chore(release): @wxt-dev/module-react v1.1.3

Co-authored-by: aklinker1 <aklinker1@users.noreply.github.com>

.github/FUNDING.yml

@@ -0,0 +1,15 @@
+# These are supported funding model platforms
+
+github: [wxt-dev] # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+polar: # Replace with a single Polar username
+buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
+thanks_dev: # Replace with a single thanks.dev username
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

.github/actions/setup/action.yml

@@ -4,6 +4,9 @@ inputs:
   install:
     default: 'true'
     description: Whether or not to run 'pnpm install'
+  installArgs:
+    default: ''
+    description: Additional args to append to "pnpm install"
 runs:
   using: composite
   steps:
@@ -17,4 +20,4 @@ runs:
     - name: Install Dependencies
       if: ${{ inputs.install == 'true' }}
       shell: bash
-      run: pnpm install
+      run: pnpm install ${{ inputs.installArgs }}

.github/workflows/release.yml

@@ -13,6 +13,8 @@ on:
           - module-solid
           - module-svelte
           - module-vue
+          - storage
+          - unocss
           - wxt
 
 jobs:

.github/workflows/sync-releases.yml

@@ -7,13 +7,14 @@ on:
         default: wxt
         type: choice
         options:
-          - wxt
-          - module-react
-          - module-vue
-          - module-svelte
-          - module-solid
           - auto-icons
           - i18n
+          - module-react
+          - module-solid
+          - module-svelte
+          - module-vue
+          - storage
+          - wxt
 
 jobs:
   sync:
@@ -21,6 +22,8 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - uses: ./.github/actions/setup
+        with:
+          installArgs: --ignore-scripts
       - run: pnpm tsx scripts/sync-releases.ts ${{ inputs.package }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/validate.yml

@@ -36,7 +36,7 @@ jobs:
       - uses: oven-sh/setup-bun@v2
       - name: pnpm test:coverage
         run: pnpm test:coverage -- --reporter=default --reporter=hanging-process
-      - uses: codecov/codecov-action@v4
+      - uses: codecov/codecov-action@v5
         env:
           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
   windows-tests:

CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+aaronklinker1@gmail.com.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

CONTRIBUTING.md

@@ -32,6 +32,7 @@ Here are some helpful commands:
 
 ```sh
 # Build WXT package
+cd packages/wxt
 pnpm build
 ```
 
@@ -144,3 +145,24 @@ pnpm dlx taze -r
 ```
 
 Configuration is in [`taze.config.ts`](./taze.config.ts).
+
+## Install Unreleased Versions
+
+This repo uses https://pkg.pr.new to publish versions of all it's packages for almost every commit. You can install them via:
+
+```sh
+npm i https://pkg.pr.new/[package-name]@[ref]
+```
+
+Or use one of the shorthands:
+
+```sh
+# Install the latest build of `wxt` from a PR:
+npm i https://pkg.pr.new/wxt@1283
+
+# Install the latest build of `@wxt-dev/module-react` on the `main` branch
+npm i https://pkg.pr.new/@wxt-dev/module-react@main
+
+# Install `@wxt-dev/storage` from a specific commit:
+npm i https://pkg.pr.new/@wxt-dev/module-react@426f907
+```

README.md

@@ -75,6 +75,12 @@ Or see the [installation guide](https://wxt.dev/guide/installation.html) to get
 - 📏 Bundle analysis
 - ⬇️ Download and bundle remote URL imports
 
+## Sponsors
+
+WXT is a [MIT-licensed](https://github.com/wxt-dev/wxt/blob/main/LICENSE) open source project with its ongoing development made possible entirely by the support of these awesome backers. If you'd like to join them, please consider [sponsoring WXT's development](https://github.com/sponsors/wxt-dev).
+
+<a href="https://github.com/sponsors/wxt-dev"><img alt="WXT Sponsors" src="https://raw.githubusercontent.com/wxt-dev/static/refs/heads/main/sponsorkit/sponsors.svg"></a>
+
 ## Contributors
 
 <!-- automd:contributors author="aklinker1" license="MIT" github="wxt-dev/wxt" -->

docs/.vitepress/components/UsingWxtSection.vue

@@ -4,11 +4,8 @@ import useListExtensionDetails, {
   ChromeExtension,
 } from '../composables/useListExtensionDetails';
 
-// Add extension IDs here. Order doesn't matter, will be sorted by weekly active users
-// During the transition from chrome.google.com/webstore to
-// chromewebstore.google.com, queue.wxt.dev might return null for your
-// extension. If it does, use "<slug>/<id>" instead of just the ID. The slug
-// can be retrieved from the URL of the item on chromewebstore.google.com
+// Add extension IDs here. Order doesn't matter, will be sorted by a combination of weekly active users and rating.
+// Change the commit message or PR title to: "docs: Added "[extension name]" to the homepage"
 const chromeExtensionIds = [
   'ocfdgncpifmegplaglcnglhioflaimkd', // GitHub: Better Line Counts
   'mgmdkjcljneegjfajchedjpdhbadklcf', // Anime Skip Player
@@ -16,7 +13,7 @@ const chromeExtensionIds = [
   'elfaihghhjjoknimpccccmkioofjjfkf', // StayFree - Website Blocker & Web Analytics
   'okifoaikfmpfcamplcfjkpdnhfodpkil', // Doozy: Ai Made Easy
   'lknmjhcajhfbbglglccadlfdjbaiifig', // tl;dv - Record, Transcribe & ChatGPT for Google Meet
-  'youtube中文配音/oglffgiaiekgeicdgkdlnlkhliajdlja', // Youtube中文配音
+  'oglffgiaiekgeicdgkdlnlkhliajdlja', // Youtube中文配音
   'agjnjboanicjcpenljmaaigopkgdnihi', // PreMiD
   'aiakblgmlabokilgljkglggnpflljdgp', // Markdown Sticky Notes
   'nomnkbngkijpffepcgbbofhcnafpkiep', // DocVersionRedirector
@@ -49,6 +46,19 @@ const chromeExtensionIds = [
   'cpaedhbidlpnbdfegakhiamfpndhjpgf', // WebChat: Chat with anyone on any website
   'fcphghnknhkimeagdglkljinmpbagone', // YouTube Auto HD + FPS
   'lpomjgbicdemjkgmbnkjncgdebogkhlb', // MultiViewer Companion
+  'ggiafipgeeaaahnjamgpjcgkdpanhddg', // Sync Watch - Watch videos together on any site
+  'nmldnjcblcihmegipecakhmnieiofmgl', // Keyword Rank Checker
+  'gppllamhaciichleihemgilcpledblpn', // YouTube Simple View - Hide distractions & more
+  'pccbghdfdnnkkbcdcibchpbffdgednkf', // Propbar - Property Data Enhancer
+  'lfknakglefggmdkjdfhhofkjnnolffkh', // Text Search Pro - Search by case and whole-word match!
+  'mbenhbocjckkbaojacmaepiameldglij', // Invoice Generator
+  'phlfhkmdofajnbhgmbmjkbkdgppgoppb', // Monthly Bill Tracker
+  'macmkmchfoclhpbncclinhjflmdkaoom', // Wandpen - Instantly improve your writing with AI
+  'lhmgechokhmdekdpgkkemoeecelcaonm', // YouTube Hider - Remove Comments By Keywords, Usernames & Tools
+  'imgheieooppmahcgniieddodaliodeeg', // QA Compass - Record standardized bug reports easily
+  'npgghjedpchajflknnbngajkjkdhncdo', // aesthetic Notion, styled
+  'hmdcmlfkchdmnmnmheododdhjedfccka', // Eye Dropper
+  'eihpmapodnppeemkhkbhikmggfojdkjd', // Cursorful - Screen Recorder with Auto Zoom
 ];
 
 const { data, err, isLoading } = useListExtensionDetails(chromeExtensionIds);

docs/.vitepress/config.ts

@@ -8,14 +8,17 @@ import {
   prepareTypedocSidebar,
 } from './utils/menus';
 import { meta, script } from './utils/head';
+import footnote from 'markdown-it-footnote';
 import { version as wxtVersion } from '../../packages/wxt/package.json';
 import { version as i18nVersion } from '../../packages/i18n/package.json';
 import { version as autoIconsVersion } from '../../packages/auto-icons/package.json';
+import { version as unocssVersion } from '../../packages/unocss/package.json';
+import { version as storageVersion } from '../../packages/storage/package.json';
 
 const title = 'Next-gen Web Extension Framework';
 const titleSuffix = ' – WXT';
 const description =
-  "WXT provides the best developer experience, making it quick, easy, and fun to develop chrome extensions for all browsers. With built-in utilities for building, zipping, and publishing your extension, it's easy to get started.";
+  "WXT provides the best developer experience, making it quick, easy, and fun to develop web extensions. With built-in utilities for building, zipping, and publishing your extension, it's easy to get started.";
 const ogTitle = `${title}${titleSuffix}`;
 const ogUrl = 'https://wxt.dev';
 const ogImage = 'https://wxt.dev/social-preview.png';
@@ -46,6 +49,12 @@ export default defineConfig({
     }),
   ],
 
+  markdown: {
+    config: (md) => {
+      md.use(footnote);
+    },
+  },
+
   themeConfig: {
     // https://vitepress.dev/reference/default-theme-config
     logo: {
@@ -53,6 +62,16 @@ export default defineConfig({
       alt: 'WXT logo',
     },
 
+    footer: {
+      message: [
+        '<a class="light-netlify" href="https://www.netlify.com"> <img src="https://www.netlify.com/v3/img/components/netlify-color-bg.svg" alt="Deploys by Netlify" style="display: inline;" /></a>',
+        '<a class="dark-netlify" href="https://www.netlify.com"> <img src="https://www.netlify.com/v3/img/components/netlify-color-accent.svg" alt="Deploys by Netlify" style="display: inline;" /></a>',
+        'Released under the <a href="https://github.com/wxt-dev/wxt/blob/main/LICENSE">MIT License</a>.',
+      ].join('<br/>'),
+      copyright:
+        'Copyright © 2023-present <a href="https://github.com/aklinker1">Aaron Klinker</a>',
+    },
+
     editLink: {
       pattern: 'https://github.com/wxt-dev/wxt/edit/main/docs/:path',
     },
@@ -79,9 +98,10 @@ export default defineConfig({
           ),
         ]),
         navItem('Other Packages', [
-          navItem(`wxt/storage — ${wxtVersion}`, '/storage'),
+          navItem(`@wxt-dev/storage — ${storageVersion}`, '/storage'),
           navItem(`@wxt-dev/auto-icons — ${autoIconsVersion}`, '/auto-icons'),
           navItem(`@wxt-dev/i18n — ${i18nVersion}`, '/i18n'),
+          navItem(`@wxt-dev/unocss — ${unocssVersion}`, '/unocss'),
         ]),
       ]),
     ],

docs/.vitepress/theme/custom.css

@@ -1,72 +1,28 @@
 /* Colors */
 :root {
-  --wxt-c-green: #53bc4a;
+  --wxt-c-green-1: #0b8a00;
+  --wxt-c-green-2: #096600;
+  --wxt-c-green-3: #096600;
+  --wxt-c-green-soft: rgba(#0b8a00 / 0.14);
+}
+
+.dark {
   --wxt-c-green-1: #67d45e;
-  --wxt-c-green-2: #4fa048;
-  --wxt-c-green-3: #447e3f;
+  --wxt-c-green-2: #329929;
+  --wxt-c-green-3: #21651b;
+  --wxt-c-green-soft: rgba(#67d45e / 0.14);
 }
 
 /* https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css */
 
 :root {
-  --vp-c-brand: var(--wxt-c-green);
   --vp-c-brand-1: var(--wxt-c-green-1);
   --vp-c-brand-2: var(--wxt-c-green-2);
   --vp-c-brand-3: var(--wxt-c-green-3);
-
-  --vp-button-brand-bg: var(--wxt-c-green);
-  --vp-button-brand-hover-bg: var(--wxt-c-green-2);
-  --vp-button-brand-active-bg: var(--wxt-c-green-3);
-
-  --vp-code-link-color: var(--wxt-c-green);
-
-  /* --vp-c-text-1: var(--wxt-c-green-1); */
-
-  --vp-button-brand-text: var(--vp-c-black);
-  --vp-button-brand-hover-text: var(--vp-c-black);
-  --vp-button-brand-active-text: var(--vp-c-black);
-
-  --vp-custom-block-tip-border: var(--wxt-c-green);
-  --vp-custom-block-tip-text: var(--wxt-c-green);
-
-  /* --vp-code-block-bg: #222422;
-  --vp-code-copy-code-bg: #313431;
-  --vp-code-copy-code-hover-bg: #3c403c; */
-
-  --vp-custom-block-tip-bg: var(--vp-code-block-bg);
-  --vp-custom-block-info-bg: var(--vp-code-block-bg);
-
-  --vp-code-color: #476582;
+  --vp-c-brand-soft: var(--wxt-c-green-soft);
 }
 
-.vp-doc a {
-  color: var(--wxt-c-green);
-}
-
-.dark {
-  --vp-c-bg: #131413;
-
-  --vp-c-bg-soft: #1a1b1a;
-  --vp-c-bg-soft-up: #1f201f;
-  --vp-c-bg-soft-down: #262926;
-  --vp-c-bg-soft-mute: #242424;
-
-  --vp-c-bg-alt: #171817;
-
-  --vp-c-default: #313136;
-  --vp-c-default-1: #3a3a3c;
-  --vp-c-default-2: #505053;
-  --vp-c-default-3: #2c2c30;
-  --vp-c-default-soft: #252529;
-
-  --vp-code-block-bg: #191a19;
-  --vp-code-copy-code-bg: #212321;
-  --vp-code-copy-code-hover-bg: #292d29;
-
-  --vp-custom-block-info-bg: #191a19;
-
-  --vp-code-color: #c9def1;
-}
+/* Customize Individual Components */
 
 .vp-doc .no-vertical-dividers th,
 .vp-doc .no-vertical-dividers td {
@@ -97,3 +53,16 @@ body {
   vertical-align: middle;
   background-color: var(--vp-c-default-2);
 }
+
+.light-netlify {
+  display: inline;
+}
+.dark .light-netlify {
+  display: none;
+}
+.dark-netlify {
+  display: none;
+}
+.dark .dark-netlify {
+  display: inline;
+}

docs/guide/essentials/assets.md

@@ -77,6 +77,84 @@ export default defineContentScript({
 
 ## WASM
 
-:::warning 🚧 Under construction
-These docs will be coming soon!
-:::
+How a `.wasm` file is loaded varies greatly between packages, but most follow a basic setup: Use a JS API to load and execute the `.wasm` file.
+
+For an extension, that means two things:
+
+1. The `.wasm` file needs to be present in output folder so it can be loaded.
+2. You must import the JS API to load and initialize the `.wasm` file, usually provided by the NPM package.
+
+For an example, let's say you have a content script needs to parse TS code into AST. We'll use [`@oxc-parser/wasm`](https://www.npmjs.com/package/@oxc-parser/wasm) to do it!
+
+First, we need to copy the `.wasm` file to the output directory. We'll do it with a [WXT module](/guide/essentials/wxt-modules):
+
+```ts
+// modules/oxc-parser-wasm.ts
+import { resolve } from 'node:path';
+
+export default defineWxtModule((wxt) => {
+  wxt.hook('build:publicAssets', (_, assets) => {
+    assets.push({
+      absoluteSrc: resolve(
+        'node_modules/@oxc-parser/wasm/web/oxc_parser_wasm_bg.wasm',
+      ),
+      relativeDest: 'oxc_parser_wasm_bg.wasm',
+    });
+  });
+});
+```
+
+Run `wxt build`, and you should see the WASM file copied into your `.output/chrome-mv3` folder!
+
+Next, since this is in a content script and we'll be fetching the WASM file over the network to load it, we need to add the file to the `web_accessible_resources`:
+
+```ts
+// wxt.config.ts
+export default defineConfig({
+  manifest: {
+    web_accessible_resources: [
+      {
+        // We'll use this matches in the cotent script as well
+        matches: ['*://*.github.com/*'],
+        // Use the same path as `relativeDest` from the WXT module
+        resources: ['/oxc_parser_wasm_bg.wasm'],
+      },
+    ],
+  },
+});
+```
+
+And finally, we need to load and initialize the `.wasm` file inside the content script to use it:
+
+```ts
+// entrypoints/content.ts
+import initWasm, { parseSync } from '@oxc-parser/wasm';
+
+export default defineContentScript({
+  matches: '*://*.github.com/*',
+  async main(ctx) {
+    if (!location.pathname.endsWith('.ts')) return;
+
+    // Get text from GitHub
+    const code = document.getElementById(
+      'read-only-cursor-text-area',
+    )?.textContent;
+    if (!code) return;
+    const sourceFilename = document.getElementById('file-name-id')?.textContent;
+    if (!sourceFilename) return;
+
+    // Load the WASM file:
+    await initWasm({
+      module_or_path: browser.runtime.getURL('/oxc_parser_wasm_bg.wasm'),
+    });
+
+    // Once loaded, we can use `parseSync`!
+    const ast = parseSync(code, { sourceFilename });
+    console.log(ast);
+  },
+});
+```
+
+This code is taken directly from `@oxc-parser/wasm` docs with one exception: We manually pass in a file path. In a standard NodeJS or web project, the default path works just fine so you don't have to pass anything in. However, extensions are different. You should always explicitly pass in the full URL to the WASM file in your output directory, which is what `browser.runtime.getURL` returns.
+
+Run your extension, and you should see OXC parse the TS file!

docs/guide/essentials/config/browser-startup.md

@@ -62,7 +62,8 @@ import { resolve } from 'node:path';
 
 export default defineRunnerConfig({
   // On Windows, the path must be absolute
-  chromiumArgs: [`--user-data-dir="${resolve(".wxt/chrome-data")}"`
+  chromiumProfile: resolve('.wxt/chrome-data'),
+  keepProfileChanges: true,
 });
 ```
 

docs/guide/essentials/config/environment-variables.md

@@ -9,6 +9,10 @@ WXT supports [dotenv files the same way as Vite](https://vite.dev/guide/env-and-
 .env.local
 .env.[mode]
 .env.[mode].local
+.env.[browser]
+.env.[browser].local
+.env.[mode].[browser]
+.env.[mode].[browser].local
 ```
 
 And any environment variables listed inside them will be available at runtime:
@@ -52,3 +56,26 @@ Vite provides two other environment variables, but they aren't useful in WXT pro
 - `import.meta.env.BASE_URL`: Use `browser.runtime.getURL` instead.
 - `import.meta.env.SSR`: Always `false`.
   :::
+
+## Manifest
+
+To use environment variables in the manifest, you need to use the function syntax:
+
+```ts
+export default defineConfig({
+  extensionApi: 'chrome',
+  modules: ['@wxt-dev/module-vue'],
+  manifest: { // [!code --]
+    oauth2: { // [!code --]
+      client_id: import.meta.env.WXT_APP_CLIENT_ID // [!code --]
+    } // [!code --]
+  } // [!code --]
+  manifest: () => ({ // [!code ++]
+    oauth2: { // [!code ++]
+      client_id: import.meta.env.WXT_APP_CLIENT_ID // [!code ++]
+    } // [!code ++]
+  }), // [!code ++]
+});
+```
+
+WXT can't load your `.env` files until after the config file has been loaded. So by using the function syntax for `manifest`, it defers creating the object until after the `.env` files are loaded into the process.

docs/guide/essentials/content-scripts.md

@@ -239,6 +239,7 @@ export default defineContentScript({
       onMount: (container) => {
         // Render your app to the UI container
         const unmount = render(() => <div>...</div>, container);
+        return unmount;
       },
       onRemove: (unmount) => {
         // Unmount the app when the UI is removed
@@ -547,16 +548,21 @@ To use `injectScript`, we need two entrypoints, one content script and one unlis
 ```ts
 // entrypoints/example-main-world.ts
 export default defineUnlistedScript(() => {
-  console.log('Hello from the main world!');
+  console.log('Hello from the main world');
 });
 ```
 
 ```ts
 // entrypoints/example.content.ts
-export default defineContentScript(async () => {
-  await injectScript('/example-main-world.js', {
-    keepInDom: true,
-  });
+export default defineContentScript({
+  matches: ['*://*/*'],
+  async main() {
+    console.log('Injecting script...');
+    await injectScript('/example-main-world.js', {
+      keepInDom: true,
+    });
+    console.log('Done!');
+  },
 });
 ```
 
@@ -570,6 +576,39 @@ For MV3, `injectScript` is synchronous and the injected script will be evaluated
 However for MV2, `injectScript` has to `fetch` the script's text content and create an inline `<script>` block. This means for MV2, your script is injected asynchronously and it will not be evaluated at the same time as your content script's `run_at`.
 :::
 
+## Mounting UI to dynamic element
+
+In many cases, you may need to mount a UI to a DOM element that does not exist at the time the web page is initially loaded. To handle this, use the `autoMount` API to automatically mount the UI when the target element appears dynamically and unmount it when the element disappears. In WXT, the `anchor` option is used to target the element, enabling automatic mounting and unmounting based on its appearance and removal.
+
+```ts
+export default defineContentScript({
+  matches: ['<all_urls>'],
+
+  main(ctx) {
+    const ui = createIntegratedUi(ctx, {
+      position: 'inline',
+      // It observes the anchor
+      anchor: '#your-target-dynamic-element',
+      onMount: (container) => {
+        // Append children to the container
+        const app = document.createElement('p');
+        app.textContent = '...';
+        container.append(app);
+      },
+    });
+
+    // Call autoMount to observe anchor element for add/remove.
+    ui.autoMount();
+  },
+});
+```
+
+:::tip
+When the `ui.remove` is called, `autoMount` also stops.
+:::
+
+See the [API Reference](/api/reference/wxt/client/interfaces/ContentScriptUi.html#automount) for the complete list of options.
+
 ## Dealing with SPAs
 
 It is difficult to write content scripts for SPAs (single page applications) and websites using HTML5 history mode for navigation because content scripts are only ran on full page reloads. SPAs and websites that take advantage of HTML5 history mode **_do not perform a full reload when changing paths_**, and thus your content script isn't going to be ran when you expect it to be.
@@ -602,7 +641,7 @@ export default defineContentScript({
   matches: ['*://*.youtube.com/*'],
   main(ctx) {
     ctx.addEventListener(window, 'wxt:locationchange', ({ newUrl }) => {
-      if (watchPattern.matches(newUrl)) mainWatch(ctx);
+      if (watchPattern.includes(newUrl)) mainWatch(ctx);
     });
   },
 });

docs/guide/essentials/entrypoints.md

@@ -304,10 +304,7 @@ Follow the [Devtools Example](https://github.com/wxt-dev/examples/tree/main/exam
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
-    <meta
-      name="viewportYou are responsible for loading/running these scripts where needed. If necessary, don't forget to add the script and/or any related stylesheets to web_accessible_resources."
-      content="width=device-width, initial-scale=1.0"
-    />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Options Title</title>
     <meta name="manifest.open_in_tab" content="true|false" />
     <meta name="manifest.chrome_style" content="true|false" />

docs/guide/essentials/es-modules.md

@@ -20,7 +20,7 @@ In your background script, set `type: "module"`:
 
 ```ts
 export default defineBackground({
-  type: 'module', // !code ++
+  type: 'module', // [!code ++]
   main() {
     // ...
   },

docs/guide/essentials/project-structure.md

@@ -35,7 +35,7 @@ Here's a brief summary of each of these files and directories:
 - `hooks/`: Auto-imported by default, contains hooks for React and Solid
 - `public/`: Contains any files you want to copy into the output folder as-is, without being processed by WXT
 - `utils/`: Auto-imported by default, contains generic utilities used throughout your project
-- `.env`: Contains [Environment Variables](/guide/essentials/config/runtime#environment-variables)
+- `.env`: Contains [Environment Variables](/guide/essentials/config/environment-variables)
 - `.env.publish`: Contains Environment Variables for [publishing](/guide/essentials/publishing)
 - `app.config.ts`: Contains [Runtime Config](/guide/essentials/config/runtime)
 - `package.json`: The standard file used by your package manager

docs/guide/essentials/publishing.md

@@ -129,7 +129,7 @@ wxt zip
 
 Firefox requires you to upload a ZIP of your source code. This allows them to rebuild your extension and review the code in a readable way. More details can be found in [Firefox's docs](https://extensionworkshop.com/documentation/publish/source-code-submission/).
 
-When running `wxt zip -b firefox`, WXT will zip both your extension and sources. Certain files (such as config files, hidden files, and tests) are automatically excluded from your sources. However, it's important to manually check the ZIP to ensure it only contains the files necessary to rebuild your extension.
+When running `wxt zip -b firefox`, WXT will zip both your extension and sources. Certain files (such as config files, hidden files, tests, and excluded entrypoints) are automatically excluded from your sources. However, it's important to manually check the ZIP to ensure it only contains the files necessary to rebuild your extension.
 
 To customize which files are zipped, add the `zip` option to your config file.
 

docs/guide/essentials/scripting.md

@@ -12,15 +12,18 @@ When using `browser.scripting.executeScript`, you can execute content scripts or
 // entrypoints/background.ts
 const res = await browser.scripting.executeScript({
   target: { tabId },
-  files: ['injected.js'],
+  files: ['content-scripts/example.js'],
 });
 console.log(res); // "Hello John!"
 ```
 
 ```ts
-// entrypoints/injected.js
-export default defineUnlistedScript(() => {
-  console.log('Script was injected!');
-  return 'Hello John!';
+// entrypoints/example.content.ts
+export default defineContentScript({
+  registration: 'runtime',
+  main(ctx) {
+    console.log('Script was executed!');
+    return 'Hello John!';
+  },
 });
 ```

docs/guide/essentials/target-different-browsers.md

@@ -4,7 +4,7 @@ When building an extension with WXT, you can create multiple builds of your exte
 
 ## Target a Browser
 
-Use the `-b` CLI flag to create a separate build of your extension for a specific browser. By default, `chrome` is targetted.
+Use the `-b` CLI flag to create a separate build of your extension for a specific browser. By default, `chrome` is targeted.
 
 ```sh
 wxt            # same as: wxt -b chrome
@@ -12,36 +12,44 @@ wxt -b firefox
 wxt -b custom
 ```
 
-Targeting a browser has several effects:
+During development, if you target Firefox, Firefox will open. All other strings open Chrome by default. To customize which browsers open, see [Set Browser Binaries](/guide/essentials/config/browser-startup#set-browser-binaries).
 
-1. During development, when passing `firefox`, WXT will automatically open Firefox with the extension installed. For all other browsers, it will open Chrome/Chromium
-2. Changes build-time constants provided by WXT:
-   - `import.meta.env.BROWSER`: A string, the targeted browser
-   - `import.meta.env.CHROME`: A boolean equivalent to `import.meta.env.BROWSER === "chrome"`
-   - `import.meta.env.FIREFOX`: A boolean equivalent to `import.meta.env.BROWSER === "firefox"`
-   - `import.meta.env.EDGE`: A boolean equivalent to `import.meta.env.BROWSER === "edge"`
-   - `import.meta.env.SAFARI`: A boolean equivalent to `import.meta.env.BROWSER === "safari"`
-   - `import.meta.env.OPERA`: A boolean equivalent to `import.meta.env.BROWSER === "opera"`
+Additionally, WXT defines several constants you can use at runtime to detect which browser is in use:
+
+```ts
+if (import.meta.env.BROWSER === 'firefox') {
+  console.log('Do something only in Firefox builds');
+}
+if (import.meta.env.FIREFOX) {
+  // Shorthand, equivalent to the if-statement above
+}
+```
+
+Read about [Built-in Environment Variables](/guide/essentials/config/environment-variables.html#built-in-environment-variables) for more details.
 
 ## Target a Manifest Version
 
 To target specific manifest versions, use the `--mv2` or `--mv3` CLI flags.
 
 :::tip Default Manifest Version
-By default, WXT will target MV2 for Safari and Firefox and MV3 for all other browers.
+By default, WXT will target MV2 for Safari and Firefox and MV3 for all other browsers.
 :::
 
-To get the target manifest version at runtime, use the built-time constant provided by WXT:
+Similar to the browser, you can get the target manifest version at runtime using the [built-in environment variable](/guide/essentials/config/environment-variables.html#built-in-environment-variables):
 
-- `import.meta.env.MANIFEST_VERSION`: A number, either `2` or `3`
+```ts
+if (import.meta.env.MANIFEST_VERSION === 2) {
+  console.log('Do something only in MV2 builds');
+}
+```
 
 ## Filtering Entrypoints
 
-Every entrypoint can be included or excluded when targetting specific browsers via the `include` and `exclude` options.
+Every entrypoint can be included or excluded when targeting specific browsers via the `include` and `exclude` options.
 
 Here are some examples:
 
-- Content script only built when targetting `firefox`:
+- Content script only built when targeting `firefox`:
 
   ```ts
   export default defineContentScript({
@@ -67,3 +75,5 @@ Here are some examples:
     </body>
   </html>
   ```
+
+Alternatively, you can use the [`filterEntrypoints` config](/api/reference/wxt/interfaces/InlineConfig#filterentrypoints) to list all the entrypoints you want to build.

docs/guide/essentials/wxt-modules.md

@@ -75,7 +75,7 @@ import { defineWxtModule } from 'wxt/modules';
 
 export default defineWxtModule({
   setup(wxt) {
-    wxt.hook('ready', () => {
+    wxt.hook('config:resolved', () => {
       wxt.config.outDir = 'dist';
     });
   },

docs/guide/introduction.md

@@ -5,11 +5,11 @@ WXT is a modern, open-source framework for building web extensions. Inspired by
 - Provide an awesome [DX](https://about.gitlab.com/topics/devops/what-is-developer-experience/)
 - Provide first-class support for all major browsers
 
-Check out the [comparison](/guide/resources/compare) to see how WXT compares to other tools for building web extnesions.
+Check out the [comparison](/guide/resources/compare) to see how WXT compares to other tools for building web extensions.
 
 ## Prerequisites
 
-These docs assume you have a basic knowledge of how Chrome extensions are structured and how you access the extension APIs.
+These docs assume you have a basic knowledge of how web extensions are structured and how you access the extension APIs.
 
 :::warning New to extension development?
 If you have never written an extension before, follow Chrome's [Hello World tutorial](https://developer.chrome.com/docs/extensions/get-started/tutorial/hello-world) to first **_create an extension without WXT_**, then come back here.

docs/guide/resources/compare.md

@@ -8,50 +8,59 @@ Lets compare the features of WXT vs [Plasmo](https://docs.plasmo.com/framework)
 - 🟡 - Partial support
 - ❌ - No support
 
-| Features                                                |       WXT        |     Plasmo      |      CRXJS       |
-| ------------------------------------------------------- | :--------------: | :-------------: | :--------------: |
-| Supports all browsers                                   |        ✅        |       ✅        | 🟡 <sup>10</sup> |
-| MV2 Support                                             |        ✅        |       ✅        | 🟡 <sup>1</sup>  |
-| MV3 Support                                             |        ✅        |       ✅        | 🟡 <sup>1</sup>  |
-| Create Extension ZIPs                                   |        ✅        |       ✅        |        ❌        |
-| Create Firefox Sources ZIP                              |        ✅        |       ❌        |        ❌        |
-| First-class TypeScript support                          |        ✅        |       ✅        |        ✅        |
-| Entrypoint discovery                                    | ✅ <sup>2</sup>  | ✅ <sup>2</sup> |        ❌        |
-| Inline entrypoint config                                |        ✅        |       ✅        | ❌ <sup>9</sup>  |
-| Auto-imports                                            |        ✅        |       ❌        |        ❌        |
-| Reusable module system                                  |        ✅        |       ❌        |        ❌        |
-| Supports all frontend frameworks                        |        ✅        | 🟡 <sup>3</sup> |        ✅        |
-| Framework specific entrypoints (like `Popup.tsx`)       | 🟡 <sup>4</sup>  | ✅ <sup>5</sup> |        ❌        |
-| Automated publishing                                    |        ✅        |       ✅        |        ❌        |
-| Remote Code Bundling (Google Analytics)                 |        ✅        |       ✅        |        ❌        |
-| Unlisted HTML Pages                                     |        ✅        |       ✅        |        ✅        |
-| Unlisted Scripts                                        |        ✅        |       ❌        |        ❌        |
-| ESM Content Scripts                                     | ❌ <sup>12</sup> |       ❌        |        ✅        |
-| <strong style="opacity: 50%">Dev Mode</strong>          |                  |                 |
-| `.env` Files                                            |        ✅        |       ✅        |        ✅        |
-| Opens browser with extension installed                  |        ✅        |       ❌        |        ❌        |
-| HMR for UIs                                             |        ✅        | 🟡 <sup>6</sup> |        ✅        |
-| Reload HTML Files on Change                             |        ✅        | 🟡 <sup>7</sup> |        ✅        |
-| Reload Content Scripts on Change                        |        ✅        | 🟡 <sup>7</sup> |        ✅        |
-| Reload Background on Change                             | 🟡 <sup>7</sup>  | 🟡 <sup>7</sup> | 🟡 <sup>7</sup>  |
-| Respects Content Script `run_at`                        |        ✅        |       ✅        | ❌ <sup>8</sup>  |
-| <strong style="opacity: 50%">Built-in Wrappers</strong> |                  |                 |                  |
-| Storage                                                 |        ✅        |       ✅        | ❌ <sup>11</sup> |
-| Messaging                                               | ❌ <sup>11</sup> |       ✅        | ❌ <sup>11</sup> |
-| Content Script UI                                       |        ✅        |       ✅        | ❌ <sup>11</sup> |
-| I18n                                                    |        ✅        |       ❌        |        ❌        |
+| Features                                                |   WXT   | Plasmo  |  CRXJS  |
+| ------------------------------------------------------- | :-----: | :-----: | :-----: |
+| Supports all browsers                                   |   ✅    |   ✅    | 🟡 [^j] |
+| MV2 Support                                             |   ✅    |   ✅    | 🟡 [^a] |
+| MV3 Support                                             |   ✅    |   ✅    | 🟡 [^a] |
+| Create Extension ZIPs                                   |   ✅    |   ✅    |   ❌    |
+| Create Firefox Sources ZIP                              |   ✅    |   ❌    |   ❌    |
+| First-class TypeScript support                          |   ✅    |   ✅    |   ✅    |
+| Entrypoint discovery                                    | ✅ [^b] | ✅ [^b] |   ❌    |
+| Inline entrypoint config                                |   ✅    |   ✅    | ❌ [^i] |
+| Auto-imports                                            |   ✅    |   ❌    |   ❌    |
+| Reusable module system                                  |   ✅    |   ❌    |   ❌    |
+| Supports all frontend frameworks                        |   ✅    | 🟡 [^c] |   ✅    |
+| Framework specific entrypoints (like `Popup.tsx`)       | 🟡 [^d] | ✅ [^e] |   ❌    |
+| Automated publishing                                    |   ✅    |   ✅    |   ❌    |
+| Remote Code Bundling (Google Analytics)                 |   ✅    |   ✅    |   ❌    |
+| Unlisted HTML Pages                                     |   ✅    |   ✅    |   ✅    |
+| Unlisted Scripts                                        |   ✅    |   ❌    |   ❌    |
+| ESM Content Scripts                                     | ❌ [^l] |   ❌    |   ✅    |
+| <strong style="opacity: 50%">Dev Mode</strong>          |         |         |         |
+| `.env` Files                                            |   ✅    |   ✅    |   ✅    |
+| Opens browser with extension installed                  |   ✅    |   ❌    |   ❌    |
+| HMR for UIs                                             |   ✅    | 🟡 [^f] |   ✅    |
+| Reload HTML Files on Change                             |   ✅    | 🟡 [^g] |   ✅    |
+| Reload Content Scripts on Change                        |   ✅    | 🟡 [^g] |   ✅    |
+| Reload Background on Change                             | 🟡 [^g] | 🟡 [^g] | 🟡 [^g] |
+| Respects Content Script `run_at`                        |   ✅    |   ✅    | ❌ [^h] |
+| <strong style="opacity: 50%">Built-in Wrappers</strong> |         |         |         |
+| Storage                                                 |   ✅    |   ✅    | ❌ [^k] |
+| Messaging                                               | ❌ [^k] |   ✅    | ❌ [^k] |
+| Content Script UI                                       |   ✅    |   ✅    | ❌ [^k] |
+| I18n                                                    |   ✅    |   ❌    |   ❌    |
 
-<small>
-  <sup>1</sup>: Either MV2 or MV3, not both.
-  <br/><sup>2</sup>: File based.
-  <br/><sup>3</sup>: Only React, Vue, and Svelte.
-  <br/><sup>4</sup>: <code>.html</code> <code>.ts</code> <code>.tsx</code>.
-  <br/><sup>5</sup>: <code>.html</code> <code>.ts</code> <code>.tsx</code>. <code>.vue</code> <code>.svelte</code>.
-  <br/><sup>6</sup>: React only.
-  <br/><sup>7</sup>: Reloads entire extension.
-  <br/><sup>8</sup>: ESM-style loaders run asynchronously.
-  <br/><sup>9</sup>: Entrypoint options all configured in <code>manifest.json</code>.
-  <br/><sup>10</sup>: As of <code>v2.0.0-beta.23</code>, but v2 stable hasn't been released yet.
-  <br/><sup>11</sup>: There is no built-in wrapper around this API. However, you can still access the standard APIs via <code>chrome</code>/<code>browser</code> globals or use any 3rd party NPM package.
-  <br/><sup>12</sup>: WIP, moving very slowly. Follow <a href="https://github.com/wxt-dev/wxt/issues/357" target="_blank"><code>wxt-dev/wxt#357</code></a> for updates.
-</small>
+[^a]: Either MV2 or MV3, not both.
+
+[^b]: File based.
+
+[^c]: Only React, Vue, and Svelte.
+
+[^d]: `.html`, `.ts`, `.tsx`.
+
+[^e]: `.html`, `.ts`, `.tsx`, `.vue`, `.svelte`.
+
+[^f]: React only.
+
+[^g]: Reloads entire extension.
+
+[^h]: ESM-style loaders run asynchronously.
+
+[^i]: Entrypoint options all configured in `manifest.json`.
+
+[^j]: As of `v2.0.0-beta.23`, but v2 stable hasn't been released yet.
+
+[^k]: There is no built-in wrapper around this API. However, you can still access the standard APIs via `chrome`/`browser` globals or use any 3rd party NPM package.
+
+[^l]: WIP, moving very slowly. Follow [wxt-dev/wxt#357](https://github.com/wxt-dev/wxt/issues/357) for updates.

docs/guide/resources/faq.md

@@ -8,9 +8,7 @@ Commonly asked questions about how to use WXT or why it behaves the way it does.
 
 [[toc]]
 
----
-
-### Why are content scripts not showing up in the manifest?
+## Why aren't content scripts added to the manifest?
 
 During development, WXT registers content scripts dynamically so they can be reloaded individually when a file is saved without reloading your entire extension.
 
@@ -19,3 +17,58 @@ To list the content scripts registered during development, open the service work
 ```js
 await chrome.scripting.getRegisteredContentScripts();
 ```
+
+## How do I disable opening the browser automatically during development?
+
+See https://wxt.dev/guide/essentials/config/browser-startup.html#disable-opening-browser
+
+## How do I stay logged into a website during development?
+
+See https://wxt.dev/guide/essentials/config/browser-startup.html#persist-data
+
+## My component library doesn't work in content scripts!
+
+Component libraries place their CSS in the document's `<head>` by default. When using `createShadowRoot`, your UI is isolated from the document's styles because it's inside a ShadowRoot.
+
+To fix this, you need to tell your component library to insert it's CSS inside the shadow root. Here's the docs for a couple of popular libraries:
+
+- React
+  - Ant Design: [`StyleProvider`](https://ant.design/docs/react/compatible-style#shadow-dom-usage)
+  - Mantine: [`MantineProvider#getRootElement` and `MantineProvider#cssVariablesSelector`](https://mantine.dev/theming/mantine-provider/)
+
+> If your library isn't listed above, try searching it's docs/issues for "shadow root", "shadow dom", or "css container".
+
+`createShadowRoot` provides it's own `<head>` element inside the shadow root, so that were you should tell the library to add the CSS. Here's an example with Ant Design:
+
+```tsx
+import { StyleProvider } from '@ant-design/cssinjs'; // [!code ++]
+import ReactDOM from 'react-dom/client';
+import App from './App.tsx';
+
+const ui = await createShadowRootUi(ctx, {
+  name: 'example-ui',
+  position: 'inline',
+  anchor: 'body',
+  onMount: (container) => { // [!code --]
+  onMount: (container, shadow) => { // [!code ++]
+    const cssContainer = shadow.querySelector("head")!; // [!code ++]
+    const root = ReactDOM.createRoot(container);
+    root.render(
+      <StyleProvider container={cssContainer}> // [!code ++]
+        <App />
+      </StyleProvider> // [!code ++]
+    );
+    return root;
+  },
+  onRemove: (root) => {
+    root?.unmount();
+  },
+});
+```
+
+Note that this doesn't effect all component libraries, just ones that inject CSS themselves rather than having you import their CSS. This approach is more prevailent in the React community, but not limited to it. That's why only React libraries are listed above. Vuetify, for example, works just fine because you import its CSS - WXT picks up on this and the CSS is added inside the shadow root automatically:
+
+```ts
+import 'vuetify/styles'; // <-- This line imports the CSS, just like importing a .css file
+import { createVuetify } from 'vuetify';
+```

docs/guide/resources/upgrading.md

@@ -109,27 +109,6 @@ You have two options:
    ```
 2. Rename your `modules` directory to something else.
 
-## v0.18.0 → v0.18.5
-
-> When this version was released, it was not considered a breaking change... but it should have been.
-
-### New `modules/` Directory
-
-WXT now recognizes the `modules/` directory as a folder containing [WXT modules](/guide/essentials/wxt-modules).
-
-If you already have `<srcDir>/modules` or `<srcDir>/Modules` directory, `wxt prepare` and other commands will fail.
-
-You have two options:
-
-1. [Recommended] Keep your files where they are and tell WXT to look in a different folder:
-   ```ts
-   // wxt.config.ts
-   export default defineConfig({
-     modulesDir: 'wxt-modules', // defaults to "modules"
-   });
-   ```
-2. Rename your `modules` directory to something else.
-
 ## v0.17.0 &rarr; v0.18.0
 
 ### Automatic MV3 `host_permissions` to MV2 `permissions`

docs/index.md

@@ -6,7 +6,7 @@ title: Next-gen Web Extension Framework
 hero:
   name: WXT
   text: Next-gen Web Extension Framework
-  tagline: An open source tool that makes Chrome Extension development faster than ever before.
+  tagline: An open source tool that makes web extension development faster than ever before.
   image:
     src: /hero-logo.svg
     alt: WXT
@@ -73,9 +73,15 @@ features:
     linkText: Read docs
 ---
 
+## Sponsors
+
+WXT is a [MIT-licensed](https://github.com/wxt-dev/wxt/blob/main/LICENSE) open source project with its ongoing development made possible entirely by the support of these awesome backers. If you'd like to join them, please consider [sponsoring WXT's development](https://github.com/sponsors/wxt-dev).
+
+<a href="https://github.com/sponsors/wxt-dev"><img alt="WXT Sponsors" src="https://raw.githubusercontent.com/wxt-dev/static/refs/heads/main/sponsorkit/sponsors-wide.svg"></a>
+
 ## Put <span style="color: var(--vp-c-brand-1)">Developer Experience</span> First
 
-WXT simplifies the chrome extension development process by providing tools for zipping and publishing, the best-in-class dev mode, an opinionated project structure, and more. Iterate faster, develop features not build scripts, and use everything the JS ecosystem has to offer.
+WXT simplifies the web extension development process by providing tools for zipping and publishing, the best-in-class dev mode, an opinionated project structure, and more. Iterate faster, develop features not build scripts, and use everything the JS ecosystem has to offer.
 
 <div style="margin: auto; width: 100%; max-width: 900px; text-align: center">
   <video src="https://github.com/wxt-dev/wxt/assets/10101283/4d678939-1bdb-495c-9c36-3aa281d84c94" controls></video>
@@ -87,7 +93,7 @@ WXT simplifies the chrome extension development process by providing tools for z
 
 ## Who's Using WXT?
 
-Battle tested and ready for production. Explore chrome extensions made with WXT.
+Battle tested and ready for production. Explore web extensions made with WXT.
 
 <ClientOnly>
   <UsingWxtSection />

docs/storage.md

@@ -6,23 +6,47 @@ outline: deep
 
 [Changelog](https://github.com/wxt-dev/wxt/blob/main/packages/wxt/CHANGELOG.md)
 
-WXT provides a simplified API to replace the `browser.storage.*` APIs. Use the `storage` auto-import from `wxt/storage` or import it manually to get started:
+A simplified wrapper around the extension storage APIs.
+
+## Installation
+
+### With WXT
+
+This module is built-in to WXT, so you don't need to install anything.
 
 ```ts
 import { storage } from 'wxt/storage';
 ```
 
-> [!IMPORTANT]
-> To use the `wxt/storage` API, the `"storage"` permission must be added to the manifest:
->
-> ```ts
-> // wxt.config.ts
-> export default defineConfig({
->   manifest: {
->     permissions: ['storage'],
->   },
-> });
-> ```
+If you use auto-imports, `storage` is auto-imported for you, so you don't even need to import it!
+
+### Without WXT
+
+Install the NPM package:
+
+```sh
+npm i @wxt-dev/storage
+pnpm add @wxt-dev/storage
+yarn add @wxt-dev/storage
+bun add @wxt-dev/storage
+```
+
+```ts
+import { storage } from '@wxt-dev/storage';
+```
+
+## Storage Permission
+
+To use the `wxt/storage` API, the `"storage"` permission must be added to the manifest:
+
+```ts
+// wxt.config.ts
+export default defineConfig({
+  manifest: {
+    permissions: ['storage'],
+  },
+});
+```
 
 ## Basic Usage
 
@@ -51,11 +75,11 @@ await storage.watch<number>(
 await storage.getMeta<{ v: number }>('local:installDate');
 ```
 
-For a full list of methods available, see the [API reference](/api/reference/wxt/storage/interfaces/WxtStorage).
+For a full list of methods available, see the [API reference](/api/reference/@wxt-dev/storage/interfaces/WxtStorage).
 
 ## Watchers
 
-To listen for storage changes, use the `storage.watch` function. It lets you setup a listener for a single key:
+To listen for storage changes, use the `storage.watch` function. It lets you set up a listener for a single key:
 
 ```ts
 const unwatch = storage.watch<number>('local:counter', (newCount, oldCount) => {
@@ -100,7 +124,7 @@ You can remove all metadata associated with a key, or just specific properties:
 // Remove all properties
 await storage.removeMeta('local:preference');
 
-// Remove one property
+// Remove only the "lastModified" property
 await storage.removeMeta('local:preference', 'lastModified');
 
 // Remove multiple properties
@@ -134,7 +158,7 @@ const unwatch = showChangelogOnUpdate.watch((newValue) => {
 });
 ```
 
-For a full list of properties and methods available, see the [API reference](/api/reference/wxt/storage/interfaces/WxtStorageItem).
+For a full list of properties and methods available, see the [API reference](/api/reference/@wxt-dev/storage/interfaces/WxtStorageItem).
 
 ### Versioning
 
@@ -225,13 +249,13 @@ export const ignoredWebsites = storage.defineItem<IgnoredWebsiteV3[]>( // [!code
 Internally, this uses a metadata property called `v` to track the value's current version.
 :::
 
-In this case, we thought that the ignored website list might change in the future, and were able to setup a versioned storage item from the start.
+In this case, we thought that the ignored website list might change in the future, and were able to set up a versioned storage item from the start.
 
-Realistically, you won't know a item needs versioned until you need to change it's schema. Thankfully, it's simple to add versioning to an unversioned storage item.
+Realistically, you won't know an item needs versioning until you need to change its schema. Thankfully, it's simple to add versioning to an unversioned storage item.
 
 When a previous version isn't found, WXT assumes the version was `1`. That means you just need to set `version: 2` and add a migration for `2`, and it will just work!
 
-Lets look at the same ignored websites example from before, but start with an unversioned item this time:
+Let's look at the same ignored websites example from before, but start with an unversioned item this time:
 
 :::code-group
 
@@ -275,13 +299,13 @@ export const ignoredWebsites = storage.defineItem<IgnoredWebsiteV2[]>( // [!code
 
 ### Running Migrations
 
-As soon as `storage.defineItem` is called, WXT checks if migrations need to be ran, and if so, runs them. Calls to get or update the storage item's value or metadata (`getValue`, `setValue`, `removeValue`, `getMeta`, etc) will automatically wait for the migration process to finish before actually reading or writing values.
+As soon as `storage.defineItem` is called, WXT checks if migrations need to be run, and if so, runs them. Calls to get or update the storage item's value or metadata (`getValue`, `setValue`, `removeValue`, `getMeta`, etc.) will automatically wait for the migration process to finish before actually reading or writing values.
 
 ### Default Values
 
 With `storage.defineItem`, there are multiple ways of defining default values:
 
-1. `fallback` - Return this value from `getValue` instead of `null` if the value is missing.
+1. **`fallback`** - Return this value from `getValue` instead of `null` if the value is missing.
 
    This option is great for providing default values for settings:
 
@@ -294,7 +318,7 @@ With `storage.defineItem`, there are multiple ways of defining default values:
    });
    ```
 
-2. `init` - Initialize and save a value in storage if it is not already saved.
+2. **`init`** - Initialize and save a value in storage if it is not already saved.
 
    This is great for values that need to be initialized or set once:
 
@@ -308,3 +332,26 @@ With `storage.defineItem`, there are multiple ways of defining default values:
    ```
 
    The value is initialized in storage immediately.
+
+## Bulk Operations
+
+When getting or setting multiple values in storage, you can perform bulk operations to improve performance by reducing the number of individual storage calls. The `storage` API provides several methods for performing bulk operations:
+
+- **`getItems`** - Get multiple values at once.
+- **`getMetas`** - Get metadata for multiple items at once.
+- **`setItems`** - Set multiple values at once.
+- **`setMetas`** - Set metadata for multiple items at once.
+- **`removeItems`** - Remove multiple values (and optionally metadata) at once.
+
+All these APIs support both string keys and defined storage items:
+
+```ts
+const userId = storage.defineItem('local:userId');
+
+await storage.setItems([
+  { key: 'local:installDate', value: Date.now() },
+  { item: userId, value: generateUserId() },
+]);
+```
+
+Refer to the [API Reference](/api/reference/@wxt-dev/storage/interfaces/WxtStorage) for types and examples of how to use all the bulk APIs.

docs/tapes/init-demo.tape

@@ -20,7 +20,7 @@ Set Framerate 50
 # Terminal theme with WXT brand colors (which was taken from the website)
 # Based on the standard charmbracelet/vhs theme:
 # https://github.com/charmbracelet/vhs/blob/88e634f4a10bbe305b6aea9a12b4d8dc3dd7f31c/style.go#L7-L28
-Set Theme {"background": "#1a1b1a", "foreground": "#dddddd", "black": "#282a2e", "brightBlack": "#4d4d4d", "red": "#D74E6F", "brightRed": "#FE5F86", "green": "#67d45e", "brightGreen": "#67d45e", "yellow": "#D3E561", "brightYellow": "#EBFF71", "blue": "#8056FF", "brightBlue": "#9B79FF", "magenta": "#ED61D7", "brightMagenta": "#FF7AEA", "cyan": "#04D7D7", "brightCyan": "#00FEFE", "white": "#bfbfbf", "brightWhite": "#e6e6e6", "indigo": "#5B56E0"}
+Set Theme {"background": "#161618", "foreground": "#dddddd", "black": "#282a2e", "brightBlack": "#4d4d4d", "red": "#D74E6F", "brightRed": "#FE5F86", "green": "#67d45e", "brightGreen": "#67d45e", "yellow": "#D3E561", "brightYellow": "#EBFF71", "blue": "#8056FF", "brightBlue": "#9B79FF", "magenta": "#ED61D7", "brightMagenta": "#FF7AEA", "cyan": "#04D7D7", "brightCyan": "#00FEFE", "white": "#bfbfbf", "brightWhite": "#e6e6e6", "indigo": "#5B56E0"}
 Set FontSize 32
 
 # Terminal settings

docs/typedoc.json

@@ -2,11 +2,18 @@
   "$schema": "https://typedoc.org/schema.json",
   "entryPointStrategy": "packages",
   "entryPoints": ["../packages/wxt"],
-  "plugin": ["typedoc-plugin-markdown", "typedoc-vitepress-theme"],
+  "plugin": [
+    "typedoc-plugin-markdown",
+    "typedoc-vitepress-theme",
+    "typedoc-plugin-frontmatter"
+  ],
   "out": "./api/reference",
   "githubPages": false,
   "excludePrivate": true,
   "excludeProtected": true,
   "excludeInternal": true,
-  "readme": "none"
+  "readme": "none",
+  "frontmatterGlobals": {
+    "editLink": false
+  }
 }

docs/unocss.md

@@ -0,0 +1 @@
+<!--@include: ../packages/unocss/README.md-->

package.json

@@ -4,7 +4,7 @@
   "engines": {
     "node": ">=18.20.3"
   },
-  "packageManager": "pnpm@9.12.0",
+  "packageManager": "pnpm@9.13.0",
   "scripts": {
     "check": "check && pnpm -r --sequential run check",
     "test": "pnpm -r --sequential run test run",
@@ -20,23 +20,25 @@
     "@aklinker1/buildc": "^1.1.4",
     "@aklinker1/check": "^1.4.5",
     "@types/fs-extra": "^11.0.4",
-    "@vitest/coverage-v8": "^2.1.2",
+    "@vitest/coverage-v8": "^2.1.4",
     "changelogen": "^0.5.7",
     "consola": "^3.2.3",
     "fast-glob": "^3.3.2",
     "fs-extra": "^11.2.0",
     "lint-staged": "^15.2.10",
-    "nano-spawn": "^0.1.0",
+    "markdown-it-footnote": "^4.0.0",
+    "nano-spawn": "^0.2.0",
     "prettier": "^3.3.3",
     "simple-git-hooks": "^2.11.1",
     "tsx": "4.15.7",
     "typedoc": "^0.25.4",
+    "typedoc-plugin-frontmatter": "^1.1.0",
     "typedoc-plugin-markdown": "4.0.0-next.23",
     "typedoc-vitepress-theme": "1.0.0-next.3",
-    "typescript": "^5.6.2",
-    "vitepress": "^1.3.4",
+    "typescript": "^5.6.3",
+    "vitepress": "^1.5.0",
     "vitest-mock-extended": "^2.0.2",
-    "vue": "^3.5.11",
+    "vue": "^3.5.12",
     "wxt": "workspace:*"
   },
   "simple-git-hooks": {
@@ -51,6 +53,9 @@
         "@algolia/client-search",
         "search-insights"
       ]
+    },
+    "patchedDependencies": {
+      "markdown-it-footnote": "patches/markdown-it-footnote.patch"
     }
   }
 }

packages/auto-icons/README.md

@@ -41,4 +41,4 @@ export default defineConfig({
 });
 ```
 
-Options have JSDocs available in your editor, or you can read them in the source code: [`AutoIconsOptions`](./src/index.ts).
+Options have JSDocs available in your editor, or you can read them in the source code: [`AutoIconsOptions`](https://github.com/wxt-dev/wxt/blob/main/packages/auto-icons/src/index.ts).

packages/auto-icons/package.json

@@ -46,9 +46,9 @@
   },
   "devDependencies": {
     "@aklinker1/check": "^1.4.5",
-    "oxlint": "^0.9.9",
-    "publint": "^0.2.11",
-    "typescript": "^5.6.2",
+    "oxlint": "^0.11.1",
+    "publint": "^0.2.12",
+    "typescript": "^5.6.3",
     "unbuild": "^2.0.0",
     "wxt": "workspace:*"
   },

packages/i18n/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## v0.2.3
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/i18n-v0.2.2...i18n-v0.2.3)
+
+### 🩹 Fixes
+
+- Prevent app crashes from parse errors due to incomplete file saves ([#1114](https://github.com/wxt-dev/wxt/pull/1114))
+
+### 📖 Documentation
+
+- Cleanup typos and broken links ([bb5ea34](https://github.com/wxt-dev/wxt/commit/bb5ea34))
+
+### ❤️ Contributors
+
+- Bread Grocery <breadgrocery@gmail.com>
+- Aaron ([@aklinker1](http://github.com/aklinker1))
+
+## v0.2.2
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/i18n-v0.2.1...i18n-v0.2.2)
+
+### 🚀 Enhancements
+
+- Add support for configuring the `locales` directory ([#1109](https://github.com/wxt-dev/wxt/pull/1109))
+
+### ❤️ Contributors
+
+- Bread Grocery <breadgrocery@gmail.com>
+
 ## v0.2.1
 
 [compare changes](https://github.com/wxt-dev/wxt/compare/i18n-v0.2.0...i18n-v0.2.1)

packages/i18n/README.md

@@ -98,6 +98,21 @@ And you're done! Using WXT, you get type-safety out of the box.
    i18n.t('helloWorld'); // "Hello world!";
    ```
 
+## Configuration
+
+The module can be configured via the `i18n` config:
+
+```ts
+export default defineConfig({
+  modules: ['@wxt-dev/i18n'],
+  i18n: {
+    // ...
+  },
+});
+```
+
+Options have JSDocs available in your editor, or you can read them in the source code: [`I18nOptions`](https://github.com/wxt-dev/wxt/blob/main/packages/i18n/src/module.ts).
+
 ## Messages File Format
 
 > [!DANGER]
@@ -225,11 +240,11 @@ A key is treated as "verbose" when it is:
 {
   "appName": {
     "message": "GitHub - Better Line Counts",
-    "description": "The app's name, should not be translated",
+    "description": "The app's name, should not be translated"
   },
   "ok": "OK",
   "deleteConfirmation": {
-    "title": "Delete XYZ?"
+    "title": "Delete XYZ?",
     "message": "You cannot undo this action once taken."
   }
 }
@@ -289,7 +304,7 @@ const messages = {
   // ...
 };
 
-// Generate JSON files for the browser
+// Generate JSON files for the extension
 await generateChromeMessagesFile('dist/_locales/en/messages.json', messages.en);
 await generateChromeMessagesFile('dist/_locales/de/messages.json', messages.de);
 // ...

packages/i18n/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wxt-dev/i18n",
   "description": "Type-safe wrapper around browser.i18n.getMessage with additional features",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "type": "module",
   "repository": {
     "type": "git",
@@ -26,7 +26,7 @@
   },
   "dependencies": {
     "chokidar": "^3.6.0",
-    "confbox": "^0.1.7",
+    "confbox": "^0.1.8",
     "fast-glob": "^3.3.2"
   },
   "peerDependencies": {
@@ -39,13 +39,13 @@
   },
   "devDependencies": {
     "@aklinker1/check": "^1.4.5",
-    "@types/chrome": "^0.0.268",
-    "@types/node": "^20.16.10",
-    "oxlint": "^0.9.9",
-    "publint": "^0.2.11",
-    "typescript": "^5.6.2",
+    "@types/chrome": "^0.0.280",
+    "@types/node": "^20.17.6",
+    "oxlint": "^0.11.1",
+    "publint": "^0.2.12",
+    "typescript": "^5.6.3",
     "unbuild": "^2.0.0",
-    "vitest": "^2.0.0",
+    "vitest": "^2.1.4",
     "vitest-plugin-random-seed": "^1.1.0",
     "wxt": "workspace:*"
   },

packages/i18n/src/module.ts

@@ -23,11 +23,11 @@ import { watch } from 'chokidar';
 import { GeneratedPublicFile, WxtDirFileEntry } from 'wxt';
 import { writeFile } from 'node:fs/promises';
 
-export default defineWxtModule({
+export default defineWxtModule<I18nOptions>({
   name: '@wxt-dev/i18n',
+  configKey: 'i18n',
   imports: [{ from: '#i18n', name: 'i18n' }],
-
-  setup(wxt) {
+  setup(wxt, options) {
     if (wxt.config.manifest.default_locale == null) {
       wxt.logger.warn(
         `\`[i18n]\` manifest.default_locale not set, \`@wxt-dev/i18n\` disabled.`,
@@ -38,9 +38,12 @@ export default defineWxtModule({
       '`[i18n]` Default locale: ' + wxt.config.manifest.default_locale,
     );
 
+    const { localesDir = resolve(wxt.config.srcDir, 'locales') } =
+      options ?? {};
+
     const getLocalizationFiles = async () => {
-      const files = await glob('locales/*', {
-        cwd: wxt.config.srcDir,
+      const files = await glob('*.{json,json5,yml,yaml,toml}', {
+        cwd: localesDir,
         absolute: true,
       });
       return files.map((file) => ({
@@ -71,7 +74,7 @@ export default defineWxtModule({
       )!;
       if (defaultLocaleFile == null) {
         throw Error(
-          `\`[i18n]\` Required localization file does not exist: \`<srcDir>/locales/${wxt.config.manifest.default_locale}.{json|json5|yml|yaml|toml}\``,
+          `\`[i18n]\` Required localization file does not exist: \`<localesDir>/${wxt.config.manifest.default_locale}.{json|json5|yml|yaml|toml}\``,
         );
       }
 
@@ -154,9 +157,28 @@ export { type GeneratedI18nStructure }
 
     if (wxt.config.command === 'serve') {
       wxt.hooks.hookOnce('build:done', () => {
-        const watcher = watch(resolve(wxt.config.srcDir, 'locales'));
-        watcher.on('change', updateLocalizations);
+        const watcher = watch(localesDir);
+        watcher.on('change', (path) => {
+          updateLocalizations(path).catch(wxt.logger.error);
+        });
       });
     }
   },
 });
+
+/**
+ * Options for the i18n module
+ */
+export interface I18nOptions {
+  /**
+   * Directory containing files that define the translations.
+   * @default "${config.srcDir}/locales"
+   */
+  localesDir?: string;
+}
+
+declare module 'wxt' {
+  export interface InlineConfig {
+    i18n?: I18nOptions;
+  }
+}

packages/module-react/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## v1.1.3
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/module-react-v1.1.2...module-react-v1.1.3)
+
+### 🩹 Fixes
+
+- Use react 19 in `@wxt-dev/module-react` and `templates/react` ([#1285](https://github.com/wxt-dev/wxt/pull/1285))
+
+### ❤️ Contributors
+
+- Aaron ([@aklinker1](http://github.com/aklinker1))
+
+## v1.1.2
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/module-react-v1.1.1...module-react-v1.1.2)
+
+### 🩹 Fixes
+
+- Use `config:resolved` hook to update config instead of `ready` ([#1178](https://github.com/wxt-dev/wxt/pull/1178))
+
+### 🏡 Chore
+
+- Add  `oxlint` for linting ([#947](https://github.com/wxt-dev/wxt/pull/947))
+- Upgrade all non-major dependencies ([#1040](https://github.com/wxt-dev/wxt/pull/1040))
+- **deps:** Upgrade all non-major dependencies ([#1164](https://github.com/wxt-dev/wxt/pull/1164))
+
+### ❤️ Contributors
+
+- Aaron ([@aklinker1](http://github.com/aklinker1))
+
 ## v1.1.1
 
 [compare changes](https://github.com/wxt-dev/wxt/compare/module-react-v1.1.0...module-react-v1.1.1)

packages/module-react/modules/react.ts

@@ -15,7 +15,7 @@ export default defineWxtModule<ReactModuleOptions>({
     addImportPreset(wxt, 'react');
 
     // Enable auto-imports for JSX files
-    wxt.hooks.hook('ready', (wxt) => {
+    wxt.hook('config:resolved', (wxt) => {
       if (wxt.config.imports === false) return;
 
       wxt.config.imports.dirsScanOptions ??= {};

packages/module-react/package.json

@@ -17,7 +17,7 @@
     "email": "aaronklinker1+wxt@gmail.com"
   },
   "license": "MIT",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
@@ -44,19 +44,19 @@
     "prepare": "buildc --deps-only -- wxt prepare"
   },
   "peerDependencies": {
-    "wxt": ">=0.18.6"
+    "wxt": ">=0.19.16"
   },
   "dependencies": {
-    "@vitejs/plugin-react": "^4.3.2"
+    "@vitejs/plugin-react": "^4.3.4"
   },
   "devDependencies": {
     "@aklinker1/check": "^1.4.5",
-    "@types/react": "^18.3.11",
-    "@types/react-dom": "^18.3.0",
-    "publint": "^0.2.11",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
-    "typescript": "^5.6.2",
+    "@types/react": "^19.0.1",
+    "@types/react-dom": "^19.0.2",
+    "publint": "^0.2.12",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "^5.6.3",
     "unbuild": "^2.0.0",
     "wxt": "workspace:*"
   }

packages/module-solid/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## v1.1.3
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/module-solid-v1.1.2...module-solid-v1.1.3)
+
+### 🩹 Fixes
+
+- Use `config:resolved` hook to update config instead of `ready` ([#1178](https://github.com/wxt-dev/wxt/pull/1178))
+
+### 🏡 Chore
+
+- Add  `oxlint` for linting ([#947](https://github.com/wxt-dev/wxt/pull/947))
+- Upgrade all non-major dependencies ([#1040](https://github.com/wxt-dev/wxt/pull/1040))
+- **deps:** Upgrade all non-major dependencies ([#1164](https://github.com/wxt-dev/wxt/pull/1164))
+
+### ❤️ Contributors
+
+- Aaron ([@aklinker1](http://github.com/aklinker1))
+
 ## v1.1.2
 
 [compare changes](https://github.com/wxt-dev/wxt/compare/module-solid-v1.1.1...module-solid-v1.1.2)

packages/module-solid/modules/solid.ts

@@ -18,7 +18,7 @@ export default defineWxtModule<SolidModuleOptions>({
     addImportPreset(wxt, 'solid-js');
 
     // Enable auto-imports for JSX files
-    wxt.hooks.hook('ready', (wxt) => {
+    wxt.hook('config:resolved', (wxt) => {
       if (wxt.config.imports === false) return;
 
       wxt.config.imports.dirsScanOptions ??= {};

packages/module-solid/package.json

@@ -17,7 +17,7 @@
     "email": "aaronklinker1+wxt@gmail.com"
   },
   "license": "MIT",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
@@ -44,16 +44,16 @@
     "prepare": "buildc --deps-only -- wxt prepare"
   },
   "peerDependencies": {
-    "wxt": ">=0.18.6"
+    "wxt": ">=0.19.16"
   },
   "dependencies": {
     "vite-plugin-solid": "^2.10.2"
   },
   "devDependencies": {
     "@aklinker1/check": "^1.4.5",
-    "publint": "^0.2.11",
-    "solid-js": "^1.9.1",
-    "typescript": "^5.6.2",
+    "publint": "^0.2.12",
+    "solid-js": "^1.9.3",
+    "typescript": "^5.6.3",
     "unbuild": "^2.0.0",
     "wxt": "workspace:*"
   }

packages/module-svelte/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Changelog
 
+## v2.0.2
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/module-svelte-v2.0.1...module-svelte-v2.0.2)
+
+### 🩹 Fixes
+
+- Svelte production errors and warnings on resolve conditions ([#1283](https://github.com/wxt-dev/wxt/pull/1283))
+
+### ❤️ Contributors
+
+- Aaron ([@aklinker1](http://github.com/aklinker1))
+
+## v2.0.1
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/module-svelte-v2.0.0...module-svelte-v2.0.1)
+
+### 🩹 Fixes
+
+- Modify dev `vite.resolve.conditions` to support Vite 6 + Svelte 5 ([#1230](https://github.com/wxt-dev/wxt/pull/1230))
+
+### 🏡 Chore
+
+- **deps:** Upgrade all non-major dependencies ([#1164](https://github.com/wxt-dev/wxt/pull/1164))
+
+### ❤️ Contributors
+
+- Aaron ([@aklinker1](http://github.com/aklinker1))
+
+## v2.0.0
+
+[⚠️ breaking changes](https://wxt.dev/guide/upgrade-guide/wxt) • [compare changes](https://github.com/wxt-dev/wxt/compare/module-svelte-v1.0.1...module-svelte-v2.0.0)
+
+### 🚀 Enhancements
+
+- ⚠️  Svelte 5 support ([#1104](https://github.com/wxt-dev/wxt/pull/1104))
+
+### 🏡 Chore
+
+- Add  `oxlint` for linting ([#947](https://github.com/wxt-dev/wxt/pull/947))
+- Upgrade all non-major dependencies ([#1040](https://github.com/wxt-dev/wxt/pull/1040))
+
+#### ⚠️ Breaking Changes
+
+Upgraded `@sveltejs/vite-plugin-svelte` from v3 to v4. This drops support for Svelte 4 and below. To continue using older versions of Svelte, use v1 of this module.
+
+To upgrade to svelte 5, just install `svelte@5`.
+
+### ❤️ Contributors
+
+- Aaron ([@aklinker1](http://github.com/aklinker1))
+
 ## v1.0.1
 
 [compare changes](https://github.com/wxt-dev/wxt/compare/module-svelte-v1.0.0...module-svelte-v1.0.1)

packages/module-svelte/package.json

@@ -17,7 +17,7 @@
     "email": "aaronklinker1+wxt@gmail.com"
   },
   "license": "MIT",
-  "version": "1.0.1",
+  "version": "2.0.2",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
@@ -42,15 +42,16 @@
     "check": "pnpm build && check"
   },
   "peerDependencies": {
-    "wxt": ">=0.18.6"
+    "wxt": ">=0.18.6",
+    "svelte": ">=5"
   },
   "dependencies": {
-    "@sveltejs/vite-plugin-svelte": "^3.1.2"
+    "@sveltejs/vite-plugin-svelte": "^4.0.0"
   },
   "devDependencies": {
     "@aklinker1/check": "^1.4.5",
-    "publint": "^0.2.11",
-    "typescript": "^5.6.2",
+    "publint": "^0.2.12",
+    "typescript": "^5.6.3",
     "unbuild": "^2.0.0",
     "wxt": "workspace:*"
   }

packages/module-svelte/src/index.ts

@@ -12,7 +12,7 @@ export default defineWxtModule<SvelteModuleOptions>({
   setup(wxt, options) {
     const { vite } = options ?? {};
 
-    addViteConfig(wxt, () => ({
+    addViteConfig(wxt, ({ mode }) => ({
       plugins: [
         svelte({
           // Using a svelte.config.js file causes a segmentation fault when importing the file
@@ -21,6 +21,9 @@ export default defineWxtModule<SvelteModuleOptions>({
           ...vite,
         }),
       ],
+      resolve: {
+        conditions: ['browser', mode],
+      },
     }));
 
     addImportPreset(wxt, 'svelte');

packages/module-vue/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## v1.0.2
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/module-vue-v1.0.1...module-vue-v1.0.2)
+
+### 🩹 Fixes
+
+- Use `config:resolved` hook to update config instead of `ready` ([#1178](https://github.com/wxt-dev/wxt/pull/1178))
+
+### 🏡 Chore
+
+- Add  `oxlint` for linting ([#947](https://github.com/wxt-dev/wxt/pull/947))
+- **deps:** Bump @vitejs/plugin-vue from 5.1.1 to 5.1.4 ([#1020](https://github.com/wxt-dev/wxt/pull/1020))
+- Upgrade all non-major dependencies ([#1040](https://github.com/wxt-dev/wxt/pull/1040))
+- **deps:** Upgrade all non-major dependencies ([#1164](https://github.com/wxt-dev/wxt/pull/1164))
+
+### ❤️ Contributors
+
+- Aaron ([@aklinker1](http://github.com/aklinker1))
+
 ## v1.0.1
 
 [compare changes](https://github.com/wxt-dev/wxt/compare/module-vue-v1.0.0...module-vue-v1.0.1)

packages/module-vue/package.json

@@ -17,7 +17,7 @@
     "email": "aaronklinker1+wxt@gmail.com"
   },
   "license": "MIT",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
@@ -42,15 +42,15 @@
     "check": "pnpm build && check"
   },
   "peerDependencies": {
-    "wxt": ">=0.18.6"
+    "wxt": ">=0.19.16"
   },
   "dependencies": {
-    "@vitejs/plugin-vue": "^5.1.4"
+    "@vitejs/plugin-vue": "^5.2.0"
   },
   "devDependencies": {
     "@aklinker1/check": "^1.4.5",
-    "publint": "^0.2.11",
-    "typescript": "^5.6.2",
+    "publint": "^0.2.12",
+    "typescript": "^5.6.3",
     "unbuild": "^2.0.0",
     "wxt": "workspace:*"
   }

packages/module-vue/src/index.ts

@@ -19,7 +19,7 @@ export default defineWxtModule<VueModuleOptions>({
     }));
 
     // Enable auto-imports in template files
-    wxt.hooks.hook('ready', (wxt) => {
+    wxt.hook('config:resolved', (wxt) => {
       if (!wxt.config.imports) return;
 
       wxt.config.imports.addons ??= {};

packages/storage/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+## v1.0.1
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/storage-v1.0.0...storage-v1.0.1)
+
+### 🩹 Fixes
+
+- Use `browser` for mv2 storage ([#1200](https://github.com/wxt-dev/wxt/pull/1200))
+
+### 📖 Documentation
+
+- Cleanup changelog ([f5b7f7e](https://github.com/wxt-dev/wxt/commit/f5b7f7e))
+
+### 🏡 Chore
+
+- Init changelog for storage package ([6fc227b](https://github.com/wxt-dev/wxt/commit/6fc227b))
+
+### ❤️ Contributors
+
+- Aaron ([@aklinker1](http://github.com/aklinker1))
+
+## v1.0.0
+
+Extracted `wxt/storage` into it's own package, `@wxt-dev/storage`!
+
+It's still shipped inside WXT and accessible via `wxt/storage`, but now:
+
+- Non-WXT projects can use the storage wrapper.
+- We can make breaking changes to the API separately.
+
+[Read the docs](https://wxt.dev/storage.html) for more details.
+
+> This is apart of the v1.0 initiative for WXT.

packages/storage/README.md

@@ -0,0 +1,36 @@
+# WXT Storage
+
+[Changelog](https://github.com/wxt-dev/wxt/blob/main/packages/storage/CHANGELOG.md) • [Docs](https://wxt.dev/storage.html)
+
+A simplified wrapper around the extension storage APIs.
+
+## Installation
+
+### With WXT
+
+This module is built-in to WXT, so you don't need to install anything.
+
+```ts
+import { storage } from 'wxt/storage';
+```
+
+If you use auto-imports, `storage` is auto-imported for you, so you don't even need to import it!
+
+### Without WXT
+
+Install the NPM package:
+
+```sh
+npm i @wxt-dev/storage
+pnpm add @wxt-dev/storage
+yarn add @wxt-dev/storage
+bun add @wxt-dev/storage
+```
+
+```ts
+import { storage } from '@wxt-dev/storage';
+```
+
+## Usage
+
+Read full docs on the [documentation website](https://wxt.dev/storage.html).

packages/storage/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@wxt-dev/storage",
+  "description": "Web extension storage API provided by WXT, supports all browsers.",
+  "version": "1.0.1",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wxt-dev/wxt.git",
+    "directory": "packages/storage"
+  },
+  "homepage": "https://wxt.dev/storage.html",
+  "keywords": [
+    "wxt",
+    "storage",
+    "extension",
+    "addon",
+    "chrome",
+    "firefox",
+    "edge"
+  ],
+  "author": {
+    "name": "Aaron Klinker",
+    "email": "aaronklinker1+wxt@gmail.com"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "buildc -- unbuild",
+    "check": "buildc --deps-only -- check",
+    "test": "buildc --deps-only -- vitest"
+  },
+  "dependencies": {
+    "async-mutex": "^0.5.0",
+    "dequal": "^2.0.3"
+  },
+  "devDependencies": {
+    "@aklinker1/check": "^1.4.5",
+    "@types/chrome": "^0.0.268",
+    "@webext-core/fake-browser": "^1.3.1",
+    "oxlint": "^0.9.9",
+    "publint": "^0.2.11",
+    "typescript": "^5.6.2",
+    "unbuild": "^2.0.0",
+    "vitest": "^2.0.0"
+  },
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ]
+}

packages/storage/src/__tests__/index.test.ts

@@ -1,7 +1,6 @@
 import { fakeBrowser } from '@webext-core/fake-browser';
 import { describe, it, expect, beforeEach, vi, expectTypeOf } from 'vitest';
-import { browser } from 'wxt/browser';
-import { WxtStorageItem, storage } from '../storage';
+import { MigrationError, type WxtStorageItem, storage } from '../index';
 
 /**
  * This works because fakeBrowser is synchronous, and is will finish any number of chained
@@ -38,7 +37,7 @@ describe('Storage Utils', () => {
           expect(actual).toBe(expected);
         });
 
-        it('should return the value if multiple : are use in the key', async () => {
+        it('should return the value if multiple : are used in the key', async () => {
           const expected = 'value';
           await fakeBrowser.storage[storageArea].set({ 'some:key': expected });
 
@@ -64,27 +63,97 @@ describe('Storage Utils', () => {
       });
 
       describe('getItems', () => {
-        it('should return an array of values', async () => {
-          const expected = [
-            { key: `${storageArea}:count`, value: 234 },
-            { key: `${storageArea}:installDate`, value: null },
-            { key: `${storageArea}:otherValue`, value: 345 },
-          ] as const;
-          const params = [
-            expected[0].key,
-            expected[1].key,
-            {
-              key: expected[2].key,
-              options: { defaultValue: expected[2].value },
-            },
-          ];
+        it('should get values from multiple storage keys', async () => {
+          const item1 = {
+            key: `${storageArea}:one`,
+            expectedValue: 1,
+          } as const;
+          const item2 = {
+            key: `${storageArea}:two`,
+            expectedValue: null,
+          } as const;
+
           await fakeBrowser.storage[storageArea].set({
-            count: expected[0].value,
+            one: item1.expectedValue,
           });
 
-          const actual = await storage.getItems(params);
+          const actual = await storage.getItems([item1.key, item2.key]);
 
-          expect(actual).toEqual(expected);
+          expect(actual).toEqual([
+            { key: item1.key, value: item1.expectedValue },
+            { key: item2.key, value: item2.expectedValue },
+          ]);
+        });
+
+        it('should get values from multiple storage items', async () => {
+          const item1 = storage.defineItem(`${storageArea}:one`);
+          const expectedValue1 = 1;
+          const item2 = storage.defineItem(`${storageArea}:two`);
+          const expectedValue2 = null;
+
+          await fakeBrowser.storage[storageArea].set({
+            one: expectedValue1,
+          });
+
+          const actual = await storage.getItems([item1, item2]);
+
+          expect(actual).toEqual([
+            { key: item1.key, value: expectedValue1 },
+            { key: item2.key, value: expectedValue2 },
+          ]);
+        });
+
+        it('should get values for a combination of different input types', async () => {
+          const key1 = `${storageArea}:one` as const;
+          const expectedValue1 = 1;
+          const item2 = storage.defineItem<number>(`${storageArea}:two`);
+          const expectedValue2 = 2;
+
+          await fakeBrowser.storage[storageArea].set({
+            one: expectedValue1,
+            two: expectedValue2,
+          });
+
+          const actual = await storage.getItems([key1, item2]);
+
+          expect(actual).toEqual([
+            { key: key1, value: expectedValue1 },
+            { key: item2.key, value: expectedValue2 },
+          ]);
+        });
+
+        it('should return fallback values for keys when provided', async () => {
+          const key1 = `${storageArea}:one` as const;
+          const expectedValue1 = null;
+          const key2 = `${storageArea}:two` as const;
+          const fallback2 = 2;
+          const expectedValue2 = fallback2;
+
+          const actual = await storage.getItems([
+            key1,
+            { key: key2, options: { fallback: fallback2 } },
+          ]);
+
+          expect(actual).toEqual([
+            { key: key1, value: expectedValue1 },
+            { key: key2, value: expectedValue2 },
+          ]);
+        });
+
+        it('should return fallback values for items when provided', async () => {
+          const item1 = storage.defineItem<number>(`${storageArea}:one`);
+          const expectedValue1 = null;
+          const item2 = storage.defineItem(`${storageArea}:two`, {
+            fallback: 2,
+          });
+          const expectedValue2 = item2.fallback;
+
+          const actual = await storage.getItems([item1, item2]);
+
+          expect(actual).toEqual([
+            { key: item1.key, value: expectedValue1 },
+            { key: item2.key, value: expectedValue2 },
+          ]);
         });
       });
 
@@ -153,7 +222,7 @@ describe('Storage Utils', () => {
       describe('setMeta', () => {
         it('should set metadata at key+$', async () => {
           const existing = { v: 1 };
-          await browser.storage[storageArea].set({ count$: existing });
+          await chrome.storage[storageArea].set({ count$: existing });
           const newValues = {
             date: Date.now(),
           };
@@ -169,7 +238,7 @@ describe('Storage Utils', () => {
           'should remove any properties set to %s',
           async (version) => {
             const existing = { v: 1 };
-            await browser.storage[storageArea].set({ count$: existing });
+            await chrome.storage[storageArea].set({ count$: existing });
             const expected = {};
 
             await storage.setMeta(`${storageArea}:count`, { v: version });
@@ -180,6 +249,74 @@ describe('Storage Utils', () => {
         );
       });
 
+      describe('setMetas', () => {
+        it('should set key metadata correctly', async () => {
+          const key1 = `${storageArea}:one` as const;
+          const initialMeta1 = {};
+          const setMeta1 = { v: 1 };
+          const expectedMeta1 = setMeta1;
+
+          const key2 = `${storageArea}:two` as const;
+          const initialMeta2 = { v: 1 };
+          const setMeta2 = { v: 2 };
+          const expectedMeta2 = setMeta2;
+
+          const key3 = `${storageArea}:three` as const;
+          const initialMeta3 = { v: 1 };
+          const setMeta3 = { d: Date.now() };
+          const expectedMeta3 = { ...initialMeta3, ...setMeta3 };
+
+          await fakeBrowser.storage[storageArea].set({
+            one$: initialMeta1,
+            two$: initialMeta2,
+            three$: initialMeta3,
+          });
+
+          await storage.setMetas([
+            { key: key1, meta: setMeta1 },
+            { key: key2, meta: setMeta2 },
+            { key: key3, meta: setMeta3 },
+          ]);
+
+          expect(await storage.getMeta(key1)).toEqual(expectedMeta1);
+          expect(await storage.getMeta(key2)).toEqual(expectedMeta2);
+          expect(await storage.getMeta(key3)).toEqual(expectedMeta3);
+        });
+
+        it('should set item metadata correctly', async () => {
+          const item1 = storage.defineItem(`${storageArea}:one`);
+          const initialMeta1 = {};
+          const setMeta1 = { v: 1 };
+          const expectedMeta1 = setMeta1;
+
+          const item2 = storage.defineItem(`${storageArea}:two`);
+          const initialMeta2 = { v: 1 };
+          const setMeta2 = { v: 2 };
+          const expectedMeta2 = setMeta2;
+
+          const item3 = storage.defineItem(`${storageArea}:three`);
+          const initialMeta3 = { v: 1 };
+          const setMeta3 = { d: Date.now() };
+          const expectedMeta3 = { ...initialMeta3, ...setMeta3 };
+
+          await fakeBrowser.storage[storageArea].set({
+            one$: initialMeta1,
+            two$: initialMeta2,
+            three$: initialMeta3,
+          });
+
+          await storage.setMetas([
+            { item: item1, meta: setMeta1 },
+            { item: item2, meta: setMeta2 },
+            { item: item3, meta: setMeta3 },
+          ]);
+
+          expect(await item1.getMeta()).toEqual(expectedMeta1);
+          expect(await item2.getMeta()).toEqual(expectedMeta2);
+          expect(await item3.getMeta()).toEqual(expectedMeta3);
+        });
+      });
+
       describe('removeItem', () => {
         it('should remove the key from storage', async () => {
           await fakeBrowser.storage[storageArea].set({ count: 456 });
@@ -219,29 +356,136 @@ describe('Storage Utils', () => {
       });
 
       describe('removeItems', () => {
-        it('should remove multiple items', async () => {
+        it('should remove multiple keys', async () => {
           const key1 = `${storageArea}:one` as const;
           const key2 = `${storageArea}:two` as const;
-          const key3 = `${storageArea}:three` as const;
           await fakeBrowser.storage[storageArea].set({
-            ['one']: '1',
-            ['two']: null,
-            ['two$']: { v: 1 },
-            ['three']: '1',
-            ['three$']: { v: 1 },
+            one: 1,
+            two: 2,
+          });
+
+          await storage.removeItems([key1, key2]);
+
+          expect(await storage.getItem(key1)).toBeNull();
+          expect(await storage.getItem(key2)).toBeNull();
+        });
+
+        it('should remove multiple keys and metadata when requested', async () => {
+          const key1 = `${storageArea}:one` as const;
+          const key2 = `${storageArea}:two` as const;
+          await fakeBrowser.storage[storageArea].set({
+            one: 1,
+            one$: { v: 1 },
+            two: 2,
+            two$: { v: 1 },
           });
 
           await storage.removeItems([
             key1,
-            key2,
-            { key: key3, options: { removeMeta: true } },
+            { key: key2, options: { removeMeta: true } },
           ]);
 
           expect(await storage.getItem(key1)).toBeNull();
+          expect(await storage.getMeta(key1)).toEqual({ v: 1 });
           expect(await storage.getItem(key2)).toBeNull();
-          expect(await storage.getMeta(key2)).toEqual({ v: 1 });
-          expect(await storage.getItem(key3)).toBeNull();
-          expect(await storage.getMeta(key3)).toEqual({});
+          expect(await storage.getMeta(key2)).toEqual({});
+        });
+
+        it('should remove multiple items', async () => {
+          const item1 = storage.defineItem(`${storageArea}:one`);
+          const item2 = storage.defineItem(`${storageArea}:two`);
+          await fakeBrowser.storage[storageArea].set({
+            one: 1,
+            two: 2,
+          });
+
+          await storage.removeItems([item1, item2]);
+
+          expect(await item1.getValue()).toBeNull();
+          expect(await item2.getValue()).toBeNull();
+        });
+
+        it('should remove multiple items and metadata when requested', async () => {
+          const item1 = storage.defineItem(`${storageArea}:one`);
+          const item2 = storage.defineItem(`${storageArea}:two`);
+          await fakeBrowser.storage[storageArea].set({
+            one: 1,
+            one$: { v: 1 },
+            two: 2,
+            two$: { v: 1 },
+          });
+
+          await storage.removeItems([
+            item1,
+            { item: item2, options: { removeMeta: true } },
+          ]);
+
+          expect(await item1.getValue()).toBeNull();
+          expect(await item1.getMeta()).toEqual({ v: 1 });
+          expect(await item2.getValue()).toBeNull();
+          expect(await item2.getMeta()).toEqual({});
+        });
+
+        it('should remove multiple items', async () => {
+          const item1 = storage.defineItem(`${storageArea}:one`);
+          const item2 = storage.defineItem(`${storageArea}:two`);
+
+          await fakeBrowser.storage.local.set({
+            one: 1,
+            two: 2,
+          });
+
+          await storage.removeItems([item1, item2]);
+
+          expect(await item1.getValue()).toBeNull();
+          expect(await item2.getValue()).toBeNull();
+        });
+
+        it('should remove items using { item: WxtStorageItem, options?: RemoveItemOptions } objects', async () => {
+          const item1 = storage.defineItem('local:item1');
+          const item2 = storage.defineItem('session:item2');
+
+          await item1.setValue('value1');
+          await item1.setMeta({ v: 1 });
+          await item2.setValue('value2');
+          await item2.setMeta({ v: 1 });
+
+          await storage.removeItems([
+            { item: item1, options: { removeMeta: true } },
+            { item: item2, options: { removeMeta: false } },
+          ]);
+
+          expect(await item1.getValue()).toBeNull();
+          expect(await item1.getMeta()).toEqual({});
+          expect(await item2.getValue()).toBeNull();
+          expect(await item2.getMeta()).toEqual({ v: 1 });
+        });
+
+        it('should handle a mix of different input types', async () => {
+          const item1 = storage.defineItem('local:item1');
+          const item2 = storage.defineItem('session:item2');
+          const item3 = storage.defineItem('local:item3');
+
+          await item1.setValue('value1');
+          await item2.setValue('value2');
+          await item3.setValue('value3');
+
+          await storage.removeItems([
+            'local:item1',
+            item2,
+            { key: 'local:item3', options: { removeMeta: true } },
+          ]);
+
+          expect(await storage.getItem('local:item1')).toBeNull();
+          expect(await item2.getValue()).toBeNull();
+          expect(await item3.getValue()).toBeNull();
+          expect(await item3.getMeta()).toEqual({});
+        });
+
+        it('should not throw an error when removing non-existent items', async () => {
+          const item = storage.defineItem('local:non_existent');
+
+          await expect(storage.removeItems([item])).resolves.not.toThrow();
         });
       });
 
@@ -400,6 +644,22 @@ describe('Storage Utils', () => {
     },
   );
 
+  describe('Invalid storage areas', () => {
+    it('should not accept keys without a valid storage area prefix', async () => {
+      // @ts-expect-error
+      await storage.getItem('test').catch(() => {});
+      // @ts-expect-error
+      await storage.getItem('loca:test').catch(() => {});
+    });
+
+    it('should throw an error when using an invalid storage area', async () => {
+      // @ts-expect-error: Test passes if there is a type error here
+      await expect(storage.getItem('invalidArea:key')).rejects.toThrow(
+        'Invalid area',
+      );
+    });
+  });
+
   describe('defineItem', () => {
     describe('versioning', () => {
       it('should migrate values to the latest when a version upgrade is detected', async () => {
@@ -553,6 +813,28 @@ describe('Storage Utils', () => {
           'Version downgrade detected (v2 -> v1) for "local:count"',
         );
       });
+
+      it('should throw an error when defining an item with an invalid version', () => {
+        expect(() => storage.defineItem('local:key', { version: 0 })).toThrow(
+          'Storage item version cannot be less than 1',
+        );
+      });
+
+      it('should handle errors in migration functions', async () => {
+        const cause = Error('Some error');
+        const expectedError = new MigrationError('local:key', 2, { cause });
+        const item = storage.defineItem<number>('local:key', {
+          version: 3,
+          migrations: {
+            2: () => {
+              throw cause;
+            },
+          },
+        });
+        await fakeBrowser.storage.local.set({ key: 1, key$: { v: 1 } });
+
+        await expect(item.migrate()).rejects.toThrow(expectedError);
+      });
     });
 
     describe('getValue', () => {
@@ -872,6 +1154,24 @@ describe('Storage Utils', () => {
 
         await expect(storage.getItem('local:test')).resolves.toBe(expected);
       });
+
+      it("should re-initialize a value on the next call to getValue if it's been removed", async () => {
+        const init = vi.fn().mockImplementation(Math.random);
+        const item = storage.defineItem<number>('local:key', { init });
+        await waitForInit();
+
+        await item.removeValue();
+        // Make sure it's actually blank before running the test
+        expect(await chrome.storage.local.get()).toEqual({});
+        init.mockClear();
+
+        const [value1, value2] = await Promise.all([
+          item.getValue(),
+          item.getValue(),
+        ]);
+        expect(init).toBeCalledTimes(1);
+        expect(value1).toBe(value2);
+      });
     });
 
     describe('types', () => {
@@ -896,12 +1196,173 @@ describe('Storage Utils', () => {
     });
   });
 
-  describe('types', () => {
-    it('should not accept keys without a valid storage area prefix', async () => {
-      // @ts-expect-error: Test passes if there is a type error here
-      await storage.getItem('test').catch(() => {});
-      // @ts-expect-error
-      await storage.getItem('loca:test').catch(() => {});
+  describe('Multiple Storage Areas', () => {
+    describe('getItems', () => {
+      it('should get the values of multiple storage items efficiently', async () => {
+        const item1 = storage.defineItem<number>('local:item1');
+        const item2 = storage.defineItem<string>('session:item2');
+        const item3 = storage.defineItem<boolean>('local:item3');
+
+        await item1.setValue(42);
+        await item2.setValue('hello');
+        await item3.setValue(false);
+
+        const localGetSpy = vi.spyOn(fakeBrowser.storage.local, 'get');
+        const sessionGetSpy = vi.spyOn(fakeBrowser.storage.session, 'get');
+
+        const values = await storage.getItems([item1, item2, item3]);
+
+        expect(values).toEqual([
+          {
+            key: 'local:item1',
+            value: 42,
+          },
+          {
+            key: 'session:item2',
+            value: 'hello',
+          },
+          {
+            key: 'local:item3',
+            value: false,
+          },
+        ]);
+
+        expect(localGetSpy).toBeCalledTimes(1);
+        expect(localGetSpy).toBeCalledWith(['item1', 'item3']);
+        expect(sessionGetSpy).toBeCalledTimes(1);
+        expect(sessionGetSpy).toBeCalledWith(['item2']);
+      });
+
+      it('should return values in the same order as input', async () => {
+        const item1 = storage.defineItem<number>('local:item1');
+        const item2 = storage.defineItem<string>('session:item2');
+        const item3 = storage.defineItem<boolean>('local:item3');
+
+        expect(await storage.getItems([item1, item2, item3])).toEqual([
+          { key: item1.key, value: null },
+          { key: item2.key, value: null },
+          { key: item3.key, value: null },
+        ]);
+        expect(await storage.getItems([item3, item2, item1])).toEqual([
+          { key: item3.key, value: null },
+          { key: item2.key, value: null },
+          { key: item1.key, value: null },
+        ]);
+      });
+    });
+
+    describe('getMetas', () => {
+      it('should get the metadata of multiple storage items efficiently', async () => {
+        const item1 = storage.defineItem<number, { v: number }>('local:item1');
+        const item2 = storage.defineItem<string, { date: number }>(
+          'session:item2',
+        );
+        const item3 = storage.defineItem<boolean, { flag: boolean }>(
+          'local:item3',
+        );
+
+        await item1.setMeta({ v: 1 });
+        await item2.setMeta({ date: 1234567890 });
+        // item3 has no meta
+
+        const localGetSpy = vi.spyOn(fakeBrowser.storage.local, 'get');
+        const sessionGetSpy = vi.spyOn(fakeBrowser.storage.session, 'get');
+
+        const metas = await storage.getMetas([item1, item2, item3]);
+
+        expect(metas).toEqual([
+          { key: item1.key, meta: { v: 1 } },
+          { key: item2.key, meta: { date: 1234567890 } },
+          { key: item3.key, meta: {} },
+        ]);
+
+        expect(localGetSpy).toBeCalledTimes(1);
+        expect(localGetSpy).toBeCalledWith(['item1$', 'item3$']);
+        expect(sessionGetSpy).toBeCalledTimes(1);
+        expect(sessionGetSpy).toBeCalledWith(['item2$']);
+      });
+
+      it('should return the metadata in the same order as input', async () => {
+        const item1 = storage.defineItem<number, { v: number }>('local:item1');
+        const item2 = storage.defineItem<string, { date: number }>(
+          'session:item2',
+        );
+        const item3 = storage.defineItem<boolean, { flag: boolean }>(
+          'local:item3',
+        );
+
+        expect(await storage.getMetas([item1, item2, item3])).toEqual([
+          { key: item1.key, meta: {} },
+          { key: item2.key, meta: {} },
+          { key: item3.key, meta: {} },
+        ]);
+        expect(await storage.getMetas([item3, item2, item1])).toEqual([
+          { key: item3.key, meta: {} },
+          { key: item2.key, meta: {} },
+          { key: item1.key, meta: {} },
+        ]);
+      });
+    });
+
+    describe('setItems', () => {
+      it('should set the values of multiple storage items efficiently', async () => {
+        const item1 = storage.defineItem<number>('local:item1');
+        const value1 = 100;
+        const item2 = storage.defineItem<string>('session:item2');
+        const value2 = 'test';
+        const item3 = storage.defineItem<boolean>('local:item3');
+        const value3 = true;
+
+        const localSetSpy = vi.spyOn(fakeBrowser.storage.local, 'set');
+        const sessionSetSpy = vi.spyOn(fakeBrowser.storage.session, 'set');
+
+        await storage.setItems([
+          { item: item1, value: value1 },
+          { item: item2, value: value2 },
+          { item: item3, value: value3 },
+        ]);
+
+        expect(localSetSpy).toBeCalledTimes(1);
+        expect(localSetSpy).toBeCalledWith({ item1: value1, item3: value3 });
+        expect(sessionSetSpy).toBeCalledTimes(1);
+        expect(sessionSetSpy).toBeCalledWith({ item2: value2 });
+      });
+    });
+
+    describe('setMetas', () => {
+      it('should set metadata efficiently', async () => {
+        const item1 = storage.defineItem<number, { v: number }>('local:one');
+        const item2 = storage.defineItem<string, { v: number }>('session:two');
+        const item3 = storage.defineItem<boolean, { v: number }>('local:three');
+        await waitForInit();
+
+        const localGetSpy = vi.spyOn(fakeBrowser.storage.local, 'get');
+        const sessionGetSpy = vi.spyOn(fakeBrowser.storage.session, 'get');
+        const localSetSpy = vi.spyOn(fakeBrowser.storage.local, 'set');
+        const sessionSetSpy = vi.spyOn(fakeBrowser.storage.session, 'set');
+
+        await storage.setMetas([
+          { item: item1, meta: { v: 1 } },
+          { item: item2, meta: { v: 2 } },
+          { item: item3, meta: { v: 3 } },
+        ]);
+
+        console.log(localGetSpy.mock.calls);
+        expect(localGetSpy).toBeCalledTimes(1);
+        expect(localGetSpy).toBeCalledWith(['one$', 'three$']);
+        expect(sessionGetSpy).toBeCalledTimes(1);
+        expect(sessionGetSpy).toBeCalledWith(['two$']);
+
+        expect(localSetSpy).toBeCalledTimes(1);
+        expect(localSetSpy).toBeCalledWith({
+          one$: { v: 1 },
+          three$: { v: 3 },
+        });
+        expect(sessionSetSpy).toBeCalledTimes(1);
+        expect(sessionSetSpy).toBeCalledWith({
+          two$: { v: 2 },
+        });
+      });
     });
 
     it('should return a nullable type when getItem is called without a fallback', async () => {

packages/storage/src/index.ts

@@ -0,0 +1,878 @@
+/// <reference types="chrome" />
+/**
+ * Simplified storage APIs with support for versioned fields, snapshots, metadata, and item definitions.
+ *
+ * See [the guide](https://wxt.dev/storage.html) for more information.
+ * @module @wxt-dev/storage
+ */
+import { dequal } from 'dequal/lite';
+import { Mutex } from 'async-mutex';
+
+const browser: typeof chrome =
+  // @ts-expect-error
+  globalThis.browser?.runtime?.id == null
+    ? globalThis.chrome
+    : // @ts-expect-error
+      globalThis.browser;
+
+export const storage = createStorage();
+
+function createStorage(): WxtStorage {
+  const drivers: Record<StorageArea, WxtStorageDriver> = {
+    local: createDriver('local'),
+    session: createDriver('session'),
+    sync: createDriver('sync'),
+    managed: createDriver('managed'),
+  };
+  const getDriver = (area: StorageArea) => {
+    const driver = drivers[area];
+    if (driver == null) {
+      const areaNames = Object.keys(drivers).join(', ');
+      throw Error(`Invalid area "${area}". Options: ${areaNames}`);
+    }
+    return driver;
+  };
+  const resolveKey = (key: StorageItemKey) => {
+    const deliminatorIndex = key.indexOf(':');
+    const driverArea = key.substring(0, deliminatorIndex) as StorageArea;
+    const driverKey = key.substring(deliminatorIndex + 1);
+    if (driverKey == null)
+      throw Error(
+        `Storage key should be in the form of "area:key", but received "${key}"`,
+      );
+
+    return {
+      driverArea,
+      driverKey,
+      driver: getDriver(driverArea),
+    };
+  };
+  const getMetaKey = (key: string) => key + '$';
+  const mergeMeta = (oldMeta: any, newMeta: any): any => {
+    const newFields = { ...oldMeta };
+    Object.entries(newMeta).forEach(([key, value]) => {
+      if (value == null) delete newFields[key];
+      else newFields[key] = value;
+    });
+    return newFields;
+  };
+  const getValueOrFallback = (value: any, fallback: any) =>
+    value ?? fallback ?? null;
+  const getMetaValue = (properties: any) =>
+    typeof properties === 'object' && !Array.isArray(properties)
+      ? properties
+      : {};
+
+  const getItem = async (
+    driver: WxtStorageDriver,
+    driverKey: string,
+    opts: GetItemOptions<any> | undefined,
+  ) => {
+    const res = await driver.getItem<any>(driverKey);
+    return getValueOrFallback(res, opts?.fallback ?? opts?.defaultValue);
+  };
+  const getMeta = async (driver: WxtStorageDriver, driverKey: string) => {
+    const metaKey = getMetaKey(driverKey);
+    const res = await driver.getItem<any>(metaKey);
+    return getMetaValue(res);
+  };
+  const setItem = async (
+    driver: WxtStorageDriver,
+    driverKey: string,
+    value: any,
+  ) => {
+    await driver.setItem(driverKey, value ?? null);
+  };
+  const setMeta = async (
+    driver: WxtStorageDriver,
+    driverKey: string,
+    properties: any | undefined,
+  ) => {
+    const metaKey = getMetaKey(driverKey);
+    const existingFields = getMetaValue(await driver.getItem(metaKey));
+    await driver.setItem(metaKey, mergeMeta(existingFields, properties));
+  };
+  const removeItem = async (
+    driver: WxtStorageDriver,
+    driverKey: string,
+    opts: RemoveItemOptions | undefined,
+  ) => {
+    await driver.removeItem(driverKey);
+    if (opts?.removeMeta) {
+      const metaKey = getMetaKey(driverKey);
+      await driver.removeItem(metaKey);
+    }
+  };
+  const removeMeta = async (
+    driver: WxtStorageDriver,
+    driverKey: string,
+    properties: string | string[] | undefined,
+  ) => {
+    const metaKey = getMetaKey(driverKey);
+    if (properties == null) {
+      await driver.removeItem(metaKey);
+    } else {
+      const newFields = getMetaValue(await driver.getItem(metaKey));
+      [properties].flat().forEach((field) => delete newFields[field]);
+      await driver.setItem(metaKey, newFields);
+    }
+  };
+  const watch = (
+    driver: WxtStorageDriver,
+    driverKey: string,
+    cb: WatchCallback<any>,
+  ) => {
+    return driver.watch(driverKey, cb);
+  };
+
+  const storage: WxtStorage = {
+    getItem: async (key, opts) => {
+      const { driver, driverKey } = resolveKey(key);
+      return await getItem(driver, driverKey, opts);
+    },
+    getItems: async (keys) => {
+      const areaToKeyMap = new Map<StorageArea, string[]>();
+      const keyToOptsMap = new Map<string, GetItemOptions<any> | undefined>();
+      const orderedKeys: StorageItemKey[] = [];
+
+      keys.forEach((key) => {
+        let keyStr: StorageItemKey;
+        let opts: GetItemOptions<any> | undefined;
+        if (typeof key === 'string') {
+          // key: string
+          keyStr = key;
+        } else if ('getValue' in key) {
+          // key: WxtStorageItem
+          keyStr = key.key;
+          opts = { fallback: key.fallback };
+        } else {
+          // key: { key, options }
+          keyStr = key.key;
+          opts = key.options;
+        }
+        orderedKeys.push(keyStr);
+        const { driverArea, driverKey } = resolveKey(keyStr);
+        const areaKeys = areaToKeyMap.get(driverArea) ?? [];
+        areaToKeyMap.set(driverArea, areaKeys.concat(driverKey));
+        keyToOptsMap.set(keyStr, opts);
+      });
+
+      const resultsMap = new Map<StorageItemKey, any>();
+      await Promise.all(
+        Array.from(areaToKeyMap.entries()).map(async ([driverArea, keys]) => {
+          const driverResults = await drivers[driverArea].getItems(keys);
+          driverResults.forEach((driverResult) => {
+            const key = `${driverArea}:${driverResult.key}` as StorageItemKey;
+            const opts = keyToOptsMap.get(key);
+            const value = getValueOrFallback(
+              driverResult.value,
+              opts?.fallback ?? opts?.defaultValue,
+            );
+            resultsMap.set(key, value);
+          });
+        }),
+      );
+
+      return orderedKeys.map((key) => ({
+        key,
+        value: resultsMap.get(key),
+      }));
+    },
+    getMeta: async (key) => {
+      const { driver, driverKey } = resolveKey(key);
+      return await getMeta(driver, driverKey);
+    },
+    getMetas: async (args) => {
+      const keys = args.map((arg) => {
+        const key = typeof arg === 'string' ? arg : arg.key;
+        const { driverArea, driverKey } = resolveKey(key);
+        return {
+          key,
+          driverArea,
+          driverKey,
+          driverMetaKey: getMetaKey(driverKey),
+        };
+      });
+      const areaToDriverMetaKeysMap = keys.reduce<
+        Partial<Record<StorageArea, (typeof keys)[number][]>>
+      >((map, key) => {
+        map[key.driverArea] ??= [];
+        map[key.driverArea]!.push(key);
+        return map;
+      }, {});
+
+      const resultsMap: Record<string, any> = {};
+      await Promise.all(
+        Object.entries(areaToDriverMetaKeysMap).map(async ([area, keys]) => {
+          const areaRes = await browser.storage[area as StorageArea].get(
+            keys.map((key) => key.driverMetaKey),
+          );
+          keys.forEach((key) => {
+            resultsMap[key.key] = areaRes[key.driverMetaKey] ?? {};
+          });
+        }),
+      );
+
+      return keys.map((key) => ({
+        key: key.key,
+        meta: resultsMap[key.key],
+      }));
+    },
+    setItem: async (key, value) => {
+      const { driver, driverKey } = resolveKey(key);
+      await setItem(driver, driverKey, value);
+    },
+    setItems: async (items) => {
+      const areaToKeyValueMap: Partial<
+        Record<StorageArea, Array<{ key: string; value: any }>>
+      > = {};
+      items.forEach((item) => {
+        const { driverArea, driverKey } = resolveKey(
+          'key' in item ? item.key : item.item.key,
+        );
+        areaToKeyValueMap[driverArea] ??= [];
+        areaToKeyValueMap[driverArea].push({
+          key: driverKey,
+          value: item.value,
+        });
+      });
+      await Promise.all(
+        Object.entries(areaToKeyValueMap).map(async ([driverArea, values]) => {
+          const driver = getDriver(driverArea as StorageArea);
+          await driver.setItems(values);
+        }),
+      );
+    },
+    setMeta: async (key, properties) => {
+      const { driver, driverKey } = resolveKey(key);
+      await setMeta(driver, driverKey, properties);
+    },
+    setMetas: async (items) => {
+      const areaToMetaUpdatesMap: Partial<
+        Record<StorageArea, { key: string; properties: any }[]>
+      > = {};
+      items.forEach((item) => {
+        const { driverArea, driverKey } = resolveKey(
+          'key' in item ? item.key : item.item.key,
+        );
+        areaToMetaUpdatesMap[driverArea] ??= [];
+        areaToMetaUpdatesMap[driverArea].push({
+          key: driverKey,
+          properties: item.meta,
+        });
+      });
+
+      await Promise.all(
+        Object.entries(areaToMetaUpdatesMap).map(
+          async ([storageArea, updates]) => {
+            const driver = getDriver(storageArea as StorageArea);
+            const metaKeys = updates.map(({ key }) => getMetaKey(key));
+            console.log(storageArea, metaKeys);
+            const existingMetas = await driver.getItems(metaKeys);
+            const existingMetaMap = Object.fromEntries(
+              existingMetas.map(({ key, value }) => [key, getMetaValue(value)]),
+            );
+
+            const metaUpdates = updates.map(({ key, properties }) => {
+              const metaKey = getMetaKey(key);
+              return {
+                key: metaKey,
+                value: mergeMeta(existingMetaMap[metaKey] ?? {}, properties),
+              };
+            });
+
+            await driver.setItems(metaUpdates);
+          },
+        ),
+      );
+    },
+    removeItem: async (key, opts) => {
+      const { driver, driverKey } = resolveKey(key);
+      await removeItem(driver, driverKey, opts);
+    },
+    removeItems: async (keys) => {
+      const areaToKeysMap: Partial<Record<StorageArea, string[]>> = {};
+
+      keys.forEach((key) => {
+        let keyStr: StorageItemKey;
+        let opts: RemoveItemOptions | undefined;
+        if (typeof key === 'string') {
+          // key: string
+          keyStr = key;
+        } else if ('getValue' in key) {
+          // key: WxtStorageItem
+          keyStr = key.key;
+        } else if ('item' in key) {
+          // key: { item, options }
+          keyStr = key.item.key;
+          opts = key.options;
+        } else {
+          // key: { key, options }
+          keyStr = key.key;
+          opts = key.options;
+        }
+        const { driverArea, driverKey } = resolveKey(keyStr);
+        areaToKeysMap[driverArea] ??= [];
+        areaToKeysMap[driverArea].push(driverKey);
+        if (opts?.removeMeta) {
+          areaToKeysMap[driverArea].push(getMetaKey(driverKey));
+        }
+      });
+
+      await Promise.all(
+        Object.entries(areaToKeysMap).map(async ([driverArea, keys]) => {
+          const driver = getDriver(driverArea as StorageArea);
+          await driver.removeItems(keys);
+        }),
+      );
+    },
+    removeMeta: async (key, properties) => {
+      const { driver, driverKey } = resolveKey(key);
+      await removeMeta(driver, driverKey, properties);
+    },
+    snapshot: async (base, opts) => {
+      const driver = getDriver(base);
+      const data = await driver.snapshot();
+      opts?.excludeKeys?.forEach((key) => {
+        delete data[key];
+        delete data[getMetaKey(key)];
+      });
+      return data;
+    },
+    restoreSnapshot: async (base, data) => {
+      const driver = getDriver(base);
+      await driver.restoreSnapshot(data);
+    },
+    watch: (key, cb) => {
+      const { driver, driverKey } = resolveKey(key);
+      return watch(driver, driverKey, cb);
+    },
+    unwatch() {
+      Object.values(drivers).forEach((driver) => {
+        driver.unwatch();
+      });
+    },
+    defineItem: (key, opts?: WxtStorageItemOptions<any>) => {
+      const { driver, driverKey } = resolveKey(key);
+
+      const { version: targetVersion = 1, migrations = {} } = opts ?? {};
+      if (targetVersion < 1) {
+        throw Error(
+          'Storage item version cannot be less than 1. Initial versions should be set to 1, not 0.',
+        );
+      }
+      const migrate = async () => {
+        const driverMetaKey = getMetaKey(driverKey);
+        const [{ value }, { value: meta }] = await driver.getItems([
+          driverKey,
+          driverMetaKey,
+        ]);
+        if (value == null) return;
+
+        const currentVersion = meta?.v ?? 1;
+        if (currentVersion > targetVersion) {
+          throw Error(
+            `Version downgrade detected (v${currentVersion} -> v${targetVersion}) for "${key}"`,
+          );
+        }
+
+        console.debug(
+          `[@wxt-dev/storage] Running storage migration for ${key}: v${currentVersion} -> v${targetVersion}`,
+        );
+        const migrationsToRun = Array.from(
+          { length: targetVersion - currentVersion },
+          (_, i) => currentVersion + i + 1,
+        );
+        let migratedValue = value;
+        for (const migrateToVersion of migrationsToRun) {
+          try {
+            migratedValue =
+              (await migrations?.[migrateToVersion]?.(migratedValue)) ??
+              migratedValue;
+          } catch (err) {
+            throw Error(`v${migrateToVersion} migration failed for "${key}"`, {
+              cause: err,
+            });
+          }
+        }
+        await driver.setItems([
+          { key: driverKey, value: migratedValue },
+          { key: driverMetaKey, value: { ...meta, v: targetVersion } },
+        ]);
+        console.debug(
+          `[@wxt-dev/storage] Storage migration completed for ${key} v${targetVersion}`,
+          { migratedValue },
+        );
+      };
+      const migrationsDone =
+        opts?.migrations == null
+          ? Promise.resolve()
+          : migrate().catch((err) => {
+              console.error(
+                `[@wxt-dev/storage] Migration failed for ${key}`,
+                err,
+              );
+            });
+
+      const initMutex = new Mutex();
+
+      const getFallback = () => opts?.fallback ?? opts?.defaultValue ?? null;
+
+      const getOrInitValue = () =>
+        initMutex.runExclusive(async () => {
+          const value = await driver.getItem<any>(driverKey);
+          // Don't init value if it already exists or the init function isn't provided
+          if (value != null || opts?.init == null) return value;
+
+          const newValue = await opts.init();
+          await driver.setItem<any>(driverKey, newValue);
+          return newValue;
+        });
+
+      // Initialize the value once migrations have finished
+      migrationsDone.then(getOrInitValue);
+
+      return {
+        key,
+        get defaultValue() {
+          return getFallback();
+        },
+        get fallback() {
+          return getFallback();
+        },
+        getValue: async () => {
+          await migrationsDone;
+          if (opts?.init) {
+            return await getOrInitValue();
+          } else {
+            return await getItem(driver, driverKey, opts);
+          }
+        },
+        getMeta: async () => {
+          await migrationsDone;
+          return await getMeta(driver, driverKey);
+        },
+        setValue: async (value) => {
+          await migrationsDone;
+          return await setItem(driver, driverKey, value);
+        },
+        setMeta: async (properties) => {
+          await migrationsDone;
+          return await setMeta(driver, driverKey, properties);
+        },
+        removeValue: async (opts) => {
+          await migrationsDone;
+          return await removeItem(driver, driverKey, opts);
+        },
+        removeMeta: async (properties) => {
+          await migrationsDone;
+          return await removeMeta(driver, driverKey, properties);
+        },
+        watch: (cb) =>
+          watch(driver, driverKey, (newValue, oldValue) =>
+            cb(newValue ?? getFallback(), oldValue ?? getFallback()),
+          ),
+        migrate,
+      };
+    },
+  };
+  return storage;
+}
+
+function createDriver(storageArea: StorageArea): WxtStorageDriver {
+  const getStorageArea = () => {
+    if (browser.runtime == null) {
+      throw Error(
+        [
+          "'wxt/storage' must be loaded in a web extension environment",
+          '\n - If thrown during a build, see https://github.com/wxt-dev/wxt/issues/371',
+          " - If thrown during tests, mock 'wxt/browser' correctly. See https://wxt.dev/guide/go-further/testing.html\n",
+        ].join('\n'),
+      );
+    }
+    if (browser.storage == null) {
+      throw Error(
+        "You must add the 'storage' permission to your manifest to use 'wxt/storage'",
+      );
+    }
+
+    const area = browser.storage[storageArea];
+    if (area == null)
+      throw Error(`"browser.storage.${storageArea}" is undefined`);
+    return area;
+  };
+  const watchListeners = new Set<(changes: StorageAreaChanges) => void>();
+  return {
+    getItem: async (key) => {
+      const res = await getStorageArea().get(key);
+      return res[key];
+    },
+    getItems: async (keys) => {
+      const result = await getStorageArea().get(keys);
+      return keys.map((key) => ({ key, value: result[key] ?? null }));
+    },
+    setItem: async (key, value) => {
+      if (value == null) {
+        await getStorageArea().remove(key);
+      } else {
+        await getStorageArea().set({ [key]: value });
+      }
+    },
+    setItems: async (values) => {
+      const map = values.reduce<Record<string, unknown>>(
+        (map, { key, value }) => {
+          map[key] = value;
+          return map;
+        },
+        {},
+      );
+      await getStorageArea().set(map);
+    },
+    removeItem: async (key) => {
+      await getStorageArea().remove(key);
+    },
+    removeItems: async (keys) => {
+      await getStorageArea().remove(keys);
+    },
+    snapshot: async () => {
+      return await getStorageArea().get();
+    },
+    restoreSnapshot: async (data) => {
+      await getStorageArea().set(data);
+    },
+    watch(key, cb) {
+      const listener = (changes: StorageAreaChanges) => {
+        const change = changes[key];
+        if (change == null) return;
+        if (dequal(change.newValue, change.oldValue)) return;
+        cb(change.newValue ?? null, change.oldValue ?? null);
+      };
+      getStorageArea().onChanged.addListener(listener);
+      watchListeners.add(listener);
+      return () => {
+        getStorageArea().onChanged.removeListener(listener);
+        watchListeners.delete(listener);
+      };
+    },
+    unwatch() {
+      watchListeners.forEach((listener) => {
+        getStorageArea().onChanged.removeListener(listener);
+      });
+      watchListeners.clear();
+    },
+  };
+}
+
+export interface WxtStorage {
+  /**
+   * Get an item from storage, or return `null` if it doesn't exist.
+   *
+   * @example
+   * await storage.getItem<number>("local:installDate");
+   */
+  getItem<TValue>(
+    key: StorageItemKey,
+    opts: GetItemOptions<TValue> & { fallback: TValue },
+  ): Promise<TValue>;
+
+  getItem<TValue>(
+    key: StorageItemKey,
+    opts?: GetItemOptions<TValue>,
+  ): Promise<TValue | null>;
+
+  /**
+   * Get multiple items from storage. The return order is guaranteed to be the same as the order
+   * requested.
+   *
+   * @example
+   * await storage.getItems(["local:installDate", "session:someCounter"]);
+   */
+  getItems(
+    keys: Array<
+      | StorageItemKey
+      | WxtStorageItem<any, any>
+      | { key: StorageItemKey; options?: GetItemOptions<any> }
+    >,
+  ): Promise<Array<{ key: StorageItemKey; value: any }>>;
+  /**
+   * Return an object containing metadata about the key. Object is stored at `key + "$"`. If value
+   * is not an object, it returns an empty object.
+   *
+   * @example
+   * await storage.getMeta("local:installDate");
+   */
+  getMeta<T extends Record<string, unknown>>(key: StorageItemKey): Promise<T>;
+  /**
+   * Get the metadata of multiple storage items.
+   *
+   * @param items List of keys or items to get the metadata of.
+   * @returns An array containing storage keys and their metadata.
+   */
+  getMetas(
+    keys: Array<StorageItemKey | WxtStorageItem<any, any>>,
+  ): Promise<Array<{ key: StorageItemKey; meta: any }>>;
+  /**
+   * Set a value in storage. Setting a value to `null` or `undefined` is equivalent to calling
+   * `removeItem`.
+   *
+   * @example
+   * await storage.setItem<number>("local:installDate", Date.now());
+   */
+  setItem<T>(key: StorageItemKey, value: T | null): Promise<void>;
+  /**
+   * Set multiple values in storage. If a value is set to `null` or `undefined`, the key is removed.
+   *
+   * @example
+   * await storage.setItem([
+   *   { key: "local:installDate", value: Date.now() },
+   *   { key: "session:someCounter, value: 5 },
+   * ]);
+   */
+  setItems(
+    values: Array<
+      | { key: StorageItemKey; value: any }
+      | { item: WxtStorageItem<any, any>; value: any }
+    >,
+  ): Promise<void>;
+  /**
+   * Sets metadata properties. If some properties are already set, but are not included in the
+   * `properties` parameter, they will not be removed.
+   *
+   * @example
+   * await storage.setMeta("local:installDate", { appVersion });
+   */
+  setMeta<T extends Record<string, unknown>>(
+    key: StorageItemKey,
+    properties: T | null,
+  ): Promise<void>;
+  /**
+   * Set the metadata of multiple storage items.
+   *
+   * @param items List of storage keys or items and metadata to set for each.
+   */
+  setMetas(
+    metas: Array<
+      | { key: StorageItemKey; meta: Record<string, any> }
+      | { item: WxtStorageItem<any, any>; meta: Record<string, any> }
+    >,
+  ): Promise<void>;
+  /**
+   * Removes an item from storage.
+   *
+   * @example
+   * await storage.removeItem("local:installDate");
+   */
+  removeItem(key: StorageItemKey, opts?: RemoveItemOptions): Promise<void>;
+  /**
+   * Remove a list of keys from storage.
+   */
+  removeItems(
+    keys: Array<
+      | StorageItemKey
+      | WxtStorageItem<any, any>
+      | { key: StorageItemKey; options?: RemoveItemOptions }
+      | { item: WxtStorageItem<any, any>; options?: RemoveItemOptions }
+    >,
+  ): Promise<void>;
+  /**
+   * Remove the entire metadata for a key, or specific properties by name.
+   *
+   * @example
+   * // Remove all metadata properties from the item
+   * await storage.removeMeta("local:installDate");
+   *
+   * // Remove only specific the "v" field
+   * await storage.removeMeta("local:installDate", "v")
+   */
+  removeMeta(
+    key: StorageItemKey,
+    properties?: string | string[],
+  ): Promise<void>;
+  /**
+   * Return all the items in storage.
+   */
+  snapshot(
+    base: StorageArea,
+    opts?: SnapshotOptions,
+  ): Promise<Record<string, unknown>>;
+  /**
+   * Restores the results of `snapshot`. If new properties have been saved since the snapshot, they are
+   * not overridden. Only values existing in the snapshot are overridden.
+   */
+  restoreSnapshot(base: StorageArea, data: any): Promise<void>;
+  /**
+   * Watch for changes to a specific key in storage.
+   */
+  watch<T>(key: StorageItemKey, cb: WatchCallback<T | null>): Unwatch;
+  /**
+   * Remove all watch listeners.
+   */
+  unwatch(): void;
+
+  /**
+   * Define a storage item with a default value, type, or versioning.
+   *
+   * Read full docs: https://wxt.dev/guide/extension-apis/storage.html#defining-storage-items
+   */
+  defineItem<TValue, TMetadata extends Record<string, unknown> = {}>(
+    key: StorageItemKey,
+  ): WxtStorageItem<TValue | null, TMetadata>;
+  defineItem<TValue, TMetadata extends Record<string, unknown> = {}>(
+    key: StorageItemKey,
+    options: WxtStorageItemOptions<TValue>,
+  ): WxtStorageItem<TValue, TMetadata>;
+}
+
+interface WxtStorageDriver {
+  getItem<T>(key: string): Promise<T | null>;
+  getItems(keys: string[]): Promise<{ key: string; value: any }[]>;
+  setItem<T>(key: string, value: T | null): Promise<void>;
+  setItems(values: Array<{ key: string; value: any }>): Promise<void>;
+  removeItem(key: string): Promise<void>;
+  removeItems(keys: string[]): Promise<void>;
+  snapshot(): Promise<Record<string, unknown>>;
+  restoreSnapshot(data: Record<string, unknown>): Promise<void>;
+  watch<T>(key: string, cb: WatchCallback<T | null>): Unwatch;
+  unwatch(): void;
+}
+
+export interface WxtStorageItem<
+  TValue,
+  TMetadata extends Record<string, unknown>,
+> {
+  /**
+   * The storage key passed when creating the storage item.
+   */
+  key: StorageItemKey;
+  /**
+   * @deprecated Renamed to fallback, use it instead.
+   */
+  defaultValue: TValue;
+  /**
+   * The value provided by the `fallback` option.
+   */
+  fallback: TValue;
+  /**
+   * Get the latest value from storage.
+   */
+  getValue(): Promise<TValue>;
+  /**
+   * Get metadata.
+   */
+  getMeta(): Promise<NullablePartial<TMetadata>>;
+  /**
+   * Set the value in storage.
+   */
+  setValue(value: TValue): Promise<void>;
+  /**
+   * Set metadata properties.
+   */
+  setMeta(properties: NullablePartial<TMetadata>): Promise<void>;
+  /**
+   * Remove the value from storage.
+   */
+  removeValue(opts?: RemoveItemOptions): Promise<void>;
+  /**
+   * Remove all metadata or certain properties from metadata.
+   */
+  removeMeta(properties?: string[]): Promise<void>;
+  /**
+   * Listen for changes to the value in storage.
+   */
+  watch(cb: WatchCallback<TValue>): Unwatch;
+  /**
+   * If there are migrations defined on the storage item, migrate to the latest version.
+   *
+   * **This function is ran automatically whenever the extension updates**, so you don't have to call it
+   * manually.
+   */
+  migrate(): Promise<void>;
+}
+
+export type StorageArea = 'local' | 'session' | 'sync' | 'managed';
+export type StorageItemKey = `${StorageArea}:${string}`;
+
+export interface GetItemOptions<T> {
+  /**
+   * @deprecated Renamed to `fallback`, use it instead.
+   */
+  defaultValue?: T;
+  /**
+   * Default value returned when `getItem` would otherwise return `null`.
+   */
+  fallback?: T;
+}
+
+export interface RemoveItemOptions {
+  /**
+   * Optionally remove metadata when deleting a key.
+   *
+   * @default false
+   */
+  removeMeta?: boolean;
+}
+
+export interface SnapshotOptions {
+  /**
+   * Exclude a list of keys. The storage area prefix should be removed since the snapshot is for a
+   * specific storage area already.
+   */
+  excludeKeys?: string[];
+}
+
+export interface WxtStorageItemOptions<T> {
+  /**
+   * @deprecated Renamed to `fallback`, use it instead.
+   */
+  defaultValue?: T;
+  /**
+   * Default value returned when `getValue` would otherwise return `null`.
+   */
+  fallback?: T;
+  /**
+   * If passed, a value in storage will be initialized immediately after
+   * defining the storage item. This function returns the value that will be
+   * saved to storage during the initialization process if a value doesn't
+   * already exist.
+   */
+  init?: () => T | Promise<T>;
+  /**
+   * Provide a version number for the storage item to enable migrations. When changing the version
+   * in the future, migration functions will be ran on application startup.
+   */
+  version?: number;
+  /**
+   * A map of version numbers to the functions used to migrate the data to that version.
+   */
+  migrations?: Record<number, (oldValue: any) => any>;
+}
+
+export type StorageAreaChanges = {
+  [key: string]: chrome.storage.StorageChange;
+};
+
+/**
+ * Same as `Partial`, but includes `| null`. It makes all the properties of an object optional and
+ * nullable.
+ */
+type NullablePartial<T> = {
+  [key in keyof T]+?: T[key] | undefined | null;
+};
+/**
+ * Callback called when a value in storage is changed.
+ */
+export type WatchCallback<T> = (newValue: T, oldValue: T) => void;
+/**
+ * Call to remove a watch listener
+ */
+export type Unwatch = () => void;
+
+export class MigrationError extends Error {
+  constructor(
+    public key: string,
+    public version: number,
+    options?: ErrorOptions,
+  ) {
+    super(`v${version} migration failed for "${key}"`, options);
+  }
+}

packages/storage/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "verbatimModuleSyntax": true,
+    "types": ["chrome"]
+  },
+  "exclude": ["node_modules/**", "dist/**"]
+}

packages/storage/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineProject } from 'vitest/config';
+
+export default defineProject({
+  test: {
+    mockReset: true,
+    restoreMocks: true,
+    setupFiles: ['vitest.setup.ts'],
+  },
+});

packages/storage/vitest.setup.ts

@@ -0,0 +1,4 @@
+import { fakeBrowser } from '@webext-core/fake-browser';
+import { vi } from 'vitest';
+
+vi.stubGlobal('chrome', fakeBrowser);

packages/unocss/README.md

@@ -0,0 +1,47 @@
+# WXT UnoCSS
+
+Use UnoCSS in your WXT extension!
+
+## Usage
+
+Install the package:
+
+```sh
+npm i --save-dev @wxt-dev/unocss unocss
+pnpm i -D @wxt-dev/unocss unocss
+yarn add --dev @wxt-dev/unocss unocss
+bun i -D @wxt-dev/unocss unocss
+```
+
+Add the module to `wxt.config.ts`:
+
+```ts
+export default defineConfig({
+  modules: ['@wxt-dev/unocss'],
+});
+```
+
+Now in your entrypoint, import UnoCSS:
+
+```ts
+import 'uno.css';
+```
+
+> [!IMPORTANT]
+> While in dev mode, you may see a warning about `uno.css` not being found. This is because in development, we don't know which files should be injected with UnoCSS styles. The warning can be safely ignored as the styles will be properly applied during the build process.
+
+## Configuration
+
+The module can be configured via the `unocss` config:
+
+```ts
+export default defineConfig({
+  modules: ['@wxt-dev/unocss'],
+  unocss: {
+    // Will only apply unocss for popup/main.ts
+    entrypoints: ['popup/main.ts'],
+  },
+});
+```
+
+Options have JSDocs available in your editor, or you can read them in the source code: [`UnoCSSOptions`](https://github.com/wxt-dev/wxt/blob/main/packages/auto-icons/src/index.ts).

packages/unocss/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@wxt-dev/unocss",
+  "description": "UnoCSS integration for WXT",
+  "version": "1.0.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wxt-dev/wxt.git",
+    "directory": "packages/unocss"
+  },
+  "homepage": "http://wxt.dev/guide/unocss.html",
+  "keywords": [
+    "wxt",
+    "module",
+    "unocss",
+    "css"
+  ],
+  "author": {
+    "name": "Florian Metz",
+    "email": "me@timeraa.dev"
+  },
+  "license": "MIT",
+  "type": "module",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "buildc -- unbuild",
+    "check": "buildc --deps-only -- check"
+  },
+  "peerDependencies": {
+    "unocss": ">=0.60.0",
+    "wxt": ">=0.19.0"
+  },
+  "devDependencies": {
+    "@aklinker1/check": "^1.4.5",
+    "oxlint": "^0.11.1",
+    "publint": "^0.2.12",
+    "typescript": "^5.6.3",
+    "unbuild": "^2.0.0",
+    "unocss": "^0.64.0",
+    "wxt": "workspace:*"
+  },
+  "dependencies": {
+    "defu": "^6.1.4",
+    "fast-glob": "^3.3.2"
+  }
+}

packages/unocss/src/index.ts

@@ -0,0 +1,68 @@
+import 'wxt';
+import { defineWxtModule } from 'wxt/modules';
+import defu from 'defu';
+import UnoCSS from 'unocss/vite';
+
+export default defineWxtModule<UnoCSSOptions>({
+  name: '@wxt-dev/unocss',
+  configKey: 'unocss',
+  async setup(wxt, options) {
+    const resolvedOptions = defu<Required<UnoCSSOptions>, UnoCSSOptions[]>(
+      options,
+      {
+        enabled: true,
+        excludeEntrypoints: ['background'],
+        configOrPath: undefined,
+      },
+    );
+
+    if (!resolvedOptions.enabled)
+      return wxt.logger.warn(`\`[unocss]\` ${this.name} disabled`);
+
+    const excludedEntrypoints = new Set(resolvedOptions.excludeEntrypoints);
+    if (wxt.config.debug) {
+      wxt.logger.debug(
+        `\`[unocss]\` Excluded entrypoints:`,
+        [...excludedEntrypoints].join(', '),
+      );
+    }
+
+    wxt.hooks.hook('vite:devServer:extendConfig', (config) => {
+      config.plugins?.push(UnoCSS(resolvedOptions.configOrPath));
+    });
+
+    wxt.hooks.hook('vite:build:extendConfig', async (entries, config) => {
+      if (entries.every((entry) => excludedEntrypoints.has(entry.name))) return;
+      config.plugins?.push(UnoCSS(resolvedOptions.configOrPath));
+    });
+  },
+});
+
+/**
+ * Options for the UnoCSS module
+ */
+export interface UnoCSSOptions<Theme extends object = object> {
+  /**
+   * Enable UnoCSS
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * List of entrypoint names that UnoCSS is not used in. By default, the UnoCSS
+   * vite plugin is added to all build steps, but this option is used to exclude
+   * it from specific builds.
+   * @example ["popup", "options"]
+   * @default []
+   */
+  excludeEntrypoints?: string[];
+  /**
+   * The path to your `unocss.config.ts` file, relative to <rootDir>, or inline configuration.
+   */
+  configOrPath?: Parameters<typeof UnoCSS<Theme>>[0];
+}
+
+declare module 'wxt' {
+  export interface InlineConfig {
+    unocss?: UnoCSSOptions;
+  }
+}

packages/unocss/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "exclude": ["node_modules/**", "dist/**"]
+}

packages/wxt-demo/package.json

@@ -18,17 +18,19 @@
   },
   "dependencies": {
     "@wxt-dev/i18n": "workspace:*",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1"
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@types/chrome": "^0.0.269",
-    "@types/react": "^18.3.11",
-    "@types/react-dom": "^18.3.0",
+    "@types/chrome": "^0.0.280",
+    "@types/react": "^19.0.1",
+    "@types/react-dom": "^19.0.2",
     "@wxt-dev/auto-icons": "workspace:*",
-    "sass": "^1.79.4",
-    "typescript": "^5.6.2",
-    "vitest": "^2.1.2",
+    "@wxt-dev/unocss": "workspace:*",
+    "sass": "^1.80.7",
+    "typescript": "^5.6.3",
+    "unocss": "^0.64.0",
+    "vitest": "^2.1.4",
     "vitest-plugin-random-seed": "^1.1.0",
     "wxt": "workspace:*"
   },

packages/wxt-demo/src/common/style.css

@@ -1,4 +0,0 @@
-body {
-  margin: 0;
-  padding: 0;
-}

packages/wxt-demo/src/entrypoints/automount.content/index.ts

@@ -0,0 +1,76 @@
+import 'uno.css';
+import './style.css';
+
+export default defineContentScript({
+  matches: ['https://*.duckduckgo.com/*'],
+  cssInjectionMode: 'manifest',
+
+  async main(ctx) {
+    const dynamicUI = createIntegratedUi(ctx, {
+      position: 'inline',
+      append: 'after',
+      anchor: 'form[role=search]',
+      onMount: (container) => {
+        const app = document.createElement('div');
+        container.id = 'automount-anchor';
+        app.classList.add('m-4', 'text-center', 'text-red-500');
+        app.textContent = i18n.t('prompt_for_name');
+        container.append(app);
+        return { container, app };
+      },
+      onRemove() {
+        console.log('dynamicUI removed');
+      },
+    });
+
+    const autoMountUi = createIntegratedUi(ctx, {
+      position: 'inline',
+      append: 'after',
+      anchor: '#automount-anchor',
+      onMount: (container) => {
+        const app = document.createElement('div');
+        app.id = 'automount-ui';
+        app.classList.add('m-0', 'text-center', 'text-blue-500');
+        app.textContent = `Hello, I'm automount UI.`;
+        container.append(app);
+      },
+      onRemove() {
+        console.log('autoMountUi removed');
+      },
+    });
+
+    autoMountUi.autoMount({
+      onStop: () => {
+        console.log('Auto mount stopped.');
+      },
+    });
+
+    const stopAutoMountButton = createIntegratedUi(ctx, {
+      position: 'inline',
+      append: 'last',
+      anchor: 'form[role=search]',
+      onMount: (container) => {
+        const app = document.createElement('button');
+        container.classList.add('flex', 'flex-justify-center');
+        app.classList.add('mt-4', 'p-2');
+        app.textContent = 'Stop auto-mount';
+        app.onclick = (e) => {
+          e.preventDefault();
+          autoMountUi.remove();
+        };
+        container.append(app);
+        return { container, app };
+      },
+    });
+
+    stopAutoMountButton.mount();
+
+    setInterval(() => {
+      if (dynamicUI.mounted) {
+        dynamicUI.remove();
+      } else {
+        dynamicUI.mount();
+      }
+    }, 2000);
+  },
+});

packages/wxt-demo/src/entrypoints/automount.content/style.css

@@ -0,0 +1,3 @@
+:root {
+  color-scheme: dark;
+}

packages/wxt-demo/src/entrypoints/background.ts

@@ -14,12 +14,13 @@ export default defineBackground({
 
     console.log(useAppConfig());
 
-    // @ts-expect-error: should only accept entrypoints or public assets
     browser.runtime.getURL('/');
     browser.runtime.getURL('/background.js');
     browser.runtime.getURL('/icons/128.png');
     browser.runtime.getURL('/example.html#hash');
     browser.runtime.getURL('/example.html?query=param');
+    // @ts-expect-error: should only accept entrypoints or public assets
+    browser.runtime.getURL('/unknown');
     // @ts-expect-error: should only allow hashes/query params on HTML files
     browser.runtime.getURL('/icon-128.png?query=param');
 

packages/wxt-demo/src/entrypoints/popup.html

@@ -4,7 +4,7 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Popup</title>
-    <link rel="stylesheet" href="../common/style.css" />
+    <link rel="stylesheet" href="uno.css" />
   </head>
   <body>
     <p>Hello popup!</p>

packages/wxt-demo/src/entrypoints/ui.content/index.ts

@@ -1,4 +1,4 @@
-import '../../common/style.css';
+import 'uno.css';
 import './style.css';
 
 export default defineContentScript({
@@ -13,6 +13,7 @@ export default defineContentScript({
       anchor: 'form[role=search]',
       onMount: (container) => {
         const app = document.createElement('div');
+        app.classList.add('m-4', 'text-red-500');
         app.textContent = i18n.t('prompt_for_name');
         container.append(app);
       },

packages/wxt-demo/src/entrypoints/ui.content/style.css

@@ -1,11 +1,6 @@
 :root {
   color-scheme: dark;
-  color: indianred;
 }
 html {
   background-color: black;
 }
-
-div {
-  padding: 16px;
-}

packages/wxt-demo/src/modules/unocss.ts

@@ -0,0 +1 @@
+export { default } from '@wxt-dev/unocss';

packages/wxt-demo/wxt.config.ts

@@ -1,4 +1,5 @@
 import { defineConfig } from 'wxt';
+import { presetUno } from 'unocss';
 
 export default defineConfig({
   srcDir: 'src',
@@ -24,7 +25,35 @@ export default defineConfig({
   },
   example: {
     a: 'a',
-    // @ts-expect-error: c is not defined, this should error out
+    // @ts-expect-error: c is not defined, this should be a type error, but it should show up in the module
     c: 'c',
   },
+  unocss: {
+    excludeEntrypoints: [
+      'example',
+      'iframe-src',
+      'injected',
+      'example-tsx',
+      'example-2',
+      'iframe',
+      'location-change',
+      'main-world',
+      'sandbox',
+      'sidepanel',
+      'unlisted',
+    ],
+    configOrPath: {
+      content: {
+        pipeline: {
+          include: [
+            // the default
+            /\.(vue|svelte|[jt]sx|mdx?|astro|elm|php|phtml|html)($|\?)/,
+            // include js/ts files
+            'src/entrypoints/**/*.{js,ts}',
+          ],
+        },
+      },
+      presets: [presetUno()],
+    },
+  },
 });

packages/wxt/CHANGELOG.md

@@ -1,5 +1,193 @@
 # Changelog
 
+## v0.19.22
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/wxt-v0.19.21...wxt-v0.19.22)
+
+### 🩹 Fixes
+
+- Exclude entire `import.meta.env` object from content script output ([#1267](https://github.com/wxt-dev/wxt/pull/1267))
+
+### ❤️ Contributors
+
+- Aaron ([@aklinker1](http://github.com/aklinker1))
+
+## v0.19.21
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/wxt-v0.19.20...wxt-v0.19.21)
+
+### 🩹 Fixes
+
+- Exclude skipped entrypoints from manifest ([#1265](https://github.com/wxt-dev/wxt/pull/1265))
+
+### ❤️ Contributors
+
+- Aaron ([@aklinker1](http://github.com/aklinker1))
+
+## v0.19.20
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/wxt-v0.19.19...wxt-v0.19.20)
+
+### 🚀 Enhancements
+
+- `autoMount` content script UIs ([#1210](https://github.com/wxt-dev/wxt/pull/1210))
+
+### 🩹 Fixes
+
+- Only show reopen browser shortcut when it can be done ([#1263](https://github.com/wxt-dev/wxt/pull/1263))
+- Import entrypoint improvements ([#1207](https://github.com/wxt-dev/wxt/pull/1207))
+
+### ❤️ Contributors
+
+- Aaron ([@aklinker1](http://github.com/aklinker1))
+- 1natsu ([@1natsu172](http://github.com/1natsu172))
+
+## v0.19.19
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/wxt-v0.19.18...wxt-v0.19.19)
+
+### 🚀 Enhancements
+
+- Keyboard shortcut to reopen the browser without restarting the dev command ([#1211](https://github.com/wxt-dev/wxt/pull/1211))
+
+### 🩹 Fixes
+
+- Prevent changing dev server port when reloading config ([#1241](https://github.com/wxt-dev/wxt/pull/1241))
+- Ensure content scripts are registered immediately in dev mode ([#1253](https://github.com/wxt-dev/wxt/pull/1253))
+- Exclude skipped entrypoints from Firefox sources zip ([#1238](https://github.com/wxt-dev/wxt/pull/1238))
+
+### ❤️ Contributors
+
+- Nishu ([@nishu-murmu](http://github.com/nishu-murmu))
+- Aaron ([@aklinker1](http://github.com/aklinker1))
+
+## v0.19.18
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/wxt-v0.19.17...wxt-v0.19.18)
+
+### 🩹 Fixes
+
+- Correct `dev.reloadCommand` restriction to consider only commands with suggested keys ([#1226](https://github.com/wxt-dev/wxt/pull/1226))
+
+### 🌊 Types
+
+- Add overloads to `ContentScriptContext#addEventListener` for different targets ([#1245](https://github.com/wxt-dev/wxt/pull/1245))
+
+### 🏡 Chore
+
+- Refactor `findEntrypoints` to return all entrypoints with `skipped` set properly ([#1244](https://github.com/wxt-dev/wxt/pull/1244))
+
+### ❤️ Contributors
+
+- Aaron ([@aklinker1](http://github.com/aklinker1))
+- Jaguar Zhou ([@aiktb](http://github.com/aiktb))
+
+## v0.19.17
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/wxt-v0.19.16...wxt-v0.19.17)
+
+### 🚀 Enhancements
+
+- New `server:created`, `server:started`, and `server:closed` hooks ([#1179](https://github.com/wxt-dev/wxt/pull/1179))
+
+### 🩹 Fixes
+
+- Re-initialize WXT modules correctly during development ([#1176](https://github.com/wxt-dev/wxt/pull/1176))
+- ESLint config being generated when ESLint is not installed. ([#1198](https://github.com/wxt-dev/wxt/pull/1198))
+- Update `vite` dependency range to support v6 ([#1215](https://github.com/wxt-dev/wxt/pull/1215))
+- Automatically convert MV3 `content_security_policy` to MV2 ([#1168](https://github.com/wxt-dev/wxt/pull/1168))
+- Correctly remove child elements with integrated UI remove ([#1219](https://github.com/wxt-dev/wxt/pull/1219))
+- Make content script `matches` optional ([#1220](https://github.com/wxt-dev/wxt/pull/1220))
+
+### 📖 Documentation
+
+- Fix analyze typo in type ([#1187](https://github.com/wxt-dev/wxt/pull/1187))
+
+### ❤️ Contributors
+
+- Aaron ([@aklinker1](http://github.com/aklinker1))
+- 1natsu ([@1natsu172](http://github.com/1natsu172))
+- Nishu ([@nishu-murmu](https://github.com/nishu-murmu))
+- Florian Metz ([@Timeraa](http://github.com/Timeraa))
+
+## v0.19.16
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/wxt-v0.19.15...wxt-v0.19.16)
+
+### 🚀 Enhancements
+
+- **hooks:** Add new `config:resolved` hook ([#1177](https://github.com/wxt-dev/wxt/pull/1177))
+
+### ❤️ Contributors
+
+- Aaron ([@aklinker1](http://github.com/aklinker1))
+
+## v0.19.15
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/wxt-v0.19.14...wxt-v0.19.15)
+
+### 🚀 Enhancements
+
+- Extract `wxt/storage` to its own package, `@wxt-dev/storage` ([#1129](https://github.com/wxt-dev/wxt/pull/1129))
+
+### 🩹 Fixes
+
+- Add "/" to `PublicPath` and `browser.runtime.getURL` ([#1171](https://github.com/wxt-dev/wxt/pull/1171))
+- Add extension ID to event used to invalidate `ContentScriptContext` ([#1175](https://github.com/wxt-dev/wxt/pull/1175))
+
+### ❤️ Contributors
+
+- Aaron ([@aklinker1](http://github.com/aklinker1))
+- Nishu ([@nishu-murmu](http://github.com/nishu-murmu))
+
+## v0.19.14
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/wxt-v0.19.13...wxt-v0.19.14)
+
+### 🚀 Enhancements
+
+- **storage:** Support storage items in batch functions ([#990](https://github.com/wxt-dev/wxt/pull/990))
+- Automatically disable 'Show warning about Self-XSS when pasing code' in new chrome ([#1159](https://github.com/wxt-dev/wxt/pull/1159))
+
+### 🩹 Fixes
+
+- Throw when config file does not exist ([#1156](https://github.com/wxt-dev/wxt/pull/1156))
+
+### 📖 Documentation
+
+- Cleanup typos and broken links ([bb5ea34](https://github.com/wxt-dev/wxt/commit/bb5ea34))
+- Fix typo in `popup` and `options` EntrypointOptions ([#1121](https://github.com/wxt-dev/wxt/pull/1121))
+
+### 🏡 Chore
+
+- **deps:** Upgrade all non-major dependencies ([#1164](https://github.com/wxt-dev/wxt/pull/1164))
+- **deps:** Bump dev and non-breaking major dependencies ([#1167](https://github.com/wxt-dev/wxt/pull/1167))
+
+### ❤️ Contributors
+
+- Aaron ([@aklinker1](http://github.com/aklinker1))
+- Rxliuli ([@rxliuli](http://github.com/rxliuli))
+- Kongmoumou ([@kongmoumou](http://github.com/kongmoumou))
+- Florian Metz ([@Timeraa](http://github.com/Timeraa))
+- Bread Grocery <breadgrocery@gmail.com>
+
+## v0.19.13
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/wxt-v0.19.12...wxt-v0.19.13)
+
+### 🚀 Enhancements
+
+- **env:** Load env from `.env.[browser]` variants ([#1078](https://github.com/wxt-dev/wxt/pull/1078))
+
+### 🩹 Fixes
+
+- Don't use `#private` member variables in `ContentScriptContext` ([#1103](https://github.com/wxt-dev/wxt/pull/1103))
+
+### ❤️ Contributors
+
+- Aaron ([@aklinker1](http://github.com/aklinker1))
+- Craig Slusher ([@sleekslush](http://github.com/sleekslush))
+
 ## v0.19.12
 
 [compare changes](https://github.com/wxt-dev/wxt/compare/wxt-v0.19.11...wxt-v0.19.12)

packages/wxt/README.md

@@ -76,6 +76,12 @@ Or see the [installation guide](https://wxt.dev/guide/installation.html) to get
 - 📏 Bundle analysis
 - ⬇️ Download and bundle remote URL imports
 
+## Sponsors
+
+WXT is a [MIT-licensed](https://github.com/wxt-dev/wxt/blob/main/LICENSE) open source project with its ongoing development made possible entirely by the support of these awesome backers. If you'd like to join them, please consider [sponsoring WXT's development](https://github.com/sponsors/wxt-dev).
+
+<a href="https://github.com/sponsors/wxt-dev"><img alt="WXT Sponsors" src="https://raw.githubusercontent.com/wxt-dev/static/refs/heads/main/sponsorkit/sponsors.svg"></a>
+
 ## Contributors
 
 <!-- automd:contributors author="aklinker1" license="MIT" github="wxt-dev/wxt" -->

packages/wxt/e2e/tests/__snapshots__/auto-imports.test.ts.snap

@@ -8,6 +8,7 @@ exports[`Auto Imports > eslintrc > "enabled: 8" should output a JSON config file
     "ContentScriptContext": true,
     "InvalidMatchPattern": true,
     "MatchPattern": true,
+    "MigrationError": true,
     "browser": true,
     "createIframeUi": true,
     "createIntegratedUi": true,
@@ -34,6 +35,7 @@ const globals = {
   "ContentScriptContext": true,
   "InvalidMatchPattern": true,
   "MatchPattern": true,
+  "MigrationError": true,
   "browser": true,
   "createIframeUi": true,
   "createIntegratedUi": true,
@@ -68,6 +70,7 @@ exports[`Auto Imports > eslintrc > "enabled: true" should output a JSON config f
     "ContentScriptContext": true,
     "InvalidMatchPattern": true,
     "MatchPattern": true,
+    "MigrationError": true,
     "browser": true,
     "createIframeUi": true,
     "createIntegratedUi": true,
@@ -95,6 +98,7 @@ exports[`Auto Imports > eslintrc > should allow customizing the output 1`] = `
     "ContentScriptContext": "readonly",
     "InvalidMatchPattern": "readonly",
     "MatchPattern": "readonly",
+    "MigrationError": "readonly",
     "browser": "readonly",
     "createIframeUi": "readonly",
     "createIntegratedUi": "readonly",

packages/wxt/e2e/tests/auto-imports.test.ts

@@ -20,6 +20,7 @@ describe('Auto Imports', () => {
             const ContentScriptContext: typeof import('wxt/client')['ContentScriptContext']
             const InvalidMatchPattern: typeof import('wxt/sandbox')['InvalidMatchPattern']
             const MatchPattern: typeof import('wxt/sandbox')['MatchPattern']
+            const MigrationError: typeof import('wxt/storage')['MigrationError']
             const browser: typeof import('wxt/browser')['browser']
             const createIframeUi: typeof import('wxt/client')['createIframeUi']
             const createIntegratedUi: typeof import('wxt/client')['createIntegratedUi']
@@ -151,6 +152,40 @@ describe('Auto Imports', () => {
       ).toMatchSnapshot();
     });
 
+    it('"enabled: false" should NOT output an ESlint config file', async () => {
+      const project = new TestProject();
+      project.addFile('entrypoints/popup.html', `<html></html>`);
+
+      await project.prepare({
+        imports: {
+          eslintrc: {
+            enabled: false,
+          },
+        },
+      });
+
+      expect(await project.fileExists('.wxt/eslint-auto-imports.mjs')).toBe(
+        false,
+      );
+      expect(await project.fileExists('.wxt/eslintrc-auto-import.json')).toBe(
+        false,
+      );
+    });
+
+    it('should NOT output an ESlint config file by default', async () => {
+      const project = new TestProject();
+      project.addFile('entrypoints/popup.html', `<html></html>`);
+
+      await project.prepare();
+
+      expect(await project.fileExists('.wxt/eslint-auto-imports.mjs')).toBe(
+        false,
+      );
+      expect(await project.fileExists('.wxt/eslintrc-auto-import.json')).toBe(
+        false,
+      );
+    });
+
     it('should allow customizing the output', async () => {
       const project = new TestProject();
       project.addFile('entrypoints/popup.html', `<html></html>`);

packages/wxt/e2e/tests/dev.test.ts

@@ -0,0 +1,24 @@
+import { describe, it, expect } from 'vitest';
+import { TestProject } from '../utils';
+
+describe('Dev Mode', () => {
+  it('should not change ports when restarting the server', async () => {
+    const project = new TestProject();
+    project.addFile(
+      'entrypoints/background.ts',
+      'export default defineBackground(() => {})',
+    );
+
+    const server = await project.startServer({
+      runner: {
+        disabled: true,
+      },
+    });
+    const initialPort = server.port;
+    await server.restart();
+    const finalPort = server.port;
+    await server.stop();
+
+    expect(finalPort).toBe(initialPort);
+  });
+});

packages/wxt/e2e/tests/hooks.test.ts

@@ -4,6 +4,7 @@ import { WxtHooks } from '../../src/types';
 
 const hooks: WxtHooks = {
   ready: vi.fn(),
+  'config:resolved': vi.fn(),
   'prepare:types': vi.fn(),
   'prepare:publicPaths': vi.fn(),
   'build:before': vi.fn(),
@@ -20,6 +21,9 @@ const hooks: WxtHooks = {
   'zip:sources:start': vi.fn(),
   'zip:sources:done': vi.fn(),
   'zip:done': vi.fn(),
+  'server:created': vi.fn(),
+  'server:started': vi.fn(),
+  'server:closed': vi.fn(),
 };
 
 function expectHooksToBeCalled(
@@ -49,6 +53,7 @@ describe('Hooks', () => {
 
     expectHooksToBeCalled({
       ready: true,
+      'config:resolved': true,
       'prepare:types': true,
       'prepare:publicPaths': true,
       'build:before': false,
@@ -65,6 +70,9 @@ describe('Hooks', () => {
       'zip:sources:start': false,
       'zip:sources:done': false,
       'zip:done': false,
+      'server:created': false,
+      'server:started': false,
+      'server:closed': false,
     });
   });
 
@@ -76,6 +84,7 @@ describe('Hooks', () => {
 
     expectHooksToBeCalled({
       ready: true,
+      'config:resolved': true,
       'prepare:types': true,
       'prepare:publicPaths': true,
       'build:before': true,
@@ -92,6 +101,9 @@ describe('Hooks', () => {
       'zip:sources:start': false,
       'zip:sources:done': false,
       'zip:done': false,
+      'server:created': false,
+      'server:started': false,
+      'server:closed': false,
     });
   });
 
@@ -103,6 +115,7 @@ describe('Hooks', () => {
 
     expectHooksToBeCalled({
       ready: true,
+      'config:resolved': true,
       'prepare:types': true,
       'prepare:publicPaths': true,
       'build:before': true,
@@ -119,6 +132,9 @@ describe('Hooks', () => {
       'zip:sources:start': false,
       'zip:sources:done': false,
       'zip:done': true,
+      'server:created': false,
+      'server:started': false,
+      'server:closed': false,
     });
   });
 
@@ -130,6 +146,7 @@ describe('Hooks', () => {
 
     expectHooksToBeCalled({
       ready: true,
+      'config:resolved': true,
       'prepare:types': true,
       'prepare:publicPaths': true,
       'build:before': true,
@@ -137,7 +154,7 @@ describe('Hooks', () => {
       'build:publicAssets': true,
       'build:manifestGenerated': true,
       'entrypoints:grouped': true,
-      'entrypoints:resolved': true,
+      'entrypoints:resolved': 2,
       'vite:build:extendConfig': 1,
       'vite:devServer:extendConfig': false,
       'zip:start': true,
@@ -146,6 +163,9 @@ describe('Hooks', () => {
       'zip:sources:start': true,
       'zip:sources:done': true,
       'zip:done': true,
+      'server:created': false,
+      'server:started': false,
+      'server:closed': false,
     });
   });
 
@@ -159,10 +179,12 @@ describe('Hooks', () => {
         disabled: true,
       },
     });
+    expect(hooks['server:closed']).not.toBeCalled();
     await server.stop();
 
     expectHooksToBeCalled({
       ready: true,
+      'config:resolved': true,
       'prepare:types': true,
       'prepare:publicPaths': true,
       'build:before': true,
@@ -179,6 +201,9 @@ describe('Hooks', () => {
       'zip:sources:start': false,
       'zip:sources:done': false,
       'zip:done': false,
+      'server:created': 1,
+      'server:started': 1,
+      'server:closed': 1,
     });
   });
 });

packages/wxt/e2e/tests/modules.test.ts

@@ -6,7 +6,7 @@ import { normalizePath } from '../../src/core/utils/paths';
 
 describe('Module Helpers', () => {
   describe('options', () => {
-    it('should recieve the options defined in wxt.config.ts based on the configKey field', async () => {
+    it('should receive the options defined in wxt.config.ts based on the configKey field', async () => {
       const options = { key: '123' };
       const reportOptions = vi.fn();
       vi.stubGlobal('reportOptions', reportOptions);

packages/wxt/e2e/tests/typescript-project.test.ts

@@ -48,6 +48,7 @@ describe('TypeScript Project', () => {
 
       declare module "wxt/browser" {
         export type PublicPath =
+          | "/"
           | "/options.html"
           | "/popup.html"
           | "/sandbox.html"

packages/wxt/e2e/tests/user-config.test.ts

@@ -157,4 +157,18 @@ describe('User Config', () => {
       await project.fileExists('.output/test-chrome-mv3-development-dev-build'),
     ).toBe(true);
   });
+
+  it('should throw error when config file not exist', async () => {
+    const project = new TestProject();
+    project.addFile(
+      'src/entrypoints/background.ts',
+      `export default defineBackground(
+        () => console.log('Hello background'),
+      );`,
+    );
+
+    await expect(
+      project.build({ configFile: 'foo.config.ts' }),
+    ).rejects.toThrowError(/not found/);
+  });
 });

packages/wxt/e2e/tests/zip.test.ts

@@ -181,6 +181,42 @@ describe('Zipping', () => {
     );
   });
 
+  it('should exclude skipped entrypoints from respective browser sources zip', async () => {
+    const project = new TestProject({
+      name: 'test',
+      version: '1.0.0',
+    });
+    project.addFile(
+      'entrypoints/not-firefox.content.ts',
+      `export default defineContentScript({
+        matches: ['*://*/*'],
+        exclude: ['firefox'],
+        main() {},
+      });`,
+    );
+    project.addFile(
+      'entrypoints/all.content.ts',
+      `export default defineContentScript({
+        matches: ['*://*/*'],
+        main(ctx) {},
+      });
+`,
+    );
+    const unzipDir = project.resolvePath('.output/test-1.0.0-sources');
+    const sourcesZip = project.resolvePath('.output/test-1.0.0-sources.zip');
+
+    await project.zip({
+      browser: 'firefox',
+    });
+    await extract(sourcesZip, { dir: unzipDir });
+    expect(
+      await project.fileExists(unzipDir, 'entrypoints/not-firefox.content.ts'),
+    ).toBe(false);
+    expect(
+      await project.fileExists(unzipDir, 'entrypoints/all.content.ts'),
+    ).toBe(true);
+  });
+
   it.each(['firefox', 'opera'])(
     'should create sources zip for "%s" browser when sourcesZip is undefined',
     async (browser) => {

packages/wxt/package.json

@@ -1,7 +1,7 @@
 {
   "name": "wxt",
   "type": "module",
-  "version": "0.19.12",
+  "version": "0.19.22",
   "description": "Next gen framework for developing web extensions",
   "repository": {
     "type": "git",
@@ -81,26 +81,27 @@
     "prepack": "pnpm build"
   },
   "dependencies": {
+    "@1natsu/wait-element": "^4.1.2",
     "@aklinker1/rollup-plugin-visualizer": "5.12.0",
-    "@types/chrome": "^0.0.269",
-    "@types/webextension-polyfill": "^0.10.7",
+    "@types/chrome": "^0.0.280",
+    "@types/webextension-polyfill": "^0.12.1",
     "@webext-core/fake-browser": "^1.3.1",
     "@webext-core/isolated-element": "^1.1.2",
     "@webext-core/match-patterns": "^1.0.3",
+    "@wxt-dev/storage": "workspace:^1.0.0",
     "async-mutex": "^0.5.0",
     "c12": "^1.11.2",
     "cac": "^6.7.14",
     "chokidar": "^3.6.0",
-    "ci-info": "^4.0.0",
+    "ci-info": "^4.1.0",
     "consola": "^3.2.3",
     "defu": "^6.1.4",
-    "dequal": "^2.0.3",
     "dotenv": "^16.4.5",
     "esbuild": "^0.21.5",
     "fast-glob": "^3.3.2",
     "filesize": "^10.1.6",
     "fs-extra": "^11.2.0",
-    "get-port": "^7.1.0",
+    "get-port-please": "^3.1.2",
     "giget": "^1.2.3",
     "hookable": "^5.5.3",
     "is-wsl": "^3.1.0",
@@ -110,40 +111,40 @@
     "linkedom": "^0.18.5",
     "magicast": "^0.3.5",
     "minimatch": "^10.0.1",
-    "nano-spawn": "^0.1.0",
+    "nano-spawn": "^0.2.0",
     "normalize-path": "^3.0.0",
     "nypm": "^0.3.12",
     "ohash": "^1.1.4",
     "open": "^10.1.0",
-    "ora": "^8.1.0",
+    "ora": "^8.1.1",
     "perfect-debounce": "^1.0.0",
-    "picocolors": "^1.1.0",
+    "picocolors": "^1.1.1",
     "prompts": "^2.4.2",
     "publish-browser-extension": "^2.2.2",
     "scule": "^1.3.0",
     "unimport": "^3.13.1",
-    "vite": "^5.4.8",
-    "vite-node": "^2.1.2",
+    "vite": "^5.0.0 || ^6.0.0",
+    "vite-node": "^2.1.4",
     "web-ext-run": "^0.2.1",
     "webextension-polyfill": "^0.12.0"
   },
   "devDependencies": {
     "@aklinker1/check": "^1.4.5",
-    "@faker-js/faker": "^8.4.1",
+    "@faker-js/faker": "^9.2.0",
     "@types/fs-extra": "^11.0.4",
     "@types/lodash.merge": "^4.6.9",
-    "@types/node": "^20.16.10",
+    "@types/node": "^20.17.6",
     "@types/normalize-path": "^3.0.2",
     "@types/prompts": "^2.4.9",
     "extract-zip": "^2.0.1",
-    "happy-dom": "^14.12.3",
+    "happy-dom": "^15.11.4",
     "lodash.merge": "^4.6.2",
-    "oxlint": "^0.9.9",
-    "publint": "^0.2.11",
+    "oxlint": "^0.11.1",
+    "publint": "^0.2.12",
     "tsx": "4.15.7",
-    "typescript": "^5.6.2",
+    "typescript": "^5.6.3",
     "unbuild": "^2.0.0",
-    "vitest": "^2.1.2",
+    "vitest": "^2.1.4",
     "vitest-plugin-random-seed": "^1.1.0"
   },
   "peerDependenciesMeta": {

packages/wxt/src/__tests__/modules.test.ts

@@ -15,7 +15,7 @@ describe('Module Utilities', () => {
 
       wxt.config.vite = () => Promise.resolve(userConfig);
       addViteConfig(wxt, () => moduleConfig);
-      await wxt.hooks.callHook('ready', wxt);
+      await wxt.hooks.callHook('config:resolved', wxt);
       const actual = await wxt.config.vite(wxt.config.env);
 
       expect(actual).toEqual(expected);
@@ -31,7 +31,7 @@ describe('Module Utilities', () => {
 
       wxt.config.vite = () => userConfig;
       addViteConfig(wxt, () => moduleConfig);
-      await wxt.hooks.callHook('ready', wxt);
+      await wxt.hooks.callHook('config:resolved', wxt);
       const actual = await wxt.config.vite(wxt.config.env);
 
       expect(actual).toEqual(expected);
@@ -44,7 +44,7 @@ describe('Module Utilities', () => {
       const wxt = fakeWxt({ hooks: createHooks() });
 
       addImportPreset(wxt, preset);
-      await wxt.hooks.callHook('ready', wxt);
+      await wxt.hooks.callHook('config:resolved', wxt);
 
       expect(wxt.config.imports && wxt.config.imports.presets).toContain(
         preset,
@@ -63,7 +63,7 @@ describe('Module Utilities', () => {
       });
 
       addImportPreset(wxt, preset);
-      await wxt.hooks.callHook('ready', wxt);
+      await wxt.hooks.callHook('config:resolved', wxt);
 
       expect(wxt.config.imports && wxt.config.imports.presets).toHaveLength(2);
     });
@@ -78,7 +78,7 @@ describe('Module Utilities', () => {
       });
 
       addImportPreset(wxt, preset);
-      await wxt.hooks.callHook('ready', wxt);
+      await wxt.hooks.callHook('config:resolved', wxt);
 
       expect(wxt.config.imports).toBe(false);
     });

packages/wxt/src/browser/index.ts

@@ -80,7 +80,6 @@ export type {
   Theme,
   TopSites,
   Types,
-  Urlbar,
   UserScripts,
   WebNavigation,
   WebRequest,

packages/wxt/src/builtin-modules/unimport.ts

@@ -18,7 +18,7 @@ export default defineWxtModule({
     let unimport: Unimport;
 
     // Add user module imports to config
-    wxt.hooks.hook('ready', () => {
+    wxt.hooks.hook('config:resolved', () => {
       const addModuleImports = (module: WxtModule<any>) => {
         if (!module.imports) return;
 
@@ -30,10 +30,10 @@ export default defineWxtModule({
       wxt.config.userModules.forEach(addModuleImports);
     });
 
-    // Create unimport instance AFTER "ready" so any modifications to the
-    // config inside "ready" are applied.
+    // Create unimport instance AFTER "config:resolved" so any modifications to the
+    // config inside "config:resolved" are applied.
     wxt.hooks.afterEach((event) => {
-      if (event.name === 'ready') {
+      if (event.name === 'config:resolved') {
         unimport = createUnimport(options);
       }
     });

packages/wxt/src/client/content-scripts/__tests__/content-script-context.test.ts

@@ -3,7 +3,15 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { ContentScriptContext } from '..';
 import { fakeBrowser } from '@webext-core/fake-browser';
-import { sleep } from '../../../core/utils/time';
+
+/**
+ * When dispatching events on document/window/etc, they are fired on the next
+ * tick of the event loop. So waiting a timeout of 0 will ensure they've been
+ * fired.
+ */
+function waitForEventsToFire() {
+  return new Promise((res) => setTimeout(res));
+}
 
 describe('Content Script Context', () => {
   beforeEach(() => {
@@ -31,11 +39,11 @@ describe('Content Script Context', () => {
     ctx.onInvalidated(onInvalidated);
 
     // Wait for events to run before next tick next tick
-    await sleep(0);
+    await waitForEventsToFire();
 
     // Create a new context after first is initialized, and wait for it to initialize
     new ContentScriptContext(name);
-    await sleep(0);
+    await waitForEventsToFire();
 
     expect(onInvalidated).toBeCalled();
     expect(ctx.isValid).toBe(false);
@@ -47,13 +55,35 @@ describe('Content Script Context', () => {
     ctx.onInvalidated(onInvalidated);
 
     // Wait for events to run before next tick next tick
-    await sleep(0);
+    await waitForEventsToFire();
 
     // Create a new context after first is initialized, and wait for it to initialize
     new ContentScriptContext('test2');
-    await sleep(0);
+    await waitForEventsToFire();
 
     expect(onInvalidated).not.toBeCalled();
     expect(ctx.isValid).toBe(true);
   });
+
+  describe('addEventListener', () => {
+    const context = new ContentScriptContext('test');
+    it('should infer types correctly for the window target', () => {
+      context.addEventListener(window, 'DOMContentLoaded', (_) => {});
+      context.addEventListener(window, 'orientationchange', (_) => {});
+      context.addEventListener(window, 'wxt:locationchange', (_) => {});
+      // @ts-expect-error
+      context.addEventListener(window, 'visibilitychange', (_) => {});
+    });
+
+    it('should infer types correctly for the document target', () => {
+      context.addEventListener(document, 'visibilitychange', (_) => {});
+      context.addEventListener(document, 'readystatechange', (_) => {});
+    });
+
+    it('should infer types correctly for HTML element targets', () => {
+      const button = document.createElement('button');
+      context.addEventListener(button, 'click', (_) => {});
+      context.addEventListener(button, 'mouseover', (_) => {});
+    });
+  });
 });

packages/wxt/src/client/content-scripts/content-script-context.ts

@@ -35,32 +35,34 @@ import { createLocationWatcher } from './location-watcher';
  * ```
  */
 export class ContentScriptContext implements AbortController {
-  private static SCRIPT_STARTED_MESSAGE_TYPE = 'wxt:content-script-started';
+  private static SCRIPT_STARTED_MESSAGE_TYPE = getUniqueEventName(
+    'wxt:content-script-started',
+  );
 
-  #isTopFrame = window.self === window.top;
-  #abortController: AbortController;
-  #locationWatcher = createLocationWatcher(this);
+  private isTopFrame = window.self === window.top;
+  private abortController: AbortController;
+  private locationWatcher = createLocationWatcher(this);
 
   constructor(
     private readonly contentScriptName: string,
     public readonly options?: Omit<ContentScriptDefinition, 'main'>,
   ) {
-    this.#abortController = new AbortController();
+    this.abortController = new AbortController();
 
-    if (this.#isTopFrame) {
-      this.#listenForNewerScripts({ ignoreFirstEvent: true });
-      this.#stopOldScripts();
+    if (this.isTopFrame) {
+      this.listenForNewerScripts({ ignoreFirstEvent: true });
+      this.stopOldScripts();
     } else {
-      this.#listenForNewerScripts();
+      this.listenForNewerScripts();
     }
   }
 
   get signal() {
-    return this.#abortController.signal;
+    return this.abortController.signal;
   }
 
   abort(reason?: any): void {
-    return this.#abortController.abort(reason);
+    return this.abortController.abort(reason);
   }
 
   get isInvalid(): boolean {
@@ -173,27 +175,39 @@ export class ContentScriptContext implements AbortController {
    * ctx.addEventListener(document, "visibilitychange", () => {
    *   // ...
    * });
-   * ctx.addEventListener(document, "wxt:locationchange", () => {
+   * ctx.addEventListener(window, "wxt:locationchange", () => {
    *   // ...
    * });
    */
-  addEventListener<
-    TTarget extends EventTarget,
-    TType extends keyof WxtContentScriptEventMap,
-  >(
-    target: TTarget,
+  addEventListener<TType extends keyof WxtWindowEventMap>(
+    target: Window,
     type: TType,
-    handler: (event: WxtContentScriptEventMap[TType]) => void,
+    handler: (event: WxtWindowEventMap[TType]) => void,
     options?: AddEventListenerOptions,
-  ) {
+  ): void;
+  addEventListener<TType extends keyof DocumentEventMap>(
+    target: Document,
+    type: keyof DocumentEventMap,
+    handler: (event: DocumentEventMap[TType]) => void,
+    options?: AddEventListenerOptions,
+  ): void;
+  addEventListener<TTarget extends EventTarget>(
+    target: TTarget,
+    ...params: Parameters<TTarget['addEventListener']>
+  ): void;
+  addEventListener(
+    target: EventTarget,
+    type: string,
+    handler: (event: Event) => void,
+    options?: AddEventListenerOptions,
+  ): void {
     if (type === 'wxt:locationchange') {
       // Start the location watcher when adding the event for the first time
-      if (this.isValid) this.#locationWatcher.run();
+      if (this.isValid) this.locationWatcher.run();
     }
 
     target.addEventListener?.(
       type.startsWith('wxt:') ? getUniqueEventName(type) : type,
-      // @ts-expect-error: Event don't match, but that's OK, EventTarget doesn't allow custom types in the callback
       handler,
       {
         ...options,
@@ -213,7 +227,7 @@ export class ContentScriptContext implements AbortController {
     );
   }
 
-  #stopOldScripts() {
+  stopOldScripts() {
     // Use postMessage so it get's sent to all the frames of the page.
     window.postMessage(
       {
@@ -224,7 +238,7 @@ export class ContentScriptContext implements AbortController {
     );
   }
 
-  #listenForNewerScripts(options?: { ignoreFirstEvent?: boolean }) {
+  listenForNewerScripts(options?: { ignoreFirstEvent?: boolean }) {
     let isFirst = true;
 
     const cb = (event: MessageEvent) => {
@@ -245,6 +259,6 @@ export class ContentScriptContext implements AbortController {
   }
 }
 
-interface WxtContentScriptEventMap extends WindowEventMap {
+export interface WxtWindowEventMap extends WindowEventMap {
   'wxt:locationchange': WxtLocationChangeEvent;
 }

packages/wxt/src/client/content-scripts/custom-events.ts

@@ -15,12 +15,5 @@ export class WxtLocationChangeEvent extends Event {
  * Returns an event name unique to the extension and content script that's running.
  */
 export function getUniqueEventName(eventName: string): string {
-  // During the build process, import.meta.env is not defined when importing
-  // entrypoints to get their metadata.
-  const entrypointName =
-    typeof import.meta.env === 'undefined'
-      ? 'build'
-      : import.meta.env.ENTRYPOINT;
-
-  return `${browser?.runtime?.id}:${entrypointName}:${eventName}`;
+  return `${browser?.runtime?.id}:${import.meta.env.ENTRYPOINT}:${eventName}`;
 }

packages/wxt/src/client/content-scripts/ui/__tests__/index.test.ts

@@ -1,12 +1,43 @@
 /** @vitest-environment happy-dom */
-import { describe, it, beforeEach, vi, expect } from 'vitest';
-import { createIntegratedUi, createIframeUi, createShadowRootUi } from '..';
+import { describe, it, beforeEach, afterEach, vi, expect } from 'vitest';
+import {
+  createIntegratedUi,
+  createIframeUi,
+  createShadowRootUi,
+  ContentScriptUi,
+} from '..';
 import { ContentScriptContext } from '../../content-script-context';
 
+/**
+ * Util for floating promise.
+ */
+async function runMicrotasks() {
+  return await new Promise((resolve) => setTimeout(resolve, 0));
+}
+
 function appendTestApp(container: HTMLElement) {
   container.innerHTML = '<app>Hello world</app>';
 }
 
+function appendTestElement({
+  tagName = 'div',
+  id,
+}: {
+  tagName?: string;
+  id: string;
+}) {
+  const parent = document.querySelector('#parent');
+  if (!parent) {
+    throw Error(
+      'Parent element not found. Please check the testing environment DOM',
+    );
+  }
+  const element = document.createElement(tagName);
+  element.id = id;
+  parent.append(element);
+  return element;
+}
+
 const fetch = vi.fn();
 
 describe('Content Script UIs', () => {
@@ -480,4 +511,223 @@ describe('Content Script UIs', () => {
       });
     });
   });
+
+  /**
+   * Need call runMicrotasks after floating-promise and append/remove dom
+   */
+  describe('auto mount', () => {
+    const DYNAMIC_CHILD_ID = 'dynamic-child';
+    let ui: ContentScriptUi<any>;
+    beforeEach(async () => {
+      ui?.remove();
+      await runMicrotasks();
+    });
+    afterEach(async () => {
+      ui?.remove();
+      await runMicrotasks();
+    });
+
+    describe.each([
+      {
+        name: 'integrated',
+        createUiFunction: createIntegratedUi,
+        uiSelector: 'div[data-wxt-integrated]',
+      },
+      {
+        name: 'iframe',
+        createUiFunction: createIframeUi,
+        uiSelector: 'div[data-wxt-iframe]',
+      },
+      {
+        name: 'shadow-root',
+        createUiFunction: createShadowRootUi,
+        uiSelector: 'test-component[data-wxt-shadow-root]',
+      },
+    ] as const)(
+      'built-in UI type: $name',
+      ({ name, createUiFunction, uiSelector }) => {
+        it('should mount when an anchor is dynamically added and unmount when an anchor is removed', async () => {
+          const onMount = vi.fn(appendTestApp);
+          const onRemove = vi.fn();
+          ui = await createUiFunction(ctx, {
+            position: 'inline',
+            onMount,
+            onRemove,
+            anchor: `#parent > #${DYNAMIC_CHILD_ID}`,
+            page: name === 'iframe' ? '/page.html' : undefined,
+            name: 'test-component',
+          });
+          let dynamicEl;
+          ui.autoMount();
+          await runMicrotasks();
+
+          for (let index = 0; index < 3; index++) {
+            await expect
+              .poll(() => document.querySelector(uiSelector))
+              .toBeNull();
+
+            dynamicEl = appendTestElement({ id: DYNAMIC_CHILD_ID });
+            await runMicrotasks();
+            await expect
+              .poll(() => document.querySelector(uiSelector))
+              .not.toBeNull();
+
+            dynamicEl.remove();
+            await runMicrotasks();
+          }
+
+          expect(onMount).toHaveBeenCalledTimes(3);
+          expect(onRemove).toHaveBeenCalledTimes(3);
+        });
+
+        describe('options', () => {
+          it('should auto-mount only once mount and remove when the `once` option is true', async () => {
+            const onMount = vi.fn(appendTestApp);
+            const onRemove = vi.fn();
+            ui = await createUiFunction(ctx, {
+              position: 'inline',
+              onMount,
+              onRemove,
+              anchor: `#parent > #${DYNAMIC_CHILD_ID}`,
+              page: name === 'iframe' ? '/page.html' : undefined,
+              name: 'test-component',
+            });
+            let dynamicEl;
+            ui.autoMount({ once: true });
+            await runMicrotasks();
+            await expect
+              .poll(() => document.querySelector(uiSelector))
+              .toBeNull();
+
+            dynamicEl = appendTestElement({ id: DYNAMIC_CHILD_ID });
+            await runMicrotasks();
+            await expect
+              .poll(() => document.querySelector(uiSelector))
+              .not.toBeNull();
+
+            dynamicEl.remove();
+            await runMicrotasks();
+            expect(onMount).toHaveBeenCalledTimes(1);
+            expect(onRemove).toHaveBeenCalledTimes(1);
+
+            // re-append after once cycle
+            dynamicEl = appendTestElement({ id: DYNAMIC_CHILD_ID });
+            await runMicrotasks();
+
+            // expect stop automount
+            await expect
+              .poll(() => document.querySelector(uiSelector))
+              .toBeNull();
+            expect(onMount).toHaveBeenCalledTimes(1);
+            expect(onRemove).toHaveBeenCalledTimes(1);
+          });
+        });
+
+        describe('invalid anchors', () => {
+          it('should throw when anchor is set as type Element', async () => {
+            ui = await createUiFunction(ctx, {
+              position: 'inline',
+              onMount: appendTestApp,
+              anchor: document.documentElement,
+              page: name === 'iframe' ? '/page.html' : undefined,
+              name: 'test-component',
+            });
+            expect(() => ui.autoMount()).toThrowError(
+              'autoMount and Element anchor option cannot be combined. Avoid passing `Element` directly or `() => Element` to the anchor.',
+            );
+          });
+
+          it('should throw when anchor is set as type `() => Element`', async () => {
+            ui = await createUiFunction(ctx, {
+              position: 'inline',
+              onMount: appendTestApp,
+              anchor: () => document.documentElement,
+              page: name === 'iframe' ? '/page.html' : undefined,
+              name: 'test-component',
+            });
+            expect(() => ui.autoMount()).toThrowError(
+              'autoMount and Element anchor option cannot be combined. Avoid passing `Element` directly or `() => Element` to the anchor.',
+            );
+          });
+        });
+
+        describe('StopAutoMount', () => {
+          it('should stop auto-mounting and remove ui when `ui.remove` is called', async () => {
+            const onMount = vi.fn(appendTestApp);
+            const onRemove = vi.fn();
+            ui = await createUiFunction(ctx, {
+              position: 'inline',
+              onMount,
+              onRemove,
+              anchor: `#parent > #${DYNAMIC_CHILD_ID}`,
+              page: name === 'iframe' ? '/page.html' : undefined,
+              name: 'test-component',
+            });
+            let dynamicEl;
+            ui.autoMount();
+            await runMicrotasks();
+
+            dynamicEl = appendTestElement({ id: DYNAMIC_CHILD_ID });
+            await runMicrotasks();
+            await expect
+              .poll(() => document.querySelector(uiSelector))
+              .not.toBeNull();
+
+            dynamicEl.remove();
+            await runMicrotasks();
+            expect(onMount).toHaveBeenCalledTimes(1);
+            expect(onRemove).toHaveBeenCalledTimes(1);
+
+            ui.remove();
+
+            dynamicEl = appendTestElement({ id: DYNAMIC_CHILD_ID });
+            dynamicEl.remove();
+            await runMicrotasks();
+            expect(onMount).toHaveBeenCalledTimes(1);
+            expect(onRemove).toHaveBeenCalledTimes(2);
+          });
+
+          it('should call internal StopAutoMount when `ui.remove` is called', async () => {
+            const onMount = vi.fn(appendTestApp);
+            const onRemove = vi.fn();
+            const onStop = vi.fn();
+            ui = await createUiFunction(ctx, {
+              position: 'inline',
+              onMount,
+              onRemove,
+              anchor: `#parent > #${DYNAMIC_CHILD_ID}`,
+              page: name === 'iframe' ? '/page.html' : undefined,
+              name: 'test-component',
+            });
+            ui.autoMount({ onStop });
+            ui.remove();
+            expect(onStop).toHaveBeenCalledTimes(1);
+            expect(onRemove).toHaveBeenCalledTimes(1);
+          });
+
+          it('should allow calling automount again after internal StopAutoMount is called', async () => {
+            const onMount = vi.fn(appendTestApp);
+            ui = await createUiFunction(ctx, {
+              position: 'inline',
+              onMount,
+              anchor: `#parent > #${DYNAMIC_CHILD_ID}`,
+              page: name === 'iframe' ? '/page.html' : undefined,
+              name: 'test-component',
+            });
+            const onStop = vi.fn();
+            ui.autoMount({ onStop });
+            ui.autoMount({ onStop });
+
+            ui.remove();
+            expect(onStop).toBeCalledTimes(1);
+
+            ui.autoMount({ onStop });
+
+            ui.remove();
+            expect(onStop).toBeCalledTimes(2);
+          });
+        });
+      },
+    );
+  });
 });

packages/wxt/src/client/content-scripts/ui/index.ts

@@ -1,12 +1,22 @@
 import { browser } from 'wxt/browser';
+import { waitElement } from '@1natsu/wait-element';
+import {
+  isExist as mountDetector,
+  isNotExist as removeDetector,
+} from '@1natsu/wait-element/detectors';
 import { ContentScriptContext } from '..';
 import {
+  AutoMount,
+  AutoMountOptions,
+  BaseMountFunctions,
   ContentScriptAnchoredOptions,
   ContentScriptPositioningOptions,
+  ContentScriptUiOptions,
   IframeContentScriptUi,
   IframeContentScriptUiOptions,
   IntegratedContentScriptUi,
   IntegratedContentScriptUiOptions,
+  MountFunctions,
   ShadowRootContentScriptUi,
   ShadowRootContentScriptUiOptions,
 } from './types';
@@ -34,10 +44,19 @@ export function createIntegratedUi<TMounted>(
   };
   const remove = () => {
     options.onRemove?.(mounted);
+    wrapper.replaceChildren();
     wrapper.remove();
     mounted = undefined;
   };
 
+  const mountFunctions = createMountFunctions(
+    {
+      mount,
+      remove,
+    },
+    options,
+  );
+
   ctx.onInvalidated(remove);
 
   return {
@@ -45,8 +64,7 @@ export function createIntegratedUi<TMounted>(
       return mounted;
     },
     wrapper,
-    mount,
-    remove,
+    ...mountFunctions,
   };
 }
 
@@ -78,6 +96,14 @@ export function createIframeUi<TMounted>(
     mounted = undefined;
   };
 
+  const mountFunctions = createMountFunctions(
+    {
+      mount,
+      remove,
+    },
+    options,
+  );
+
   ctx.onInvalidated(remove);
 
   return {
@@ -86,8 +112,7 @@ export function createIframeUi<TMounted>(
     },
     iframe,
     wrapper,
-    mount,
-    remove,
+    ...mountFunctions,
   };
 }
 
@@ -96,7 +121,7 @@ export function createIframeUi<TMounted>(
  *
  * > This function is async because it has to load the CSS via a network call.
  *
- * @see https://wxt.dev/guide/essentials/content-scripts.html#shadowroot
+ * @see https://wxt.dev/guide/essentials/content-scripts.html#shadow-root
  */
 export async function createShadowRootUi<TMounted>(
   ctx: ContentScriptContext,
@@ -136,7 +161,7 @@ export async function createShadowRootUi<TMounted>(
   const remove = () => {
     // Cleanup mounted state
     options.onRemove?.(mounted);
-    // Detatch shadow root from DOM
+    // Detach shadow root from DOM
     shadowHost.remove();
     // Remove children from uiContainer
     while (uiContainer.lastChild)
@@ -145,14 +170,21 @@ export async function createShadowRootUi<TMounted>(
     mounted = undefined;
   };
 
+  const mountFunctions = createMountFunctions(
+    {
+      mount,
+      remove,
+    },
+    options,
+  );
+
   ctx.onInvalidated(remove);
 
   return {
     shadow,
     shadowHost,
     uiContainer,
-    mount,
-    remove,
+    ...mountFunctions,
     get mounted() {
       return mounted;
     },
@@ -255,6 +287,107 @@ function mountUi(
   }
 }
 
+function createMountFunctions<TMounted>(
+  baseFunctions: BaseMountFunctions,
+  options: ContentScriptUiOptions<TMounted>,
+): MountFunctions {
+  let autoMountInstance: AutoMount | undefined = undefined;
+
+  const stopAutoMount = () => {
+    autoMountInstance?.stopAutoMount();
+    autoMountInstance = undefined;
+  };
+
+  const mount = () => {
+    baseFunctions.mount();
+  };
+
+  const unmount = baseFunctions.remove;
+
+  const remove = () => {
+    stopAutoMount();
+    baseFunctions.remove();
+  };
+
+  const autoMount = (autoMountOptions?: AutoMountOptions) => {
+    if (autoMountInstance) {
+      logger.warn('autoMount is already set.');
+    }
+    autoMountInstance = autoMountUi(
+      { mount, unmount, stopAutoMount },
+      {
+        ...options,
+        ...autoMountOptions,
+      },
+    );
+  };
+
+  return {
+    mount,
+    remove,
+    autoMount,
+  };
+}
+
+function autoMountUi(
+  uiCallbacks: {
+    mount: () => void;
+    unmount: () => void;
+    stopAutoMount: () => void;
+  },
+  options: ContentScriptAnchoredOptions & AutoMountOptions,
+): AutoMount {
+  const abortController = new AbortController();
+  const EXPLICIT_STOP_REASON = 'explicit_stop_auto_mount';
+  const _stopAutoMount = () => {
+    abortController.abort(EXPLICIT_STOP_REASON);
+    options.onStop?.();
+  };
+
+  let resolvedAnchor =
+    typeof options.anchor === 'function' ? options.anchor() : options.anchor;
+  if (resolvedAnchor instanceof Element) {
+    throw Error(
+      'autoMount and Element anchor option cannot be combined. Avoid passing `Element` directly or `() => Element` to the anchor.',
+    );
+  }
+
+  async function observeElement(selector: string | null | undefined) {
+    let isAnchorExist = !!getAnchor(options);
+
+    while (!abortController.signal.aborted) {
+      try {
+        const changedAnchor = await waitElement(selector ?? 'body', {
+          customMatcher: () => getAnchor(options) ?? null,
+          detector: isAnchorExist ? removeDetector : mountDetector,
+          signal: abortController.signal,
+        });
+        isAnchorExist = !!changedAnchor;
+        if (isAnchorExist) {
+          uiCallbacks.mount();
+        } else {
+          uiCallbacks.unmount();
+          if (options.once) {
+            uiCallbacks.stopAutoMount();
+          }
+        }
+      } catch (error) {
+        if (
+          abortController.signal.aborted &&
+          abortController.signal.reason === EXPLICIT_STOP_REASON
+        ) {
+          break;
+        } else {
+          throw error;
+        }
+      }
+    }
+  }
+  observeElement(resolvedAnchor);
+
+  return { stopAutoMount: _stopAutoMount };
+}
+
 /**
  * Load the CSS for the current entrypoint.
  */

packages/wxt/src/client/content-scripts/ui/types.ts

@@ -36,18 +36,7 @@ export interface ShadowRootContentScriptUi<TMounted>
   shadow: ShadowRoot;
 }
 
-export interface ContentScriptUi<TMounted> {
-  /**
-   * Function that mounts or remounts the UI on the page.
-   */
-  mount: () => void;
-  /**
-   * Function that removes the UI from the webpage.
-   */
-  remove: () => void;
-  /**>
-   * Custom data returned from the `options.mount` function.
-   */
+export interface ContentScriptUi<TMounted> extends MountFunctions {
   mounted: TMounted | undefined;
 }
 
@@ -216,3 +205,40 @@ export interface ContentScriptAnchoredOptions {
    */
   append?: ContentScriptAppendMode | ((anchor: Element, ui: Element) => void);
 }
+
+export interface BaseMountFunctions {
+  /**
+   * Function that mounts or remounts the UI on the page.
+   */
+  mount: () => void;
+
+  /**
+   * Function that removes the UI from the webpage.
+   */
+  remove: () => void;
+}
+
+export interface MountFunctions extends BaseMountFunctions {
+  /**
+   * Call `ui.autoMount()` to automatically mount and remove the UI as the anchor is dynamically added/removed by the webpage.
+   */
+  autoMount: (options?: AutoMountOptions) => void;
+}
+
+export type AutoMountOptions = {
+  /**
+   * When true, only mount and unmount a UI once.
+   */
+  once?: boolean;
+  /**
+   * The callback triggered when `StopAutoMount` is called.
+   */
+  onStop?: () => void;
+};
+export type StopAutoMount = () => void;
+export interface AutoMount {
+  /**
+   * Stop watching the anchor element for changes, but keep the UI mounted.
+   */
+  stopAutoMount: StopAutoMount;
+}

packages/wxt/src/core/builders/vite/index.ts

@@ -24,11 +24,13 @@ import { importEntrypointFile } from '../../utils/building';
 import { ViteNodeServer } from 'vite-node/server';
 import { ViteNodeRunner } from 'vite-node/client';
 import { installSourcemapsSupport } from 'vite-node/source-map';
+import { createExtensionEnvironment } from '../../utils/environments';
+import { relative } from 'node:path';
 
 export async function createViteBuilder(
   wxtConfig: ResolvedConfig,
   hooks: Hookable<WxtHooks>,
-  server?: WxtDevServer,
+  getWxtDevServer?: () => WxtDevServer | undefined,
 ): Promise<WxtBuilder> {
   const vite = await import('vite');
 
@@ -65,6 +67,8 @@ export async function createViteBuilder(
       ignored: [`${wxtConfig.outBaseDir}/**`, `${wxtConfig.wxtDir}/**`],
     };
 
+    const server = getWxtDevServer?.();
+
     config.plugins ??= [];
     config.plugins.push(
       wxtPlugins.download(wxtConfig),
@@ -193,7 +197,7 @@ export async function createViteBuilder(
   };
 
   /**
-   * Return the basic config for building a sinlge CSS entrypoint in [multi-page mode](https://vitejs.dev/guide/build.html#multi-page-app).
+   * Return the basic config for building a single CSS entrypoint in [multi-page mode](https://vitejs.dev/guide/build.html#multi-page-app).
    */
   const getCssConfig = (entrypoint: Entrypoint): vite.InlineConfig => {
     return {
@@ -218,55 +222,104 @@ export async function createViteBuilder(
     };
   };
 
+  const createViteNodeImporter = async (paths: string[]) => {
+    const baseConfig = await getBaseConfig({
+      excludeAnalysisPlugin: true,
+    });
+    // Disable dep optimization, as recommended by vite-node's README
+    baseConfig.optimizeDeps ??= {};
+    baseConfig.optimizeDeps.noDiscovery = true;
+    baseConfig.optimizeDeps.include = [];
+    const envConfig: vite.InlineConfig = {
+      plugins: paths.map((path) =>
+        wxtPlugins.removeEntrypointMainFunction(wxtConfig, path),
+      ),
+    };
+    const config = vite.mergeConfig(baseConfig, envConfig);
+    const server = await vite.createServer(config);
+    await server.pluginContainer.buildStart({});
+    const node = new ViteNodeServer(
+      // @ts-ignore: Some weird type error...
+      server,
+    );
+    installSourcemapsSupport({
+      getSourceMap: (source) => node.getSourceMap(source),
+    });
+    const runner = new ViteNodeRunner({
+      root: server.config.root,
+      base: server.config.base,
+      // when having the server and runner in a different context,
+      // you will need to handle the communication between them
+      // and pass to this function
+      fetchModule(id) {
+        return node.fetchModule(id);
+      },
+      resolveId(id, importer) {
+        return node.resolveId(id, importer);
+      },
+    });
+    return { runner, server };
+  };
+
+  const requireDefaultExport = (path: string, mod: any) => {
+    const relativePath = relative(wxtConfig.root, path);
+    if (mod?.default == null) {
+      const defineFn = relativePath.includes('.content')
+        ? 'defineContentScript'
+        : relativePath.includes('background')
+          ? 'defineBackground'
+          : 'defineUnlistedScript';
+
+      throw Error(
+        `${relativePath}: Default export not found, did you forget to call "export default ${defineFn}(...)"?`,
+      );
+    }
+  };
+
   return {
     name: 'Vite',
     version: vite.version,
     async importEntrypoint(path) {
+      const env = createExtensionEnvironment();
       switch (wxtConfig.entrypointLoader) {
         default:
         case 'jiti': {
-          return await importEntrypointFile(path);
+          return await env.run(() => importEntrypointFile(path));
         }
         case 'vite-node': {
-          const baseConfig = await getBaseConfig({
-            excludeAnalysisPlugin: true,
-          });
-          // Disable dep optimization, as recommended by vite-node's README
-          baseConfig.optimizeDeps ??= {};
-          baseConfig.optimizeDeps.noDiscovery = true;
-          baseConfig.optimizeDeps.include = [];
-          const envConfig: vite.InlineConfig = {
-            plugins: [wxtPlugins.removeEntrypointMainFunction(wxtConfig, path)],
-          };
-          const config = vite.mergeConfig(baseConfig, envConfig);
-          const server = await vite.createServer(config);
-          await server.pluginContainer.buildStart({});
-          const node = new ViteNodeServer(
-            // @ts-ignore: Some weird type error...
-            server,
-          );
-          installSourcemapsSupport({
-            getSourceMap: (source) => node.getSourceMap(source),
-          });
-          const runner = new ViteNodeRunner({
-            root: server.config.root,
-            base: server.config.base,
-            // when having the server and runner in a different context,
-            // you will need to handle the communication between them
-            // and pass to this function
-            fetchModule(id) {
-              return node.fetchModule(id);
-            },
-            resolveId(id, importer) {
-              return node.resolveId(id, importer);
-            },
-          });
-          const res = await runner.executeFile(path);
+          const { runner, server } = await createViteNodeImporter([path]);
+          const res = await env.run(() => runner.executeFile(path));
           await server.close();
+          requireDefaultExport(path, res);
           return res.default;
         }
       }
     },
+    async importEntrypoints(paths) {
+      const env = createExtensionEnvironment();
+      switch (wxtConfig.entrypointLoader) {
+        default:
+        case 'jiti': {
+          return await env.run(() =>
+            Promise.all(paths.map(importEntrypointFile)),
+          );
+        }
+        case 'vite-node': {
+          const { runner, server } = await createViteNodeImporter(paths);
+          const res = await env.run(() =>
+            Promise.all(
+              paths.map(async (path) => {
+                const mod = await runner.executeFile(path);
+                requireDefaultExport(path, mod);
+                return mod.default;
+              }),
+            ),
+          );
+          await server.close();
+          return res;
+        }
+      }
+    },
     async build(group) {
       let entryConfig;
       if (Array.isArray(group)) entryConfig = getMultiPageConfig(group);

packages/wxt/src/core/create-server.ts

@@ -21,12 +21,13 @@ import { createExtensionRunner } from './runners';
 import { Mutex } from 'async-mutex';
 import pc from 'picocolors';
 import { relative } from 'node:path';
-import { registerWxt, wxt } from './wxt';
+import { deinitWxtModules, initWxtModules, registerWxt, wxt } from './wxt';
 import { unnormalizePath } from './utils/paths';
 import {
   getContentScriptJs,
   mapWxtOptionsToRegisteredContentScript,
 } from './utils/content-scripts';
+import { createKeyboardShortcuts } from './keyboard-shortcuts';
 
 /**
  * Creates a dev server and pre-builds all the files that need to exist before loading the extension.
@@ -40,64 +41,120 @@ import {
 export async function createServer(
   inlineConfig?: InlineConfig,
 ): Promise<WxtDevServer> {
-  await registerWxt('serve', inlineConfig, async (config) => {
-    const { port, hostname } = config.dev.server!;
-    const serverInfo: ServerInfo = {
+  await registerWxt('serve', inlineConfig);
+
+  wxt.server = await createServerInternal();
+  await wxt.hooks.callHook('server:created', wxt, wxt.server);
+  return wxt.server;
+}
+
+async function createServerInternal(): Promise<WxtDevServer> {
+  const getServerInfo = (): ServerInfo => {
+    const { port, hostname } = wxt.config.dev.server!;
+    return {
       port,
       hostname,
       origin: `http://${hostname}:${port}`,
     };
+  };
 
-    // Server instance must be created first so its reference can be added to the internal config used
-    // to pre-render entrypoints
-    const server: WxtDevServer = {
-      ...serverInfo,
-      get watcher() {
-        return builderServer.watcher;
-      },
-      get ws() {
-        return builderServer.ws;
-      },
-      currentOutput: undefined,
-      async start() {
-        await builderServer.listen();
-        wxt.logger.success(`Started dev server @ ${serverInfo.origin}`);
-        await buildAndOpenBrowser();
-      },
-      async stop() {
-        await runner.closeBrowser();
-        await builderServer.close();
-      },
-      async restart() {
-        await closeAndRecreateRunner();
-        await buildAndOpenBrowser();
-      },
-      transformHtml(url, html, originalUrl) {
-        return builderServer.transformHtml(url, html, originalUrl);
-      },
-      reloadContentScript(payload) {
-        server.ws.send('wxt:reload-content-script', payload);
-      },
-      reloadPage(path) {
-        server.ws.send('wxt:reload-page', path);
-      },
-      reloadExtension() {
-        server.ws.send('wxt:reload-extension');
-      },
-      async restartBrowser() {
-        await closeAndRecreateRunner();
-        await runner.openBrowser();
-      },
-    };
-    return server;
-  });
-
-  const server = wxt.server!;
   let [runner, builderServer] = await Promise.all([
     createExtensionRunner(),
-    wxt.builder.createServer(server),
+    wxt.builder.createServer(getServerInfo()),
   ]);
 
+  // Used to track if modules need to be re-initialized
+  let wasStopped = false;
+
+  // Server instance must be created first so its reference can be added to the internal config used
+  // to pre-render entrypoints
+  const server: WxtDevServer = {
+    get hostname() {
+      return getServerInfo().hostname;
+    },
+    get port() {
+      return getServerInfo().port;
+    },
+    get origin() {
+      return getServerInfo().origin;
+    },
+    get watcher() {
+      return builderServer.watcher;
+    },
+    get ws() {
+      return builderServer.ws;
+    },
+    currentOutput: undefined,
+    async start() {
+      if (wasStopped) {
+        await wxt.reloadConfig();
+        runner = await createExtensionRunner();
+        builderServer = await wxt.builder.createServer(getServerInfo());
+        await initWxtModules();
+      }
+
+      await builderServer.listen();
+      wxt.logger.success(`Started dev server @ ${server.origin}`);
+      await wxt.hooks.callHook('server:started', wxt, server);
+
+      // Register content scripts for the first time after the background starts
+      // up since they're not listed in the manifest.
+      // Add listener before opening the browser to guarantee it is present when
+      // the extension sends back the initialization message.
+      server.ws.on('wxt:background-initialized', () => {
+        if (server.currentOutput == null) return;
+        reloadContentScripts(server.currentOutput.steps, server);
+      });
+
+      await buildAndOpenBrowser();
+
+      // Listen for file changes and reload different parts of the extension accordingly
+      const reloadOnChange = createFileReloader(server);
+      server.watcher.on('all', reloadOnChange);
+      keyboardShortcuts.start();
+      keyboardShortcuts.printHelp({
+        canReopenBrowser:
+          !wxt.config.runnerConfig.config.disabled && !!runner.canOpen?.(),
+      });
+    },
+
+    async stop() {
+      wasStopped = true;
+      keyboardShortcuts.stop();
+      await runner.closeBrowser();
+      await builderServer.close();
+      await wxt.hooks.callHook('server:closed', wxt, server);
+
+      deinitWxtModules();
+      server.currentOutput = undefined;
+    },
+    async restart() {
+      await server.stop();
+      await server.start();
+    },
+    transformHtml(url, html, originalUrl) {
+      return builderServer.transformHtml(url, html, originalUrl);
+    },
+    reloadContentScript(payload) {
+      server.ws.send('wxt:reload-content-script', payload);
+    },
+    reloadPage(path) {
+      server.ws.send('wxt:reload-page', path);
+    },
+    reloadExtension() {
+      server.ws.send('wxt:reload-extension');
+    },
+    async restartBrowser() {
+      await runner.closeBrowser();
+      keyboardShortcuts.stop();
+      await wxt.reloadConfig();
+      runner = await createExtensionRunner();
+      await runner.openBrowser();
+      keyboardShortcuts.start();
+    },
+  };
+  const keyboardShortcuts = createKeyboardShortcuts(server);
+
   const buildAndOpenBrowser = async () => {
     // Build after starting the dev server so it can be used to transform HTML files
     server.currentOutput = await internalBuild();
@@ -114,26 +171,6 @@ export async function createServer(
     await runner.openBrowser();
   };
 
-  /**
-   * Stops the previous runner, grabs the latest config, and recreates the runner.
-   */
-  const closeAndRecreateRunner = async () => {
-    await runner.closeBrowser();
-    await wxt.reloadConfig();
-    runner = await createExtensionRunner();
-  };
-
-  // Register content scripts for the first time after the background starts up since they're not
-  // listed in the manifest
-  server.ws.on('wxt:background-initialized', () => {
-    if (server.currentOutput == null) return;
-    reloadContentScripts(server.currentOutput.steps, server);
-  });
-
-  // Listen for file changes and reload different parts of the extension accordingly
-  const reloadOnChange = createFileReloader(server);
-  server.watcher.on('all', reloadOnChange);
-
   return server;
 }
 
@@ -206,6 +243,7 @@ function createFileReloader(server: WxtDevServer) {
             break;
           case 'content-script-reload':
             reloadContentScripts(changes.changedSteps, server);
+
             const rebuiltNames = changes.rebuildGroups
               .flat()
               .map((entry) => entry.name);

packages/wxt/src/core/generate-wxt-dir.ts

@@ -78,6 +78,7 @@ async function getPathsDeclarationEntry(
         isHtmlEntrypoint(entry) ? '.html' : '.js',
       ),
     )
+    .concat([''])
     .concat(await getPublicFiles());
 
   await wxt.hooks.callHook('prepare:publicPaths', wxt, paths);
@@ -176,7 +177,7 @@ declare module "wxt/browser" {
         message.message,
       ),
     ),
-    // Include a final union-based override so TS accepts valid string templates or concatinations
+    // Include a final union-based override so TS accepts valid string templates or concatenations
     // ie: browser.i18n.getMessage(`some_enum_${enumValue}`)
     renderGetMessageOverload(
       messages.map((message) => `"${message.name}"`).join(' | '),

packages/wxt/src/core/keyboard-shortcuts.ts

@@ -0,0 +1,52 @@
+import readline from 'node:readline';
+import { WxtDevServer } from '../types';
+import { wxt } from './wxt';
+import pc from 'picocolors';
+
+export interface KeyboardShortcutWatcher {
+  start(): void;
+  stop(): void;
+  printHelp(flags: { canReopenBrowser: boolean }): void;
+}
+
+/**
+ * Function that creates a keyboard shortcut handler for the extension.
+ */
+export function createKeyboardShortcuts(
+  server: WxtDevServer,
+): KeyboardShortcutWatcher {
+  let rl: readline.Interface | undefined;
+
+  const handleInput = (line: string) => {
+    // Only handle our specific command
+    if (line.trim() === 'o') {
+      server.restartBrowser();
+    }
+  };
+
+  return {
+    start() {
+      if (rl) return;
+
+      rl = readline.createInterface({
+        input: process.stdin,
+        terminal: false, // Don't intercept ctrl+C, ctrl+Z, etc
+      });
+
+      rl.on('line', handleInput);
+    },
+
+    stop() {
+      rl?.close();
+      rl = undefined;
+    },
+
+    printHelp(flags) {
+      if (flags.canReopenBrowser) {
+        wxt.logger.info(
+          `${pc.dim('Press')} ${pc.bold('o + enter')} ${pc.dim('to reopen the browser')}`,
+        );
+      }
+    },
+  };
+}

packages/wxt/src/core/resolve-config.ts

@@ -27,6 +27,7 @@ import { builtinModules } from '../builtin-modules';
 import { getEslintVersion } from './utils/eslint';
 import { safeStringToNumber } from './utils/number';
 import { loadEnv } from './utils/env';
+import { getPort } from 'get-port-please';
 
 /**
  * Given an inline config, discover the config file if necessary, merge the results, resolve any
@@ -53,6 +54,9 @@ export async function resolveConfig(
         esmResolve: true,
       },
     });
+    if (inlineConfig.configFile && metadata.layers?.length === 0) {
+      throw Error(`Config file "${inlineConfig.configFile}" not found`);
+    }
     userConfig = loadedConfig ?? {};
     userConfigMetadata = metadata;
   }
@@ -74,7 +78,7 @@ export async function resolveConfig(
   const mode = mergedConfig.mode ?? COMMAND_MODES[command];
   const env: ConfigEnv = { browser, command, manifestVersion, mode };
 
-  loadEnv(mode); // Load any environment variables used below
+  loadEnv(mode, browser); // Load any environment variables used below
 
   const root = path.resolve(
     inlineConfig.root ?? userConfig.root ?? process.cwd(),
@@ -134,14 +138,19 @@ export async function resolveConfig(
 
   let devServerConfig: ResolvedConfig['dev']['server'];
   if (command === 'serve') {
+    const hostname = mergedConfig.dev?.server?.hostname ?? 'localhost';
     let port = mergedConfig.dev?.server?.port;
     if (port == null || !isFinite(port)) {
-      const { default: getPort, portNumbers } = await import('get-port');
-      port = await getPort({ port: portNumbers(3000, 3010) });
+      port = await getPort({
+        port: 3000,
+        portRange: [3001, 3010],
+        // Passing host required for Mac, unsure of Windows/Linux
+        host: hostname,
+      });
     }
     devServerConfig = {
       port,
-      hostname: mergedConfig.dev?.server?.hostname ?? 'localhost',
+      hostname,
       watchDebounce: safeStringToNumber(process.env.WXT_WATCH_DEBOUNCE) ?? 800,
     };
   }
@@ -383,10 +392,11 @@ async function getUnimportEslintOptions(
     case 'auto':
       const version = await getEslintVersion();
       let major = parseInt(version[0]);
+      if (isNaN(major)) eslintEnabled = false;
       if (major <= 8) eslintEnabled = 8;
       else if (major >= 9) eslintEnabled = 9;
       // NaN
-      else eslintEnabled = 8;
+      else eslintEnabled = false;
       break;
     case true:
       eslintEnabled = 8;

packages/wxt/src/core/runners/web-ext.ts

@@ -11,6 +11,9 @@ export function createWebExtRunner(): ExtensionRunner {
   let runner: WebExtRunInstance | undefined;
 
   return {
+    canOpen() {
+      return true;
+    },
     async openBrowser() {
       const startTime = Date.now();
 
@@ -50,7 +53,10 @@ export function createWebExtRunner(): ExtensionRunner {
                 wxtUserConfig?.chromiumPref,
                 DEFAULT_CHROMIUM_PREFS,
               ),
-              args: wxtUserConfig?.chromiumArgs,
+              args: [
+                '--unsafely-disable-devtools-self-xss-warnings',
+                ...(wxtUserConfig?.chromiumArgs ?? []),
+              ],
             }),
       };
 

packages/wxt/src/core/utils/__tests__/manifest.test.ts

@@ -44,6 +44,7 @@ describe('Manifest Utils', () => {
             defaultTitle: 'Default Iitle',
           },
           outputDir: outDir,
+          skipped: false,
         });
 
       it('should include an action for mv3', async () => {
@@ -209,6 +210,7 @@ describe('Manifest Utils', () => {
           chromeStyle: true,
           browserStyle: true,
         },
+        skipped: false,
       });
 
       it('should include a options_ui and chrome_style for chrome', async () => {
@@ -265,6 +267,7 @@ describe('Manifest Utils', () => {
           persistent: true,
           type: 'module',
         },
+        skipped: false,
       });
 
       describe('MV3', () => {
@@ -368,7 +371,7 @@ describe('Manifest Utils', () => {
 
     describe('icons', () => {
       it('should auto-discover icons with the correct name', async () => {
-        const entrypoints = fakeArray(fakeEntrypoint);
+        const entrypoints = fakeArray(() => fakeEntrypoint({ skipped: false }));
         const buildOutput = fakeBuildOutput({
           publicAssets: [
             { type: 'asset', fileName: 'icon-16.png' },
@@ -396,7 +399,7 @@ describe('Manifest Utils', () => {
       });
 
       it('should return undefined when no icons are found', async () => {
-        const entrypoints = fakeArray(fakeEntrypoint);
+        const entrypoints = fakeArray(() => fakeEntrypoint({ skipped: false }));
         const buildOutput = fakeBuildOutput({
           publicAssets: [
             { type: 'asset', fileName: 'logo.png' },
@@ -413,7 +416,7 @@ describe('Manifest Utils', () => {
       });
 
       it('should allow icons to be overwritten from the wxt.config.ts file', async () => {
-        const entrypoints = fakeArray(fakeEntrypoint);
+        const entrypoints = fakeArray(() => fakeEntrypoint({ skipped: false }));
         const buildOutput = fakeBuildOutput({
           publicAssets: [
             { type: 'asset', fileName: 'icon-16.png' },
@@ -837,6 +840,7 @@ describe('Manifest Utils', () => {
             options: {
               registration: 'runtime',
             },
+            skipped: false,
           });
 
           const entrypoints = [cs];
@@ -902,6 +906,7 @@ describe('Manifest Utils', () => {
         async (browser) => {
           const sidepanel = fakeSidepanelEntrypoint({
             outputDir: outDir,
+            skipped: false,
           });
           const buildOutput = fakeBuildOutput();
 
@@ -934,6 +939,7 @@ describe('Manifest Utils', () => {
         async (browser) => {
           const sidepanel = fakeSidepanelEntrypoint({
             outputDir: outDir,
+            skipped: false,
           });
           const buildOutput = fakeBuildOutput();
 
@@ -1581,6 +1587,64 @@ describe('Manifest Utils', () => {
           permissions: ['tabs', 'scripting'],
         });
       });
+
+      it('should convert MV3 CSP object to MV2 CSP string with localhost for MV2', async () => {
+        const entrypoints: Entrypoint[] = [];
+        const buildOutput = fakeBuildOutput();
+        const inputCsp =
+          "script-src 'self' 'wasm-unsafe-eval'; object-src 'self';";
+        const expectedCsp =
+          "script-src 'self' 'wasm-unsafe-eval' http://localhost:3000; object-src 'self';";
+
+        // Setup WXT for Firefox and serve command
+        setFakeWxt({
+          config: {
+            browser: 'firefox',
+            command: 'serve',
+            manifestVersion: 2,
+            manifest: {
+              content_security_policy: {
+                extension_pages: inputCsp,
+              },
+            },
+          },
+          server: fakeWxtDevServer({
+            port: 3000,
+            hostname: 'localhost',
+            origin: 'http://localhost:3000',
+          }),
+        });
+
+        const { manifest: actual } = await generateManifest(
+          entrypoints,
+          buildOutput,
+        );
+
+        expect(actual.content_security_policy).toEqual(expectedCsp);
+      });
+    });
+
+    it('should not add skipped entrypoints to manifest', async () => {
+      const popup = fakePopupEntrypoint({ skipped: true });
+      const content = fakeContentScriptEntrypoint({ skipped: true });
+      const sidePanel = fakeSidepanelEntrypoint({ skipped: true });
+      const buildOutput = fakeBuildOutput();
+
+      setFakeWxt({
+        config: {
+          command: 'build',
+          manifestVersion: 3,
+        },
+      });
+
+      const { manifest } = await generateManifest(
+        [popup, content, sidePanel],
+        buildOutput,
+      );
+
+      expect(manifest.action).toBeUndefined();
+      expect(manifest.sidebar_action).toBeUndefined();
+      expect(manifest.content_scripts).toBeUndefined();
     });
   });