chore(release): v0.13.3

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

.github/workflows/validate.yml

@@ -80,6 +80,3 @@ jobs:
         working-directory: templates/${{ matrix.template }}
       - run: pnpm build
         working-directory: templates/${{ matrix.template }}
-        env:
-          # Debug Vite 5's deprecated CJS support
-          VITE_CJS_TRACE: true

CHANGELOG.md

@@ -1,5 +1,100 @@
 # Changelog
 
+## v0.13.3
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.13.2...v0.13.3)
+
+### 🚀 Enhancements
+
+- **DX:** Add `ctrl+E`/`cmd+E` shortcut to reload extension during development ([#322](https://github.com/wxt-dev/wxt/pull/322))
+
+### 🏡 Chore
+
+- **deps-dev:** Bump tsx from 4.6.2 to 4.7.0 ([#320](https://github.com/wxt-dev/wxt/pull/320))
+- **deps-dev:** Bump prettier from 3.1.0 to 3.1.1 ([#318](https://github.com/wxt-dev/wxt/pull/318))
+- **deps-dev:** Bump vitepress from 1.0.0-rc.31 to 1.0.0-rc.34 ([#316](https://github.com/wxt-dev/wxt/pull/316))
+- Refactor manifest generation E2E tests to unit tests ([#323](https://github.com/wxt-dev/wxt/pull/323))
+
+## v0.13.2
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.13.1...v0.13.2)
+
+### 🚀 Enhancements
+
+- Add `isolateEvents` option to `createContentScripUi` ([#313](https://github.com/wxt-dev/wxt/pull/313))
+
+### 📖 Documentation
+
+- Remove duplicate `entrypoints/` path ([76e63e2](https://github.com/wxt-dev/wxt/commit/76e63e2))
+- Update unlisted pages/scripts description ([c99a281](https://github.com/wxt-dev/wxt/commit/c99a281))
+- Update content script entrypoint docs ([1360eb7](https://github.com/wxt-dev/wxt/commit/1360eb7))
+- Add example for setting up custom panels/panes in devtools ([#308](https://github.com/wxt-dev/wxt/pull/308))
+- Use example tags to automate relevant example lists ([#311](https://github.com/wxt-dev/wxt/pull/311))
+
+### 🏡 Chore
+
+- Update templates to `^0.13.0` ([#309](https://github.com/wxt-dev/wxt/pull/309))
+- Upgrade template dependencies ([#310](https://github.com/wxt-dev/wxt/pull/310))
+- Re-enable coverage ([#312](https://github.com/wxt-dev/wxt/pull/312))
+
+### ❤️ Contributors
+
+- 冯不游
+
+## v0.13.1
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.13.0...v0.13.1)
+
+### 🩹 Fixes
+
+- **storage:** Support multiple `:` characters in storage keys ([#303](https://github.com/wxt-dev/wxt/pull/303))
+- Ship `vite/client` types internally for proper resolution using PNPM ([#304](https://github.com/wxt-dev/wxt/pull/304))
+
+### 📖 Documentation
+
+- Reorder guide ([6421ab3](https://github.com/wxt-dev/wxt/commit/6421ab3))
+- General fixes and improvements ([2ad099b](https://github.com/wxt-dev/wxt/commit/2ad099b))
+
+### 🏡 Chore
+
+- Update `scripts/build.ts` show current build step in progress, not completed count ([#306](https://github.com/wxt-dev/wxt/pull/306))
+
+## v0.13.0
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.12.5...v0.13.0)
+
+### 🚀 Enhancements
+
+- ⚠️  New `wxt/storage` APIs ([#300](https://github.com/wxt-dev/wxt/pull/300))
+
+#### ⚠️ Breaking Changes
+
+- `wxt/storage` no longer relies on [`unstorage`](https://www.npmjs.com/package/unstorage). Some `unstorage` APIs, like `prefixStorage`, have been removed, while others, like `snapshot`, are methods on the new `storage` object. Most of the standard usage remains the same. See https://wxt.dev/guide/storage and https://wxt.dev/api/wxt/storage/ for more details ([#300](https://github.com/wxt-dev/wxt/pull/300))
+
+## v0.12.5
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.12.4...v0.12.5)
+
+### 🩹 Fixes
+
+- Correct import in dev-only, noop background ([#298](https://github.com/wxt-dev/wxt/pull/298))
+
+## v0.12.4
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.12.3...v0.12.4)
+
+### 🩹 Fixes
+
+- Disable Vite CJS warnings ([#296](https://github.com/wxt-dev/wxt/pull/296))
+
+## v0.12.3
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.12.2...v0.12.3)
+
+### 🩹 Fixes
+
+- Correctly mock `webextension-polyfill` for Vitest ([#294](https://github.com/wxt-dev/wxt/pull/294))
+
 ## v0.12.2
 
 [compare changes](https://github.com/wxt-dev/wxt/compare/v0.12.1...v0.12.2)

README.md

@@ -9,9 +9,8 @@
   <a href="https://www.npmjs.com/package/wxt" target="_blank"><img alt="npm" src="https://img.shields.io/npm/dm/wxt?labelColor=black&color=%234fa048"></a>
   <span> </span>
   <a href="https://github.com/wxt-dev/wxt/blob/main/LICENSE" target="_blank"><img alt="NPM" src="https://img.shields.io/npm/l/wxt?labelColor=black&color=%234fa048"></a>
-  <!-- Hide code coverage while it's broken -->
-  <!-- <span> </span>
-  <a href="https://codecov.io/github/wxt-dev/wxt" target="_blank"><img alt="Codecov" src="https://img.shields.io/codecov/c/github/wxt-dev/wxt?labelColor=black&color=%234fa048"></a> -->
+  <span> </span>
+  <a href="https://codecov.io/github/wxt-dev/wxt" target="_blank"><img alt="Codecov" src="https://img.shields.io/codecov/c/github/wxt-dev/wxt?labelColor=black&color=%234fa048"></a>
 </p>
 
 <p align="center">

demo/package.json

@@ -19,13 +19,11 @@
   "dependencies": {
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
-    "vitest": "^0.34.6",
-    "webextension-polyfill": "^0.10.0"
+    "vitest": "^1.1.0"
   },
   "devDependencies": {
     "@types/react": "^18.2.34",
     "@types/react-dom": "^18.2.14",
-    "@types/webextension-polyfill": "^0.10.5",
     "sass": "^1.69.5",
     "wxt": "workspace:*"
   }

demo/src/entrypoints/__tests__/background.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it, vi } from 'vitest';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
 import background from '../background';
 
 browser.i18n.getMessage = () => 'fake-message';
@@ -7,6 +7,10 @@ const logMock = vi.fn();
 console.log = logMock;
 
 describe('Background Entrypoint', () => {
+  beforeEach(() => {
+    fakeBrowser.reset();
+  });
+
   it("should log the extenion's runtime ID", () => {
     const id = 'some-id';
     fakeBrowser.runtime.id = id;
@@ -15,4 +19,11 @@ describe('Background Entrypoint', () => {
 
     expect(logMock).toBeCalledWith(id);
   });
+
+  it('should set the start time in storage', async () => {
+    background.main();
+    await new Promise((res) => setTimeout(res));
+
+    expect(await storage.getItem('session:startTime')).toBeDefined();
+  });
 });

docs/.vitepress/components/ExampleList.vue

@@ -0,0 +1,34 @@
+<script lang="ts" setup>
+import { ref, onMounted, computed } from 'vue';
+
+const props = defineProps<{
+  tag?: string;
+}>();
+
+const examples = ref();
+onMounted(async () => {
+  const res = await fetch(
+    'https://raw.githubusercontent.com/wxt-dev/wxt-examples/main/examples.json',
+  );
+  examples.value = await res.json();
+});
+
+const filteredExamples = computed(() => {
+  if (props.tag == null) return examples.value;
+
+  return examples.value.filter((example) => {
+    return example.tags?.includes(props.tag);
+  });
+});
+</script>
+
+<template>
+  <ul>
+    <li v-if="examples == null">Loading...</li>
+    <template v-else>
+      <li v-for="example of filteredExamples">
+        <a :href="example.url" target="_blank">{{ example.name }}</a>
+      </li>
+    </template>
+  </ul>
+</template>

docs/.vitepress/components/UsingWxtSection.vue

@@ -5,6 +5,10 @@ import useListExtensionDetails, {
 } 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
 const chromeExtensionIds = [
   'ocfdgncpifmegplaglcnglhioflaimkd', // GitHub: Better Line Counts
   'mgmdkjcljneegjfajchedjpdhbadklcf', // Anime Skip Player
@@ -12,6 +16,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中文配音
 ];
 
 const { data } = useListExtensionDetails(chromeExtensionIds);
@@ -24,6 +29,7 @@ const sortedExtensions = computed(() => {
       // Sort based on the user count weighted by the rating
       sortKey: ((item.rating ?? 5) / 5) * item.weeklyActiveUsers,
     }))
+    .filter((item) => !!item)
     .sort((l, r) => r.sortKey - l.sortKey);
 });
 

docs/.vitepress/config.ts

@@ -84,18 +84,18 @@ export default defineConfig({
             { text: 'Installation', link: '/guide/installation.md' },
             { text: 'Configuration', link: '/guide/configuration.md' },
             { text: 'Entrypoints', link: '/guide/entrypoints.md' },
-            { text: 'Assets', link: '/guide/assets.md' },
-            { text: 'Multiple Browsers', link: '/guide/multiple-browsers.md' },
-            { text: 'Publishing', link: '/guide/publishing.md' },
-            { text: 'Auto-imports', link: '/guide/auto-imports.md' },
             { text: 'Manifest.json', link: '/guide/manifest.md' },
             { text: 'Extension APIs', link: '/guide/extension-apis.md' },
             { text: 'Storage', link: '/guide/storage.md' },
+            { text: 'Assets', link: '/guide/assets.md' },
             { text: 'Content Script UI', link: '/guide/content-script-ui.md' },
+            { text: 'Multiple Browsers', link: '/guide/multiple-browsers.md' },
+            { text: 'Auto-imports', link: '/guide/auto-imports.md' },
+            { text: 'Vite', link: '/guide/vite.md' },
             { text: 'Remote Code', link: '/guide/remote-code.md' },
+            { text: 'Publishing', link: '/guide/publishing.md' },
             { text: 'Development', link: '/guide/development.md' },
             { text: 'Testing', link: '/guide/testing.md' },
-            { text: 'Vite', link: '/guide/vite.md' },
           ],
         },
         {

docs/.vitepress/theme/index.ts

@@ -2,6 +2,7 @@ import DefaultTheme from 'vitepress/theme';
 import Icon from '../components/Icon.vue';
 import EntrypointPatterns from '../components/EntrypointPatterns.vue';
 import UsingWxtSection from '../components/UsingWxtSection.vue';
+import ExampleList from '../components/ExampleList.vue';
 import './custom.css';
 
 export default {
@@ -10,5 +11,6 @@ export default {
     ctx.app.component('Icon', Icon);
     ctx.app.component('EntrypointPatterns', EntrypointPatterns);
     ctx.app.component('UsingWxtSection', UsingWxtSection);
+    ctx.app.component('ExampleList', ExampleList);
   },
 };

docs/entrypoints/content-scripts.md

@@ -20,7 +20,7 @@ When creating content script entrypoints, they are automatically included in the
 ```ts
 export default defineContentScript({
   // Set manifest options
-  matches: ['*://google.com/*', '*://duckduckgo.com/*'],
+  matches: string[],
   excludeMatches: undefined | [],
   includeGlobs: undefined | [],
   excludeGlobs: undefined | [],
@@ -90,7 +90,7 @@ To include CSS with your content script, import the CSS file at the top of your
 
 ```
 
-<srcDir>
+<srcDir>/
 └─ entrypoints/
    └─ overlay.content/
       ├─ index.ts
@@ -137,3 +137,5 @@ export default defineContentScript({
   },
 });
 ```
+
+See [Content Script UI](/guide/content-script-ui) for more info on creating UIs and including CSS in content scripts.

docs/entrypoints/devtools.md

@@ -13,15 +13,12 @@
 
 ## Definition
 
-Plain old HTML file.
-
 ```html
 <!doctype html>
 <html lang="en">
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Title</title>
     <!-- Set include/exclude if the page should be removed from some builds -->
     <meta name="manifest.include" content="['chrome', ...]" />
     <meta name="manifest.exclude" content="['chrome', ...]" />
@@ -31,3 +28,13 @@ Plain old HTML file.
   </body>
 </html>
 ```
+
+## Adding UI Elements
+
+Chrome extensions allow you to add panels and side panes to the devtools window.
+
+![DevTools window showing Elements panel and Styles sidebar pane.](https://developer.chrome.com/static/docs/extensions/how-to/devtools/extend-devtools/image/devtools-window-showing-e-9051f7f0347cd_1920.png)
+
+See the WXT's examples for a full walkthrough of extending the devtools window:
+
+<ExampleList tag="devtools" />

docs/entrypoints/sandbox.md

@@ -10,10 +10,10 @@ Firefox does not support sandboxed pages.
 
 <EntrypointPatterns
   :patterns="[
-    ['entrypoints/sandbox.html', 'sandbox.html'],
-    ['entrypoints/sandbox/index.html', 'sandbox.html'],
-    ['entrypoints/<name>.sandbox.html', '<name>.html` '],
-    ['entrypoints/<name>.sandbox/index.html', '<name>.html` '],
+    ['sandbox.html', 'sandbox.html'],
+    ['sandbox/index.html', 'sandbox.html'],
+    ['<name>.sandbox.html', '<name>.html` '],
+    ['<name>.sandbox/index.html', '<name>.html` '],
   ]"
 />
 

docs/entrypoints/sidepanel.md

@@ -10,10 +10,10 @@ Chrome added support for sidepanels in Manifest V3, they are not available in Ma
 
 <EntrypointPatterns
   :patterns="[
-    ['entrypoints/sidepanel.html', 'sidepanel.html'],
-    ['entrypoints/sidepanel/index.html', 'sidepanel.html'],
-    ['entrypoints/<name>.sidepanel.html', '<name>.html` '],
-    ['entrypoints/<name>.sidepanel/index.html', '<name>.html` '],
+    ['sidepanel.html', 'sidepanel.html'],
+    ['sidepanel/index.html', 'sidepanel.html'],
+    ['<name>.sidepanel.html', '<name>.html` '],
+    ['<name>.sidepanel/index.html', '<name>.html` '],
   ]"
 />
 

docs/entrypoints/unlisted-pages.md

@@ -1,6 +1,6 @@
 # Unlisted Pages
 
-HTML pages that are built by Vite, but are not included in the manifest.
+HTML pages that are bundled and shipped with the extension, but are not included in the manifest.
 
 ### Examples
 

docs/entrypoints/unlisted-scripts.md

@@ -1,6 +1,6 @@
 # Unlisted Scripts
 
-TypeScript files that are built, but are not included in the manifest.
+TypeScript files that are bundled and shipped with the extension, but are not included in the manifest.
 
 You are responsible for loading/running these scripts where needed.
 

docs/examples.md

@@ -2,26 +2,6 @@
 
 Simple walkthroughs to accomplish common tasks or patterns with WXT.
 
-<script lang="ts" setup>
-import { ref, onMounted } from 'vue';
-
-const examples = ref()
-onMounted(async () => {
-    const res = await fetch("https://raw.githubusercontent.com/wxt-dev/wxt-examples/main/examples.json");
-    examples.value = await res.json();
-})
-
-</script>
-
-<ul>
-    <li v-if="examples == null">
-        Loading...
-    </li>
-    <template v-else>
-        <li v-for="example of examples">
-        <a :href="example.url" target="_blank">{{ example.name }}</a>
-        </li>
-    </template>
-</ul>
+<ExampleList />
 
 > Full code available at [`wxt-dev/wxt-examples`](https://github.com/wxt-dev/wxt-examples)

docs/guide/configuration.md

@@ -51,12 +51,6 @@ export default defineConfig({
 });
 ```
 
-## Vite Config
-
-[Vite](https://vitejs.dev/) is the bundler used to build each entrypoint of your extension. Vite can be configured via the `vite` option.
-
-See [Vite's documentation](https://vitejs.dev/config/) for configuring the bundler.
-
 ## Frontend Frameworks
 
 Adding a framework like Vue, React, or Svelte is easy!
@@ -70,9 +64,9 @@ import { defineConfig } from 'wxt';
 import vue from '@vitejs/plugin-vue';
 
 export default defineConfig({
-  vite: {
+  vite: () => ({
     plugins: [vue()],
-  },
+  }),
 });
 ```
 
@@ -81,9 +75,9 @@ import { defineConfig } from 'wxt';
 import react from '@vitejs/plugin-react';
 
 export default defineConfig({
-  vite: {
+  vite: () => ({
     plugins: [react()],
-  },
+  }),
 });
 ```
 
@@ -92,10 +86,14 @@ import { defineConfig } from 'wxt';
 import { svelte } from '@sveltejs/vite-plugin-svelte';
 
 export default defineConfig({
-  vite: {
+  vite: () => ({
     plugins: [svelte()],
-  },
+  }),
 });
 ```
 
 :::
+
+:::info
+Internally, WXT runs `vite build` multiple times during a single build. It can't share the same instance of some plugins between each build, so a function is used to return completely new instances of each plugin for each build.
+:::

docs/guide/content-script-ui.md

@@ -6,11 +6,11 @@ There are three ways to mount a UI inside a content script:
 
 Each has their own set of advantages and disadvantages.
 
-| Method     | Isolated Styles | HMR | Use page's context |
-| ---------- | :-------------: | :-: | :----------------: |
-| Integrated |       ❌        | ❌  |         ✅         |
-| ShadowRoot |       ✅        | ❌  |         ✅         |
-| IFrame     |       ✅        | ✅  |         ❌         |
+| Method     | Isolated Styles |   Isolated Events   | HMR | Use page's context |
+| ---------- | :-------------: | :-----------------: | :-: | :----------------: |
+| Integrated |       ❌        |         ❌          | ❌  |         ✅         |
+| ShadowRoot |       ✅        | ✅ (off by default) | ❌  |         ✅         |
+| IFrame     |       ✅        |         ✅          | ✅  |         ❌         |
 
 ## Integrated
 
@@ -149,7 +149,7 @@ export default defineContentScript({
 
 Often in web extensions, you don't want your content script's CSS affecting the page, or vise-versa. The [`ShadowRoot`](https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot) API is ideal for this.
 
-WXT provides a helper function, [`createContentScriptUi`](/api/wxt/client/functions/createContentScriptUi), that abstracts all the `ShadowRoot` setup away, making it easy to create UIs with isolated CSS.
+WXT provides a helper function, [`createContentScriptUi`](/api/wxt/client/functions/createContentScriptUi), that abstracts all the `ShadowRoot` setup away, making it easy to create UIs with isolated CSS. It also supports an optional `isolateEvents` parameter to further isolate user interactions.
 
 To use `createContentScriptUi`, follow these steps:
 

docs/guide/development.md

@@ -57,3 +57,13 @@ export default defineRunnerConfig({
 :::tip
 When configuring browser binaries, it's helpful to put them in `~/web-ext.config.ts` instead of the project directory's `web-ext.config.ts` file. When placed in your home directory (`~/`), this config will be used by all WXT projects, so you only need to configure the binaries once.
 :::
+
+## Reload the Extension
+
+Normally, to manually reload an extension, you have to visit `chrome://extensions` and click the reload button for your extension.
+
+When running `wxt` command to start the dev server, WXT adds a keyboard shortcut, `ctrl+E` for Windows/Linux and `cmd+E` for Mac, that reloads the extension when pressed, without visiting `chrome://extensions`.
+
+:::note
+This shortcut is only available during development, and is not be added to your extension when running `wxt build` or `wxt-zip`.
+:::

docs/guide/manifest.md

@@ -1,12 +1,13 @@
 # Manifest.json
 
-The manifest.json is generated at build-time based on files in your `entrypoints` directory and your `wxt.config.ts`.
+The manifest.json is generated at build-time based on files in the `entrypoints/` directory and `wxt.config.ts`.
 
 ## Configuration
 
 While entrypoints are generated and added to the manifest at build-time, you can customize or add to your `manifest.json` in the config file.
 
 ```ts
+// wxt.config.tsentrypoint of your extension
 import { defineConfig } from 'wxt';
 
 export default defineConfig({
@@ -25,11 +26,13 @@ If not provided via the `manifest` config, the [manifest's `name`](https://devel
 
 ## `version` and `version_name`
 
-The [manifest's `version` and `version_name`](https://developer.chrome.com/docs/extensions/mv3/manifest/version/) fields are based on your package.json's `version` property.
+The [manifest's `version` and `version_name`](https://developer.chrome.com/docs/extensions/mv3/manifest/version/) properties are based on the `version` field listed in your `package.json` or `wxt.config.ts`.
 
-- `version_name` is the exact string listed in your package.json
+- `version_name` is the exact string listed in your `package.json` or `wxt.config.ts` file
 - `version` is the string cleaned up, with any invalid suffixes removed
 
+If a version is not found, a warning is logged and the version defaults to `"0.0.0"`.
+
 ### Example
 
 ```json
@@ -118,3 +121,7 @@ export default defineConfig({
   },
 });
 ```
+
+See the official localization examples for more details:
+
+<ExampleList tag="i18n" />

docs/guide/publishing.md

@@ -4,7 +4,7 @@ WXT offers several utilities that simplify the publishing process.
 
 ## First Time Publishing
 
-If you're publishing an extension to a store for the first time, it's recommended that you manually navigate the process. Each store has unique steps and requirements that you need to familiarize yourself with.
+If you're publishing an extension to a store for the first time, you must manually navigate the process. Each store has unique steps and requirements that you need to familiarize yourself with.
 
 Each store requires that a ZIP file be uploaded. You can generate these using the `wxt zip` command:
 

docs/guide/storage.md

@@ -1,36 +1,254 @@
 # Storage API
 
-WXT's storage API is powered by `unstorage`. See [their docs](https://unstorage.unjs.io/usage#usage-1) for more details.
-
-## Overview
-
-:::code-group
-
-```ts [native]
-const { installDate } = await browser.storage.local.get('installDate');
-await browser.storage.local.set({ key: 'value' });
-```
-
-```ts [wxt/browser]
-const installDate = await storage.get('local:installDate');
-await storage.setItem('key', 'value');
-```
-
-:::
-
-Use the `"local:"`, `"session:"`, `"sync:"`, and `"managed:"` prefixes to specify which storage area to use.
-
-## Customization
-
-WXT also provides a driver for `unstorage`. To customize the `storage` object's setup, like removing the prefixes and using a single storage area, you can create your own storage:
+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:
 
 ```ts
-// storage.ts
-export default createStorage({
-  driver: webExtensionDriver({ storageArea: 'local' }),
+import { storage } from 'wxt/storage';
+```
+
+[[toc]]
+
+## Basic Usage
+
+All storage keys must be prefixed by their storage area.
+
+```ts
+// ❌ This will throw an error
+await storage.getItem('installDate');
+
+// ✅ This is good
+await storage.getItem('local:installDate');
+```
+
+You can use `local:`, `session:`, `sync:`, or `managed:`.
+
+If you use TypeScript, you can add a type parameter to most methods to specify the expected type of the key's value:
+
+```ts
+await storage.getItem<number>('local:installDate');
+await storage.watch<number>(
+  'local:installDate',
+  (newInstallDate, oldInstallDate) => {
+    // ...
+  },
+);
+await storage.getMeta<{ v: number }>('local:installDate');
+```
+
+## Watchers
+
+To listen for storage changes, use the `storage.watch` function. It lets you setup a listener for a single key:
+
+```ts
+const unwatch = storage.watch<number>('local:counter', (newCount, oldCount) => {
+  console.log('Count changed:', { newCount, oldCount });
 });
 ```
 
-:::note
-`wxt/browser` re-exports all of `unstorage`, which is where `createStorage` comes from.
+To remove the listener, call the returned `unwatch` function:
+
+```ts
+const unwatch = storage.watch(...);
+
+// Some time later...
+unwatch();
+```
+
+## Metadata
+
+`wxt/storage` also supports setting metadata for keys, stored at `key + "$"`. Metadata is a collection of properties associated with a key. It might be a version number, last modified date, etc.
+
+[Other than versioning](#versioning-and-migrations), you are responsible for managing a field's metadata:
+
+```ts
+await Promise.all([
+  storage.setItem('local:preference', true),
+  storage.setMeta('local:preference', { lastModified: Date.now() }),
+]);
+```
+
+When setting different properties of metadata from multiple calls, the properties are combined instead of overwritten:
+
+```ts
+await storage.setMeta('local:preference', { lastModified: Date.now() });
+await storage.setMeta('local:preference', { v: 2 });
+
+await storage.getMeta('local:preference'); // { v: 2, lastModified: 1703690746007 }
+```
+
+You can remove all metadata associated with a key, or just specific properties:
+
+```ts
+// Remove all properties
+await storage.removeMeta('local:preference');
+
+// Remove one property
+await storage.removeMeta('local:preference', 'lastModified');
+
+// Remove multiple properties
+await storage.removeMeta('local:preference', ['lastModified', 'v']);
+```
+
+## Defining Storage Items
+
+Writing the key and type parameter for the same key over and over again can be annoying. As an alternative, you can use `storage.defineItem` to create a "storage item".
+
+Storage items contain the same APIs as the `storage` variable, but you can configure its type, default value, and more in a single place:
+
+```ts
+// utils/storage.ts
+const showChangelogOnUpdate = storage.defineItem<boolean>(
+  'local:showChangelogOnUpdate',
+  {
+    defaultValue: true,
+  },
+);
+```
+
+Now, instead of using the `storage` variable, you can use the helper functions on the storage item you created:
+
+```ts
+await showChangelogOnUpdate.getValue();
+await showChangelogOnUpdate.setValue(false);
+await showChangelogOnUpdate.removeValue();
+const unwatch = showChangelogOnUpdate.watch(() => {
+  // ...
+});
+```
+
+### Versioning and Migrations
+
+You can add versioning to storage items if you expect them to grow or change over time. When defining the first version of an item, start with version 1.
+
+For example, consider a storage item that stores a list of websites that are ignored by an extension.
+
+:::code-group
+
+```ts [v1]
+type IgnoredWebsiteV1 = string;
+
+export const ignoredWebsites = storage.defineItem<IgnoredWebsiteV1[]>(
+  'local:ignoredWebsites',
+  {
+    defaultValue: [],
+    version: 1,
+  },
+);
+```
+
+<!-- prettier-ignore -->
+```ts [v2]
+import { nanoid } from 'nanoid'; // [!code ++]
+
+type IgnoredWebsiteV1 = string;
+interface IgnoredWebsiteV2 { // [!code ++]
+  id: string; // [!code ++]
+  website: string; // [!code ++]
+} // [!code ++]
+
+export const ignoredWebsites = storage.defineItem<IgnoredWebsiteV1[]>( // [!code --]
+export const ignoredWebsites = storage.defineItem<IgnoredWebsiteV2[]>( // [!code ++]
+  'local:ignoredWebsites',
+  {
+    defaultValue: [],
+    version: 1, // [!code --]
+    version: 2, // [!code ++]
+    migrations: { // [!code ++]
+      // Ran when migrating from v1 to v2 // [!code ++]
+      2: (websites: IgnoredWebsiteV1[]): IgnoredWebsiteV2[] => { // [!code ++]
+        return websites.map((website) => ({ id: nanoid(), website })); // [!code ++]
+      }, // [!code ++]
+    }, // [!code ++]
+  },
+);
+```
+
+<!-- prettier-ignore -->
+```ts [v3]
+import { nanoid } from 'nanoid';
+
+type IgnoredWebsiteV1 = string;
+interface IgnoredWebsiteV2 {
+  id: string;
+  website: string;
+}
+interface IgnoredWebsiteV3 { // [!code ++]
+  id: string; // [!code ++]
+  website: string; // [!code ++]
+  enabled: boolean; // [!code ++]
+} // [!code ++]
+
+export const ignoredWebsites = storage.defineItem<IgnoredWebsiteV2[]>( // [!code --]
+export const ignoredWebsites = storage.defineItem<IgnoredWebsiteV3[]>( // [!code ++]
+  'local:ignoredWebsites',
+  {
+    defaultValue: [],
+    version: 2, // [!code --]
+    version: 3, // [!code ++]
+    migrations: {
+      // Ran when migrating from v1 to v2
+      2: (websites: IgnoredWebsiteV1[]): IgnoredWebsiteV2[] => {
+        return websites.map((website) => ({ id: nanoid(), website }));
+      },
+      // Ran when migrating from v2 to v3 // [!code ++]
+      3: (websites: IgnoredWebsiteV2[]): IgnoredWebsiteV3[] => { // [!code ++]
+        return websites.map((website) => ({ ...website, enabled: true })); // [!code ++]
+      }, // [!code ++]
+    },
+  },
+);
+```
+
+:::
+
+:::info
+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.
+
+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.
+
+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:
+
+:::code-group
+
+```ts [Unversioned]
+export const ignoredWebsites = storage.defineItem<string[]>(
+  'local:ignoredWebsites',
+  {
+    defaultValue: [],
+  },
+);
+```
+
+<!-- prettier-ignore -->
+```ts [v2]
+import { nanoid } from 'nanoid'; // [!code ++]
+
+// Retroactively add a type for the first version // [!code ++]
+type IgnoredWebsiteV1 = string; // [!code ++]
+interface IgnoredWebsiteV2 { // [!code ++]
+  id: string; // [!code ++]
+  website: string; // [!code ++]
+} // [!code ++]
+
+export const ignoredWebsites = storage.defineItem<string[]>( // [!code --]
+export const ignoredWebsites = storage.defineItem<IgnoredWebsiteV2[]>( // [!code ++]
+  'local:ignoredWebsites',
+  {
+    defaultValue: [],
+    version: 2, // [!code ++]
+    migrations: { // [!code ++]
+      // Ran when migrating from v1 to v2 // [!code ++]
+      2: (websites: IgnoredWebsiteV1[]): IgnoredWebsiteV2[] => { // [!code ++]
+        return websites.map((website) => ({ id: nanoid(), website })); // [!code ++]
+      }, // [!code ++]
+    }, // [!code ++]
+  },
+);
+```
+
 :::

docs/guide/testing.md

@@ -1,162 +1,25 @@
 # Testing
 
-WXT provides several utils for writing tests.
+## Official Frameworks
 
-## Unit tests
+WXT officially supports [Vitest](https://vitest.dev/) for unit tests and either [Playwright](https://playwright.dev/) or [Puppeteer](https://pptr.dev/) for E2E tests against Chromium browsers.
 
-If you're using auto-imports (enabled by default), [Vitest](https://vitest.dev/) is the only testing framework that supports them.
+For details setting up each testing framework, see the official examples:
 
-If you want to use a different testing library/framework (like Jest, mocha, node:test, etc), you can keep using it, but you have two options:
+<ExampleList tag="testing" />
 
-1. Switch to Vitest (recommended)
-2. Configure the testing library manually
-   - Disable auto-imports by setting `imports: false` in your `wxt.config.ts` file
-   - Manually add globals normally provided by WXT (like `__BROWSER__`) that you consume to the global scope before accessing them (`globalThis.__BROWSER__ = "chrome"`)
+### Unofficial Frameworks
 
-### Vitest Setup
+Puppeteer and Playwright are the only E2E test runners that support Chrome Extensions. There are no other options at the time of writing.
 
-Install vitest and add the `WxtVitest` plugin to your `vitest.config.ts` file.
+There are other options for unit tests however, like [Jest](https://jestjs.io/), [Mocha](https://mochajs.org/), or [`node:test`](https://nodejs.org/api/test.html). **_WXT does not claim to support any of them_** because none of them support all of WXT's features, like TypeScript or auto-imports.
 
-```sh
-pnpm i -D vitest
-```
+If you want to try to use a different framework for unit tests, you will need to configure the environment manually:
 
-```ts
-// <root>/vitest.config.ts
-import { defineConfig } from 'vitest/config';
-import { WxtVitest } from 'wxt/testing';
+- **Auto-imports**: Add `unimport` to your test environment or disable them by setting `imports: false` in your `wxt.config.ts` file
+- **`browser` mock**: Mock the `webextension-polyfill` module globally with `wxt/dist/virtual/mock-browser.js`
+- **[Remote Code Bundling](/guide/remote-code)**: If you use it, configure your environment to handle the `url:` module prefix
+- **Global Variables**: If you consume them, manually define globals provided by WXT (like `__BROWSER__`) by adding them to the global scope before accessing them (`globalThis.__BROWSER__ = "chrome"`)
+- **Import paths**: If you use the `@/` or `~/` path aliases, add them to your test environment
 
-export default defineConfig({
-  plugins: [WxtVitest()],
-  test: {
-    server: {
-      deps: {
-        // Add any dependencies that import webextension-polyfill here, otherwise tests will attempt to import the real polyfill, breaking the
-        // TODO: Auto-detect these dependencies inside `WxtVitest` so maintaining this list manually isn't necessary
-        inline: [...],
-      },
-    },
-  },
-});
-```
-
-And that's it. You're ready to start writing tests.
-
-### Writing Tests
-
-Here's a very basic test, written with a few different testing libraries, with a few different approaches for mocking the `browser` global.
-
-:::code-group
-
-```ts [Vitest]
-import { describe, it, expect, vi } from 'vitest';
-
-function logRuntimeId() {
-  // Vitest automatically mocks "browser" with "fakeBrowser"
-  console.log(browser.runtime.id);
-}
-
-describe('logRuntimeId', () => {
-  it("should log the extension's runtime ID", () => {
-    // Set a known ID on fakeBrowser for the test
-    const id = 'some-runtime-id';
-    fakeBrowser.runtime.id = id;
-    const logSpy = vi.spyOn(console, 'log');
-
-    logRuntimeId();
-
-    expect(logSpy).toBeCalledWith(id);
-  });
-});
-```
-
-```ts [Jest - Manual Mock]
-import { fakeBrowser } from 'wxt/testing';
-import { browser } from 'wxt/browser';
-
-function logRuntimeId() {
-  console.log(browser.runtime.id);
-}
-
-// Manually mock
-jest.mock('wxt/browser', () => {
-  const { fakeBrowser } = require('wxt/testing');
-  return { browser: fakeBrowser };
-});
-
-describe('logRuntimeId', () => {
-  it("should log the extension's runtime ID", () => {
-    // Set a known ID on fakeBrowser for the test
-    const id = 'some-runtime-id';
-    fakeBrowser.runtime.id = id;
-    const logSpy = jest.spyOn(console, 'log');
-
-    logRuntimeId();
-
-    expect(logSpy).toBeCalledWith(id);
-  });
-});
-```
-
-```ts [node:test - Parameterized]
-import { describe, it, mock } from 'node:test';
-import { assert } from 'node:assert';
-import { fakeBrowser } from 'wxt/testing';
-import { browser } from 'wxt/browser';
-
-// Add browser as a parameter so fakeBrowser can be passed instead of browser
-function logRuntimeId(browser = browser) {
-  console.log(browser.runtime.id);
-}
-
-describe('logRuntimeId', () => {
-  it("should log the extension's runtime ID", () => {
-    // Set a known ID on fakeBrowser for the test
-    const id = 'some-runtime-id';
-    fakeBrowser.runtime.id = id;
-    console.log = mock.fn();
-
-    // pass in fakeBrowser during tests
-    logRuntimeId(fakeBrowser);
-
-    assert.deepStrictEqual(console.log.mock.calls[0].arguments, [id]);
-  });
-});
-```
-
-:::
-
-:::warning
-Without mocking the `browser` variable, you'll see errors like this:
-
-```
-This script should only be loaded in a browser extension.
-```
-
-:::
-
-WXT provides an in-memory, partial implementation of `browser`, [`fakeBrowser`](/api/wxt/testing/variables/fakeBrowser), from the [`@webext-core/fake-browser`](https://webext-core.aklinker1.io/guide/fake-browser/) package. `fakeBrowser` works with all testing frameworks/libraries. See their docs for a list of [implemented APIs](https://webext-core.aklinker1.io/guide/fake-browser/implemented-apis.html) and more example tests.
-
-## E2E Tests
-
-WXT does not provide any utils for running E2E tests. There are two libraries you can use to run E2E tests for any chrome extension.
-
-- [`playwright`](https://playwright.dev/docs/chrome-extensions) (recommended) - "A high-level API to automate web browsers"
-- [`puppeteer`](https://pptr.dev/guides/chrome-extensions) - "A high-level API to control headless Chrome over the DevTools Protocol"
-
-:::info
-Note that both only support running tests on Chrome.
-:::
-
-Before running tests with either of these tools, you must build the extension with `wxt build` and then load the extension from the output directory in a new tab.
-
-To test an extension's UI, like the popup or options page, you'll need to know the extension's ID to open the URL directly.
-
-> _chrome-extension://`browser.runtime.id`/popup.html_
-
-- Playwright provides an API to get your extension ID after it has been installed. [See their docs](https://playwright.dev/docs/chrome-extensions#testing).
-- Puppeteer requires you know the ID before installing the extension, so you can hard code it into the URLs you open. Follow [Chrome's guide](https://developer.chrome.com/docs/extensions/mv3/manifest/key/) to setup a consistent runtime id.
-
-:::info
-You cannot test popups in their normal popup window, you have to open them in a tab.
-:::
+[Here's how Vitest is configured](https://github.com/wxt-dev/wxt/blob/main/src/testing/wxt-vitest-plugin.ts) for reference.

e2e/tests/auto-imports.test.ts

@@ -20,24 +20,14 @@ describe('Auto Imports', () => {
             const InvalidMatchPattern: typeof import('wxt/sandbox')['InvalidMatchPattern']
             const MatchPattern: typeof import('wxt/sandbox')['MatchPattern']
             const browser: typeof import('wxt/browser')['browser']
-            const builtinDrivers: typeof import('wxt/storage')['builtinDrivers']
             const createContentScriptIframe: typeof import('wxt/client')['createContentScriptIframe']
             const createContentScriptUi: typeof import('wxt/client')['createContentScriptUi']
-            const createStorage: typeof import('wxt/storage')['createStorage']
             const defineBackground: typeof import('wxt/sandbox')['defineBackground']
             const defineConfig: typeof import('wxt')['defineConfig']
             const defineContentScript: typeof import('wxt/sandbox')['defineContentScript']
-            const defineDriver: typeof import('wxt/storage')['defineDriver']
             const defineUnlistedScript: typeof import('wxt/sandbox')['defineUnlistedScript']
             const fakeBrowser: typeof import('wxt/testing')['fakeBrowser']
-            const joinKeys: typeof import('wxt/storage')['joinKeys']
-            const normalizeBaseKey: typeof import('wxt/storage')['normalizeBaseKey']
-            const normalizeKey: typeof import('wxt/storage')['normalizeKey']
-            const prefixStorage: typeof import('wxt/storage')['prefixStorage']
-            const restoreSnapshot: typeof import('wxt/storage')['restoreSnapshot']
-            const snapshot: typeof import('wxt/storage')['snapshot']
             const storage: typeof import('wxt/storage')['storage']
-            const webExtensionDriver: typeof import('wxt/storage')['webExtensionDriver']
           }
           "
         `);
@@ -54,7 +44,7 @@ describe('Auto Imports', () => {
           ".wxt/wxt.d.ts
           ----------------------------------------
           // Generated by wxt
-          /// <reference types="vite/client" />
+          /// <reference types="wxt/vite-builder-env" />
           /// <reference types="./types/imports.d.ts" />
           /// <reference types="./types/paths.d.ts" />
           /// <reference types="./types/i18n.d.ts" />
@@ -93,7 +83,7 @@ describe('Auto Imports', () => {
         ".wxt/wxt.d.ts
         ----------------------------------------
         // Generated by wxt
-        /// <reference types="vite/client" />
+        /// <reference types="wxt/vite-builder-env" />
         /// <reference types="./types/paths.d.ts" />
         /// <reference types="./types/i18n.d.ts" />
         /// <reference types="./types/globals.d.ts" />

e2e/tests/manifest-content.test.ts

@@ -1,556 +1,7 @@
 import { describe, it, expect } from 'vitest';
 import { TestProject } from '../utils';
 
-// TODO: move to unit tests to speed this up - this doesn't have to be in E2E tests
-
 describe('Manifest Content', () => {
-  describe('popup', () => {
-    const popupContent = (type?: 'browser_action' | 'page_action') => `
-      <html>
-        <head>
-          ${type == null ? '' : `<meta name="manifest.type" content="${type}">`}
-          <meta name="manifest.default_icon" content="{ '16': '/icon/16.png' }">
-          <title>Default Title</title>
-        </head>
-      </html>
-    `;
-
-    it('should include an action for mv3', async () => {
-      const project = new TestProject();
-      project.addFile('entrypoints/popup.html', popupContent());
-
-      await project.build();
-
-      const manifest = await project.getOutputManifest();
-      expect(manifest.action).toEqual({
-        default_icon: { '16': '/icon/16.png' },
-        default_title: 'Default Title',
-        default_popup: 'popup.html',
-      });
-    });
-
-    it.each([
-      [undefined, 'browser_action'],
-      ['browser_action', 'browser_action'],
-      ['page_action', 'page_action'],
-    ] as const)(
-      'should include a browser_action for mv2',
-      async (type, expectedType) => {
-        const project = new TestProject();
-        project.addFile('entrypoints/popup.html', popupContent(type));
-
-        await project.build({ manifestVersion: 2 });
-
-        const manifest = await project.getOutputManifest(
-          '.output/chrome-mv2/manifest.json',
-        );
-        expect(manifest[expectedType]).toEqual({
-          default_icon: { '16': '/icon/16.png' },
-          default_title: 'Default Title',
-          default_popup: 'popup.html',
-        });
-      },
-    );
-  });
-
-  describe('options', () => {
-    const optionsContent = `
-      <html>
-        <head>
-          <meta name="manifest.open_in_tab" content="false">
-          <meta name="manifest.chrome_style" content="true">
-          <meta name="manifest.browser_style" content="true">
-        </head>
-      </html>
-    `;
-
-    it('should include a options_ui and chrome_style for chrome', async () => {
-      const project = new TestProject();
-      project.addFile('entrypoints/options.html', optionsContent);
-
-      await project.build();
-      const manifest = await project.getOutputManifest();
-
-      expect(manifest.options_ui).toEqual({
-        open_in_tab: false,
-        chrome_style: true,
-        page: 'options.html',
-      });
-    });
-
-    it('should include a options_ui and browser_style for firefox', async () => {
-      const project = new TestProject();
-      project.addFile('entrypoints/options.html', optionsContent);
-
-      await project.build({ browser: 'firefox' });
-      const manifest = await project.getOutputManifest(
-        '.output/firefox-mv2/manifest.json',
-      );
-
-      expect(manifest.options_ui).toEqual({
-        open_in_tab: false,
-        browser_style: true,
-        page: 'options.html',
-      });
-    });
-  });
-
-  describe('background', () => {
-    const backgroundContent = `
-      export default defineBackground({
-        persistent: true,
-        type: "module",
-        main: () => {},
-      })
-    `;
-
-    it.each(['chrome', 'safari'])(
-      'should include scripts and persistent for %s mv2',
-      async (browser) => {
-        const project = new TestProject();
-        project.addFile('entrypoints/background.ts', backgroundContent);
-
-        await project.build({ browser, manifestVersion: 2 });
-        const manifest = await project.getOutputManifest(
-          `.output/${browser}-mv2/manifest.json`,
-        );
-
-        expect(manifest.background).toEqual({
-          persistent: true,
-          scripts: ['background.js'],
-        });
-      },
-    );
-
-    it.each(['chrome', 'safari'])(
-      'should include a service worker and type for %s mv3',
-      async (browser) => {
-        const project = new TestProject();
-        project.addFile('entrypoints/background.ts', backgroundContent);
-
-        await project.build({ browser, manifestVersion: 3 });
-        const manifest = await project.getOutputManifest(
-          `.output/${browser}-mv3/manifest.json`,
-        );
-
-        expect(manifest.background).toEqual({
-          type: 'module',
-          service_worker: 'background.js',
-        });
-      },
-    );
-
-    it('should include a background script and type for firefox mv3', async () => {
-      const project = new TestProject();
-      project.addFile('entrypoints/background.ts', backgroundContent);
-
-      await project.build({ browser: 'firefox', manifestVersion: 3 });
-      const manifest = await project.getOutputManifest(
-        '.output/firefox-mv3/manifest.json',
-      );
-
-      expect(manifest.background).toEqual({
-        type: 'module',
-        scripts: ['background.js'],
-      });
-    });
-
-    it('should include a background script and persistent for firefox mv2', async () => {
-      const project = new TestProject();
-      project.addFile('entrypoints/background.ts', backgroundContent);
-
-      await project.build({ browser: 'firefox', manifestVersion: 2 });
-      const manifest = await project.getOutputManifest(
-        '.output/firefox-mv2/manifest.json',
-      );
-
-      expect(manifest.background).toEqual({
-        persistent: true,
-        scripts: ['background.js'],
-      });
-    });
-  });
-
-  describe('icons', () => {
-    it('should auto-discover icons with the correct name', async () => {
-      const project = new TestProject();
-      project.addFile('entrypoints/unlisted.html');
-      project.addFile('public/icon-16.png');
-      project.addFile('public/icon/32.png');
-      project.addFile('public/icon@48w.png');
-      project.addFile('public/icon-64x64.png');
-      project.addFile('public/icon@96.png');
-      project.addFile('public/icons/128x128.png');
-
-      await project.build();
-      const manifest = await project.getOutputManifest();
-
-      expect(manifest.icons).toEqual({
-        '16': 'icon-16.png',
-        '32': 'icon/32.png',
-        '48': 'icon@48w.png',
-        '64': 'icon-64x64.png',
-        '96': 'icon@96.png',
-        '128': 'icons/128x128.png',
-      });
-    });
-
-    it('should return undefined when no icons are found', async () => {
-      const project = new TestProject();
-      project.addFile('entrypoints/unlisted.html');
-      project.addFile('public/logo.png');
-      project.addFile('public/icon.jpeg');
-
-      await project.build();
-      const manifest = await project.getOutputManifest();
-
-      expect(manifest.icons).toBeUndefined();
-    });
-
-    it('should allow icons to be overwritten from the wxt.config.ts file', async () => {
-      const project = new TestProject();
-      project.addFile('entrypoints/unlisted.html');
-      project.addFile('public/icon-16.png');
-      project.addFile('public/icon-32.png');
-      project.addFile('public/logo-16.png');
-      project.addFile('public/logo-32.png');
-      project.addFile('public/logo-48.png');
-
-      const icons = {
-        '16': 'logo-16.png',
-        '32': 'logo-32.png',
-        '48': 'logo-48.png',
-      };
-      project.setConfigFileConfig({
-        manifest: {
-          icons,
-        },
-      });
-
-      await project.build();
-      const manifest = await project.getOutputManifest();
-
-      expect(manifest.icons).toEqual(icons);
-    });
-  });
-
-  describe('content_scripts', () => {
-    it('should group content scripts and styles together based on their manifest properties', async () => {
-      const project = new TestProject();
-      project.addFile(
-        'entrypoints/one.content/index.ts',
-        `import "./style.css";
-        export default defineContentScript({
-          matches: ["*://google.com/*"],
-          main: () => {},
-        })`,
-      );
-      project.addFile(
-        'entrypoints/one.content/style.css',
-        `body { color: red }`,
-      );
-      project.addFile(
-        'entrypoints/two.content/index.ts',
-        `import "./style.css";
-        export default defineContentScript({
-          matches: ["*://google.com/*"],
-          runAt: "document_end",
-          main: () => {},
-        })`,
-      );
-      project.addFile(
-        'entrypoints/two.content/style.css',
-        `body { color: green }`,
-      );
-      project.addFile(
-        'entrypoints/three.content/index.ts',
-        `import "./style.css";
-        export default defineContentScript({
-          matches: ["*://google.com/*"],
-          runAt: "document_end",
-          main: () => {},
-        })`,
-      );
-      project.addFile(
-        'entrypoints/three.content/style.css',
-        `body { color: blue }`,
-      );
-      project.addFile(
-        'entrypoints/four.content/index.ts',
-        `import "./style.css";
-        export default defineContentScript({
-          matches: ["*://duckduckgo.com/*"],
-          runAt: "document_end",
-          main: () => {},
-        })`,
-      );
-      project.addFile(
-        'entrypoints/four.content/style.css',
-        `body { color: yellow }`,
-      );
-
-      await project.build();
-
-      const manifest = await project.getOutputManifest();
-
-      expect(manifest.content_scripts).toContainEqual({
-        matches: ['*://duckduckgo.com/*'],
-        run_at: 'document_end',
-        css: ['content-scripts/four.css'],
-        js: ['content-scripts/four.js'],
-      });
-      expect(manifest.content_scripts).toContainEqual({
-        matches: ['*://google.com/*'],
-        run_at: 'document_end',
-        css: ['content-scripts/three.css', 'content-scripts/two.css'],
-        js: ['content-scripts/three.js', 'content-scripts/two.js'],
-      });
-      expect(manifest.content_scripts).toContainEqual({
-        matches: ['*://google.com/*'],
-        css: ['content-scripts/one.css'],
-        js: ['content-scripts/one.js'],
-      });
-    });
-
-    it('should add to any content scripts declared in wxt.config.ts', async () => {
-      const project = new TestProject();
-      project.addFile(
-        'entrypoints/one.content/index.ts',
-        `export default defineContentScript({
-          matches: ["*://google.com/*"],
-          main: () => {},
-        })`,
-      );
-      project.addFile(
-        'entrypoints/two.content/style.css',
-        `body {
-          background-color: red;
-        }`,
-      );
-      project.setConfigFileConfig({
-        manifest: {
-          content_scripts: [
-            {
-              css: ['content-scripts/two.css'],
-              matches: ['*://*.google.com/*'],
-            },
-          ],
-        },
-      });
-
-      await project.build();
-
-      const manifest = await project.getOutputManifest();
-
-      expect(manifest.content_scripts).toContainEqual({
-        css: ['content-scripts/two.css'],
-        matches: ['*://*.google.com/*'],
-      });
-      expect(manifest.content_scripts).toContainEqual({
-        matches: ['*://google.com/*'],
-        js: ['content-scripts/one.js'],
-      });
-    });
-
-    it('should add a CSS entry when cssInjectionMode is undefined', async () => {
-      const project = new TestProject();
-      project.addFile(
-        'entrypoints/content/style.css',
-        'body { background-color: red; }',
-      );
-      project.addFile(
-        'entrypoints/content/index.ts',
-        `import "./style.css";
-
-        export default defineContentScript({
-          matches: ["https://*.google.com/*"],
-
-          main() {},
-        });`,
-      );
-      await project.build();
-
-      expect(await project.serializeFile('.output/chrome-mv3/manifest.json'))
-        .toMatchInlineSnapshot(`
-          ".output/chrome-mv3/manifest.json
-          ----------------------------------------
-          {"manifest_version":3,"name":"E2E Extension","description":"Example description","version":"0.0.0","content_scripts":[{"matches":["https://*.google.com/*"],"css":["content-scripts/content.css"],"js":["content-scripts/content.js"]}]}"
-        `);
-    });
-
-    it('should add a CSS entry when cssInjectionMode is "manifest"', async () => {
-      const project = new TestProject();
-      project.addFile(
-        'entrypoints/content/style.css',
-        'body { background-color: red; }',
-      );
-      project.addFile(
-        'entrypoints/content/index.ts',
-        `import "./style.css";
-
-        export default defineContentScript({
-          matches: ["https://*.google.com/*"],
-          cssInjectionMode: "manifest",
-
-          main() {},
-        });`,
-      );
-      await project.build();
-
-      expect(await project.serializeFile('.output/chrome-mv3/manifest.json'))
-        .toMatchInlineSnapshot(`
-          ".output/chrome-mv3/manifest.json
-          ----------------------------------------
-          {"manifest_version":3,"name":"E2E Extension","description":"Example description","version":"0.0.0","content_scripts":[{"matches":["https://*.google.com/*"],"css":["content-scripts/content.css"],"js":["content-scripts/content.js"]}]}"
-        `);
-    });
-
-    it('should not add an entry for CSS when cssInjectionMode is "manual"', async () => {
-      const project = new TestProject();
-      project.addFile(
-        'entrypoints/content/style.css',
-        'body { background-color: red; }',
-      );
-      project.addFile(
-        'entrypoints/content/index.ts',
-        `import "./style.css";
-
-        export default defineContentScript({
-          matches: ["https://*.google.com/*"],
-          cssInjectionMode: "manual",
-
-          main() {},
-        });`,
-      );
-      await project.build();
-
-      expect(await project.serializeFile('.output/chrome-mv3/manifest.json'))
-        .toMatchInlineSnapshot(`
-          ".output/chrome-mv3/manifest.json
-          ----------------------------------------
-          {"manifest_version":3,"name":"E2E Extension","description":"Example description","version":"0.0.0","content_scripts":[{"matches":["https://*.google.com/*"],"js":["content-scripts/content.js"]}]}"
-        `);
-    });
-
-    it('should not add a content script entry for CSS when cssInjectionMode is "ui", but add a web_accessible_resources entry for MV2', async () => {
-      const project = new TestProject();
-      project.addFile(
-        'entrypoints/content/style.css',
-        'body { background-color: red; }',
-      );
-      project.addFile(
-        'entrypoints/content/index.ts',
-        `import "./style.css";
-
-        export default defineContentScript({
-          matches: ["https://*.google.com/*"],
-          cssInjectionMode: "ui",
-
-          main() {},
-        });`,
-      );
-      await project.build({
-        manifestVersion: 2,
-      });
-
-      expect(await project.serializeFile('.output/chrome-mv2/manifest.json'))
-        .toMatchInlineSnapshot(`
-          ".output/chrome-mv2/manifest.json
-          ----------------------------------------
-          {"manifest_version":2,"name":"E2E Extension","description":"Example description","version":"0.0.0","content_scripts":[{"matches":["https://*.google.com/*"],"js":["content-scripts/content.js"]}],"web_accessible_resources":["content-scripts/content.css"]}"
-        `);
-    });
-
-    it('should not add a content script entry for CSS when cssInjectionMode is "ui", but add a web_accessible_resources entry for MV3', async () => {
-      const project = new TestProject();
-      project.addFile(
-        'entrypoints/content/style.css',
-        'body { background-color: red; }',
-      );
-      project.addFile(
-        'entrypoints/content/index.ts',
-        `import "./style.css";
-
-        export default defineContentScript({
-          matches: ["https://*.google.com/*"],
-          cssInjectionMode: "ui",
-
-          main() {},
-        });`,
-      );
-      await project.build({
-        manifestVersion: 3,
-      });
-
-      expect(await project.serializeFile('.output/chrome-mv3/manifest.json'))
-        .toMatchInlineSnapshot(`
-          ".output/chrome-mv3/manifest.json
-          ----------------------------------------
-          {"manifest_version":3,"name":"E2E Extension","description":"Example description","version":"0.0.0","content_scripts":[{"matches":["https://*.google.com/*"],"js":["content-scripts/content.js"]}],"web_accessible_resources":[{"resources":["content-scripts/content.css"],"matches":["https://*.google.com/*"]}]}"
-        `);
-    });
-  });
-
-  it('should combine web accessible resources', async () => {
-    const project = new TestProject();
-    project.addFile(
-      'entrypoints/content/style.css',
-      'body { background-color: red; }',
-    );
-    project.addFile(
-      'entrypoints/content/index.ts',
-      `import "./style.css";
-
-      export default defineContentScript({
-        matches: ["https://*.google.com/*"],
-        cssInjectionMode: "ui",
-
-        main() {},
-      });`,
-    );
-    project.setConfigFileConfig({
-      manifest: {
-        web_accessible_resources: [
-          { resources: ['one.png'], matches: ['https://one.com/*'] },
-        ],
-      },
-    });
-    await project.build();
-
-    expect(await project.serializeFile('.output/chrome-mv3/manifest.json'))
-      .toMatchInlineSnapshot(`
-        ".output/chrome-mv3/manifest.json
-        ----------------------------------------
-        {"manifest_version":3,"name":"E2E Extension","description":"Example description","version":"0.0.0","web_accessible_resources":[{"resources":["one.png"],"matches":["https://one.com/*"]},{"resources":["content-scripts/content.css"],"matches":["https://*.google.com/*"]}],"content_scripts":[{"matches":["https://*.google.com/*"],"js":["content-scripts/content.js"]}]}"
-      `);
-  });
-
-  it('should respect the transformManifest option', async () => {
-    const project = new TestProject();
-    project.addFile('entrypoints/unlisted.html');
-    project.addFile(
-      'wxt.config.ts',
-      `import { defineConfig } from 'wxt';
-
-      export default defineConfig({
-        transformManifest(manifest) {
-          manifest.author = "Custom Author"
-        }
-      })`,
-    );
-
-    await project.build();
-
-    const output = await project.serializeFile(
-      '.output/chrome-mv3/manifest.json',
-    );
-    expect(output).toMatchInlineSnapshot(`
-      ".output/chrome-mv3/manifest.json
-      ----------------------------------------
-      {"manifest_version":3,"name":"E2E Extension","description":"Example description","version":"0.0.0","author":"Custom Author"}"
-    `);
-  });
-
   it.each([
     { browser: undefined, outDir: 'chrome-mv3', expected: undefined },
     { browser: 'chrome', outDir: 'chrome-mv3', expected: undefined },
@@ -579,95 +30,4 @@ describe('Manifest Content', () => {
       expect(safariManifest.background.persistent).toBe(expected);
     },
   );
-
-  describe('versions', () => {
-    it.each([
-      ['chrome', 3] as const,
-      ['safari', 2] as const,
-      ['edge', 3] as const,
-    ])(
-      'should include version_name on %s when it needs simplified',
-      async (browser, manifestVersion) => {
-        const project = new TestProject({
-          version: '1.0.0-alpha1',
-        });
-        project.addFile('entrypoints/unlisted.html');
-
-        await project.build({ browser, manifestVersion });
-        const manifest = await project.getOutputManifest(
-          `.output/${browser}-mv${manifestVersion}/manifest.json`,
-        );
-
-        expect(manifest.version).toBe('1.0.0');
-        expect(manifest.version_name).toBe('1.0.0-alpha1');
-      },
-    );
-
-    it.each([['firefox', 2] as const])(
-      "should not include a version_name on %s because the browser doesn't support it",
-      async (browser, manifestVersion) => {
-        const project = new TestProject({
-          version: '1.0.0-alpha1',
-        });
-        project.addFile('entrypoints/unlisted.html');
-
-        await project.build({ browser, manifestVersion });
-        const manifest = await project.getOutputManifest(
-          `.output/${browser}-mv${manifestVersion}/manifest.json`,
-        );
-
-        expect(manifest.version).toBe('1.0.0');
-        expect(manifest.version_name).toBeUndefined();
-      },
-    );
-
-    it.each([
-      ['chrome', 3] as const,
-      ['firefox', 2] as const,
-      ['safari', 3] as const,
-      ['edge', 3] as const,
-    ])(
-      'should not include the version_name if it is equal to version',
-      async (browser, manifestVersion) => {
-        const project = new TestProject({
-          version: '1.0.0.1',
-        });
-        project.addFile('entrypoints/unlisted.html');
-
-        await project.build({ browser, manifestVersion });
-        const manifest = await project.getOutputManifest(
-          `.output/${browser}-mv${manifestVersion}/manifest.json`,
-        );
-
-        expect(manifest.version).toBe('1.0.0.1');
-        expect(manifest.version_name).toBeUndefined();
-      },
-    );
-  });
-
-  it('should respect the action field in the manifest without a popup', async () => {
-    const project = new TestProject();
-    project.addFile('entrypoints/unlisted.html');
-    project.setConfigFileConfig({
-      manifest: {
-        action: {
-          default_title: 'Hello world',
-        },
-      },
-    });
-
-    await project.build();
-
-    expect(await project.getOutputManifest()).toMatchInlineSnapshot(`
-      {
-        "action": {
-          "default_title": "Hello world",
-        },
-        "description": "Example description",
-        "manifest_version": 3,
-        "name": "E2E Extension",
-        "version": "0.0.0",
-      }
-    `);
-  });
 });

e2e/tests/typescript-project.test.ts

@@ -227,7 +227,7 @@ describe('TypeScript Project', () => {
       ".wxt/wxt.d.ts
       ----------------------------------------
       // Generated by wxt
-      /// <reference types="vite/client" />
+      /// <reference types="wxt/vite-builder-env" />
       /// <reference types="./types/imports.d.ts" />
       /// <reference types="./types/paths.d.ts" />
       /// <reference types="./types/i18n.d.ts" />

package.json

@@ -1,7 +1,7 @@
 {
   "name": "wxt",
   "type": "module",
-  "version": "0.12.2",
+  "version": "0.13.3",
   "description": "Next gen framework for developing web extensions",
   "engines": {
     "node": ">=18",
@@ -76,6 +76,9 @@
         "types": "./dist/storage.d.cts",
         "default": "./dist/storage.cjs"
       }
+    },
+    "./vite-builder-env": {
+      "types": "./dist/vite-builder-env.d.ts"
     }
   },
   "scripts": {
@@ -90,7 +93,7 @@
     "compile:wxt": "tsc --noEmit",
     "compile:virtual": "tsc --noEmit -p src/virtual",
     "test": "vitest",
-    "test:coverage": "vitest run --coverage",
+    "test:coverage": "vitest run --coverage.enabled \"--coverage.include=src/**\" \"--coverage.exclude=src/core/utils/testing/**\" \"--coverage.exclude=**/*.d.ts\"",
     "prepare": "simple-git-hooks",
     "prepublish": "pnpm -s build",
     "docs:gen": "typedoc --options docs/typedoc.json",
@@ -102,7 +105,7 @@
   "dependencies": {
     "@types/webextension-polyfill": "^0.10.5",
     "@webext-core/fake-browser": "^1.3.1",
-    "@webext-core/isolated-element": "^1.0.4",
+    "@webext-core/isolated-element": "^1.1.1",
     "@webext-core/match-patterns": "^1.0.3",
     "async-mutex": "^0.4.0",
     "c12": "^1.5.1",
@@ -110,6 +113,7 @@
     "chokidar": "^3.5.3",
     "consola": "^3.2.3",
     "defu": "^6.1.3",
+    "dequal": "^2.0.3",
     "esbuild": "^0.19.5",
     "fast-glob": "^3.3.1",
     "filesize": "^10.0.8",
@@ -128,7 +132,6 @@
     "prompts": "^2.4.2",
     "rollup-plugin-visualizer": "^5.9.2",
     "unimport": "^3.4.0",
-    "unstorage": "^1.9.0",
     "vite": "^5.0.0",
     "web-ext-run": "^0.1.0",
     "webextension-polyfill": "^0.10.0",
@@ -157,8 +160,8 @@
     "typedoc-plugin-markdown": "4.0.0-next.23",
     "typedoc-vitepress-theme": "1.0.0-next.3",
     "typescript": "^5.3.2",
-    "vitepress": "1.0.0-rc.31",
-    "vitest": "^1.0.0",
+    "vitepress": "1.0.0-rc.34",
+    "vitest": "^1.1.0",
     "vitest-mock-extended": "^1.3.1",
     "vue": "^3.3.10"
   },

scripts/build.ts

@@ -29,9 +29,9 @@ const preset = {
 } satisfies tsup.Options;
 
 function spinnerPMap(configs: tsup.Options[]) {
-  let completed = 0;
+  let progress = 1;
   const updateSpinner = () => {
-    spinner.text = `${spinnerText} [${completed}/${configs.length}]`;
+    spinner.text = `${spinnerText} [${progress}/${configs.length}]`;
   };
   updateSpinner();
 
@@ -39,7 +39,7 @@ function spinnerPMap(configs: tsup.Options[]) {
     config,
     async (config) => {
       const res = await tsup.build(config);
-      completed++;
+      progress++;
       updateSpinner();
       return res;
     },
@@ -106,6 +106,9 @@ await spinnerPMap(config).catch((err) => {
   process.exit(1);
 });
 
+// Copy "public" files that need shipped inside WXT
+await fs.copyFile('src/vite-builder-env.d.ts', 'dist/vite-builder-env.d.ts');
+
 spinner.clear().stop();
 
 const duration = Date.now() - startTime;

src/__tests__/storage.test.ts

@@ -1,11 +1,12 @@
 import { fakeBrowser } from '@webext-core/fake-browser';
-import { describe, it, expect, beforeEach } from 'vitest';
+import { describe, it, expect, beforeEach, vi } from 'vitest';
 import { browser } from '~/browser';
 import { storage } from '~/storage';
 
 describe('Storage Utils', () => {
   beforeEach(() => {
     fakeBrowser.reset();
+    storage.unwatch();
   });
 
   describe.each(['local', 'sync', 'managed', 'session'] as const)(
@@ -15,33 +16,89 @@ describe('Storage Utils', () => {
         it('should return the value from the correct storage area', async () => {
           const expected = 123;
           await fakeBrowser.storage[storageArea].set({ count: expected });
-          expect(await storage.getItem(`${storageArea}:count`)).toBe(expected);
+
+          const actual = await storage.getItem(`${storageArea}:count`);
+
+          expect(actual).toBe(expected);
+        });
+
+        it('should return the value if multiple : are use in the key', async () => {
+          const expected = 'value';
+          await fakeBrowser.storage[storageArea].set({ 'some:key': expected });
+
+          const actual = await storage.getItem(`${storageArea}:some:key`);
+
+          expect(actual).toBe(expected);
         });
 
         it("should return null if the value doesn't exist", async () => {
-          expect(await storage.getItem(`${storageArea}:count`)).toBeNull();
+          const actual = await storage.getItem(`${storageArea}:count`);
+
+          expect(actual).toBeNull();
+        });
+
+        it('should return the default value if passed in options', async () => {
+          const expected = 0;
+          const actual = await storage.getItem(`${storageArea}:count`, {
+            defaultValue: expected,
+          });
+
+          expect(actual).toBe(expected);
         });
       });
 
       describe('getItems', () => {
-        it('should return an array of values in the same order as the keys passed in', async () => {
+        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 },
+          ];
+          const params = [
+            expected[0].key,
+            expected[1].key,
+            {
+              key: expected[2].key,
+              options: { defaultValue: expected[2].value },
+            },
           ];
-          const keys = expected.map((item) => item.key);
           await fakeBrowser.storage[storageArea].set({
             count: expected[0].value,
           });
 
-          const actual = await storage.getItems(keys);
+          const actual = await storage.getItems(params);
+
+          expect(actual).toHaveLength(3);
+          expected.forEach((item) => {
+            expect(actual).toContainEqual(item);
+          });
+        });
+      });
+
+      describe('getMeta', () => {
+        it('should return item metadata from key+$', async () => {
+          const expected = { v: 1 };
+          await fakeBrowser.storage[storageArea].set({ count$: expected });
+
+          const actual = await storage.getMeta(`${storageArea}:count`);
 
           expect(actual).toEqual(expected);
         });
+
+        it('should return an empty object if missing', async () => {
+          const actual = await storage.getMeta(`${storageArea}:count`);
+
+          expect(actual).toEqual({});
+        });
       });
 
       describe('setItem', () => {
-        it('should set the value in the correct storage area', () => {});
+        it('should set the value in the correct storage area', async () => {
+          const key = `${storageArea}:count`;
+          const value = 321;
+
+          await storage.setItem(key, value);
+        });
 
         it.each([undefined, null])(
           'should remove the item from storage when setting the value to %s',
@@ -57,12 +114,685 @@ describe('Storage Utils', () => {
         );
       });
 
+      describe('setItems', () => {
+        it('should set multiple items in storage', async () => {
+          const expected = [
+            { key: `${storageArea}:count`, value: 234 },
+            { key: `${storageArea}:installDate`, value: null },
+          ];
+          await fakeBrowser.storage[storageArea].set({
+            count: 123,
+            installDate: 321,
+          });
+
+          await storage.setItems(expected);
+          const actual = await storage.getItems(
+            expected.map((item) => item.key),
+          );
+
+          expect(actual).toHaveLength(2);
+          expected.forEach((item) => {
+            expect(actual).toContainEqual(item);
+          });
+        });
+      });
+
+      describe('setMeta', () => {
+        it('should set metadata at key+$', async () => {
+          const existing = { v: 1 };
+          await browser.storage[storageArea].set({ count$: existing });
+          const newValues = {
+            date: Date.now(),
+          };
+          const expected = { ...existing, ...newValues };
+
+          await storage.setMeta(`${storageArea}:count`, newValues);
+          const actual = await storage.getMeta(`${storageArea}:count`);
+
+          expect(actual).toEqual(expected);
+        });
+
+        it.each([undefined, null])(
+          'should remove any properties set to %s',
+          async (version) => {
+            const existing = { v: 1 };
+            await browser.storage[storageArea].set({ count$: existing });
+            const expected = {};
+
+            await storage.setMeta(`${storageArea}:count`, { v: version });
+            const actual = await storage.getMeta(`${storageArea}:count`);
+
+            expect(actual).toEqual(expected);
+          },
+        );
+      });
+
       describe('removeItem', () => {
         it('should remove the key from storage', async () => {
           await fakeBrowser.storage[storageArea].set({ count: 456 });
-          await storage.removeItem(`${storageArea}:count`);
 
-          expect(await browser.storage[storageArea].get()).toEqual({});
+          await storage.removeItem(`${storageArea}:count`);
+          const actual = await storage.getItem(`${storageArea}:count`);
+
+          expect(actual).toBeNull();
+        });
+
+        it('should not remove the metadata by default', async () => {
+          const expected = { v: 1 };
+          await fakeBrowser.storage[storageArea].set({
+            count$: expected,
+            count: 3,
+          });
+
+          await storage.removeItem(`${storageArea}:count`);
+          const actual = await storage.getMeta(`${storageArea}:count`);
+
+          expect(actual).toEqual(expected);
+        });
+
+        it('should remove the metadata when requested', async () => {
+          await fakeBrowser.storage[storageArea].set({
+            count$: { v: 1 },
+            count: 3,
+          });
+
+          await storage.removeItem(`${storageArea}:count`, {
+            removeMeta: true,
+          });
+          const actual = await storage.getMeta(`${storageArea}:count`);
+
+          expect(actual).toEqual({});
+        });
+      });
+
+      describe('removeItems', () => {
+        it('should remove multiple items', async () => {
+          const key1 = `${storageArea}:one`;
+          const key2 = `${storageArea}:two`;
+          const key3 = `${storageArea}:three`;
+          await fakeBrowser.storage[storageArea].set({
+            ['one']: '1',
+            ['two']: null,
+            ['two$']: { v: 1 },
+            ['three']: '1',
+            ['three$']: { v: 1 },
+          });
+
+          await storage.removeItems([
+            key1,
+            key2,
+            { key: key3, options: { removeMeta: true } },
+          ]);
+
+          expect(await storage.getItem(key1)).toBeNull();
+          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({});
+        });
+      });
+
+      describe('removeMeta', () => {
+        it('should remove all metadata', async () => {
+          await fakeBrowser.storage[storageArea].set({ count$: { v: 4 } });
+
+          await storage.removeMeta(`${storageArea}:count`);
+          const actual = await storage.getMeta(`${storageArea}:count`);
+
+          expect(actual).toEqual({});
+        });
+
+        it('should only remove specific properties', async () => {
+          await fakeBrowser.storage[storageArea].set({
+            count$: { v: 4, d: Date.now() },
+          });
+
+          await storage.removeMeta(`${storageArea}:count`, ['d']);
+          const actual = await storage.getMeta(`${storageArea}:count`);
+
+          expect(actual).toEqual({ v: 4 });
+        });
+      });
+
+      describe('snapshot', () => {
+        it('should return a snapshot of the entire storage without area prefixes', async () => {
+          const expected = {
+            count: 1,
+            count$: { v: 2 },
+            example: 'test',
+          };
+
+          await fakeBrowser.storage[storageArea].set(expected);
+          const actual = await storage.snapshot(storageArea);
+
+          expect(actual).toEqual(expected);
+        });
+
+        it('should exclude specific properties and their metadata', async () => {
+          const input = {
+            count: 1,
+            count$: { v: 2 },
+            example: 'test',
+          };
+          const excludeKeys = ['count'];
+          const expected = {
+            example: 'test',
+          };
+
+          await fakeBrowser.storage[storageArea].set(input);
+          const actual = await storage.snapshot(storageArea, { excludeKeys });
+
+          expect(actual).toEqual(expected);
+        });
+      });
+
+      describe('restoreSnapshot', () => {
+        it('should restore a snapshot object by setting all values in storage', async () => {
+          const data = {
+            one: 'one',
+            two: 'two',
+          };
+          const existing = {
+            two: 'two-two',
+            three: 'three',
+          };
+          await fakeBrowser.storage[storageArea].set(existing);
+
+          await storage.restoreSnapshot(storageArea, data);
+          const actual = await storage.snapshot(storageArea);
+
+          expect(actual).toEqual({ ...existing, ...data });
+        });
+
+        it('should overwrite, not merge, any metadata keys in the snapshot', async () => {
+          const existing = {
+            count: 1,
+            count$: {
+              v: 2,
+            },
+          };
+          const data = {
+            count$: {
+              restoredAt: Date.now(),
+            },
+          };
+          const expected = {
+            ...existing,
+            count$: data.count$,
+          };
+          await fakeBrowser.storage[storageArea].set(existing);
+
+          await storage.restoreSnapshot(storageArea, data);
+          const actual = await storage.snapshot(storageArea);
+
+          expect(actual).toEqual(expected);
+        });
+      });
+
+      describe('watch', () => {
+        it('should not trigger if the changed key is different from the requested key', async () => {
+          const cb = vi.fn();
+
+          storage.watch(`${storageArea}:key`, cb);
+          await storage.setItem(`${storageArea}:not-the-key`, '123');
+
+          expect(cb).not.toBeCalled();
+        });
+
+        it("should not trigger if the value doesn't change", async () => {
+          const cb = vi.fn();
+          const value = '123';
+
+          await storage.setItem(`${storageArea}:key`, value);
+          storage.watch(`${storageArea}:key`, cb);
+          await storage.setItem(`${storageArea}:key`, value);
+
+          expect(cb).not.toBeCalled();
+        });
+
+        it('should call the callback when the value changes', async () => {
+          const cb = vi.fn();
+          const newValue = '123';
+          const oldValue = null;
+
+          storage.watch(`${storageArea}:key`, cb);
+          await storage.setItem(`${storageArea}:key`, newValue);
+
+          expect(cb).toBeCalledTimes(1);
+          expect(cb).toBeCalledWith(newValue, oldValue);
+        });
+
+        it('should remove the listener when calling the returned function', async () => {
+          const cb = vi.fn();
+
+          const unwatch = storage.watch(`${storageArea}:key`, cb);
+          unwatch();
+          await storage.setItem(`${storageArea}:key`, '123');
+
+          expect(cb).not.toBeCalled();
+        });
+      });
+
+      describe('unwatch', () => {
+        it('should remove all watch listeners', async () => {
+          const cb = vi.fn();
+
+          storage.watch(`${storageArea}:key`, cb);
+          storage.unwatch();
+          await storage.setItem(`${storageArea}:key`, '123');
+
+          expect(cb).not.toBeCalled();
+        });
+      });
+
+      describe('defineItem', () => {
+        describe('versioning', () => {
+          /**
+           * This works because fakeBrowser is syncrounous, and is will finish any number of chained
+           * calls within a single tick of the event loop, ie: a timeout of 0.
+           */
+          async function waitForMigrations() {
+            return new Promise((res) => setTimeout(res));
+          }
+
+          it('should migrate values to the latest when a version upgrade is detected', async () => {
+            await fakeBrowser.storage[storageArea].set({
+              count: 2,
+              count$: { v: 1 },
+            });
+            const migrateToV2 = vi.fn((oldCount) => oldCount * 2);
+            const migrateToV3 = vi.fn((oldCount) => oldCount * 3);
+
+            const item = storage.defineItem<number, { v: number }>(
+              `${storageArea}:count`,
+              {
+                version: 3,
+                migrations: {
+                  2: migrateToV2,
+                  3: migrateToV3,
+                },
+              },
+            );
+            await waitForMigrations();
+
+            const actualValue = await item.getValue();
+            const actualMeta = await item.getMeta();
+
+            expect(actualValue).toEqual(12);
+            expect(actualMeta).toEqual({ v: 3 });
+
+            expect(migrateToV2).toBeCalledTimes(1);
+            expect(migrateToV2).toBeCalledWith(2);
+
+            expect(migrateToV3).toBeCalledTimes(1);
+            expect(migrateToV3).toBeCalledWith(4);
+          });
+
+          it("should not run migrations if the value doesn't exist yet", async () => {
+            const migrateToV2 = vi.fn((oldCount) => oldCount * 2);
+            const migrateToV3 = vi.fn((oldCount) => oldCount * 3);
+
+            const item = storage.defineItem<number, { v: number }>(
+              `${storageArea}:count`,
+              {
+                version: 3,
+                migrations: {
+                  2: migrateToV2,
+                  3: migrateToV3,
+                },
+              },
+            );
+            await waitForMigrations();
+
+            const actualValue = await item.getValue();
+            const actualMeta = await item.getMeta();
+
+            expect(actualValue).toBeNull();
+            expect(actualMeta).toEqual({});
+
+            expect(migrateToV2).not.toBeCalled();
+            expect(migrateToV3).not.toBeCalled();
+          });
+
+          it('should run the v2 migration when converting an unversioned item to a versioned one', async () => {
+            await fakeBrowser.storage[storageArea].set({
+              count: 2,
+            });
+            const migrateToV2 = vi.fn((oldCount) => oldCount * 2);
+
+            const item = storage.defineItem<number, { v: number }>(
+              `${storageArea}:count`,
+              {
+                version: 2,
+                migrations: {
+                  2: migrateToV2,
+                },
+              },
+            );
+            await waitForMigrations();
+
+            const actualValue = await item.getValue();
+            const actualMeta = await item.getMeta();
+
+            expect(actualValue).toEqual(4);
+            expect(actualMeta).toEqual({ v: 2 });
+
+            expect(migrateToV2).toBeCalledTimes(1);
+            expect(migrateToV2).toBeCalledWith(2);
+          });
+
+          it('Should not run old migrations if the version is unchanged', async () => {
+            await fakeBrowser.storage[storageArea].set({
+              count: 2,
+              count$: { v: 3 },
+            });
+            const migrateToV2 = vi.fn((oldCount) => oldCount * 2);
+            const migrateToV3 = vi.fn((oldCount) => oldCount * 3);
+
+            storage.defineItem<number, { v: number }>(`${storageArea}:count`, {
+              version: 3,
+              migrations: {
+                2: migrateToV2,
+                3: migrateToV3,
+              },
+            });
+            await waitForMigrations();
+
+            expect(migrateToV2).not.toBeCalled();
+            expect(migrateToV3).not.toBeCalled();
+          });
+
+          it('should skip missing migration functions', async () => {
+            await fakeBrowser.storage[storageArea].set({
+              count: 2,
+              count$: { v: 0 },
+            });
+            const migrateToV1 = vi.fn((oldCount) => oldCount * 1);
+            const migrateToV3 = vi.fn((oldCount) => oldCount * 3);
+
+            const item = storage.defineItem<number, { v: number }>(
+              `${storageArea}:count`,
+              {
+                version: 3,
+                migrations: {
+                  1: migrateToV1,
+                  3: migrateToV3,
+                },
+              },
+            );
+            await waitForMigrations();
+
+            const actualValue = await item.getValue();
+            const actualMeta = await item.getMeta();
+
+            expect(actualValue).toEqual(6);
+            expect(actualMeta).toEqual({ v: 3 });
+
+            expect(migrateToV1).toBeCalledTimes(1);
+            expect(migrateToV1).toBeCalledWith(2);
+
+            expect(migrateToV3).toBeCalledTimes(1);
+            expect(migrateToV3).toBeCalledWith(2);
+          });
+
+          it('should throw an error if the new version is less than the previous version', async () => {
+            const prevVersion = 2;
+            const nextVersion = 1;
+            await fakeBrowser.storage[storageArea].set({
+              count: 0,
+              count$: { v: prevVersion },
+            });
+
+            const item = storage.defineItem(`${storageArea}:count`, {
+              version: nextVersion,
+            });
+
+            // @ts-expect-error: _migrationsCompleted is returned, but untyped
+            await expect(item._migrationsCompleted).rejects.toThrow(
+              'version downgrade detected',
+            );
+          });
+        });
+
+        describe('getValue', () => {
+          it('should return the value from storage', async () => {
+            const expected = 2;
+            const item = storage.defineItem<number>(`${storageArea}:count`);
+            await fakeBrowser.storage[storageArea].set({ count: expected });
+
+            const actual = await item.getValue();
+
+            expect(actual).toBe(expected);
+          });
+
+          it('should return null if missing', async () => {
+            const item = storage.defineItem<number>(`${storageArea}:count`);
+
+            const actual = await item.getValue();
+
+            expect(actual).toBeNull();
+          });
+
+          it('should return the provided default value if missing', async () => {
+            const expected = 0;
+            const item = storage.defineItem(`${storageArea}:count`, {
+              defaultValue: expected,
+            });
+
+            const actual = await item.getValue();
+
+            expect(actual).toEqual(expected);
+          });
+        });
+
+        describe('getMeta', () => {
+          it('should return the value from storage at key+$', async () => {
+            const expected = { v: 2 };
+            const item = storage.defineItem<number, { v: number }>(
+              `${storageArea}:count`,
+            );
+            await fakeBrowser.storage[storageArea].set({ count$: expected });
+
+            const actual = await item.getMeta();
+
+            expect(actual).toBe(expected);
+          });
+
+          it('should return an empty object if missing', async () => {
+            const expected = {};
+            const item = storage.defineItem<number, { v: number }>(
+              `${storageArea}:count`,
+            );
+
+            const actual = await item.getMeta();
+
+            expect(actual).toEqual(expected);
+          });
+        });
+
+        describe('setValue', () => {
+          it('should set the value in storage', async () => {
+            const expected = 1;
+            const item = storage.defineItem<number>(`${storageArea}:count`);
+
+            await item.setValue(expected);
+            const actual = await item.getValue();
+
+            expect(actual).toBe(expected);
+          });
+
+          it.each([undefined, null])(
+            'should remove the value in storage when %s is passed in',
+            async (value) => {
+              const item = storage.defineItem<number>(`${storageArea}:count`);
+
+              // @ts-expect-error: undefined is not assignable to null, but we're testing that case on purpose
+              await item.setValue(value);
+              const actual = await item.getValue();
+
+              expect(actual).toBeNull();
+            },
+          );
+        });
+
+        describe('setMeta', () => {
+          it('should set metadata at key+$', async () => {
+            const expected = { date: Date.now() };
+            const item = storage.defineItem<number, { date: number }>(
+              `${storageArea}:count`,
+            );
+
+            await item.setMeta(expected);
+            const actual = await item.getMeta();
+
+            expect(actual).toEqual(expected);
+          });
+
+          it('should add to metadata if already present', async () => {
+            const existing = { v: 2 };
+            const newFields = { date: Date.now() };
+            const expected = { ...existing, ...newFields };
+            const item = storage.defineItem<
+              number,
+              { date: number; v: number }
+            >(`${storageArea}:count`);
+            await fakeBrowser.storage[storageArea].set({
+              count$: existing,
+            });
+
+            await item.setMeta(newFields);
+            const actual = await item.getMeta();
+
+            expect(actual).toEqual(expected);
+          });
+        });
+
+        describe('removeValue', () => {
+          it('should remove the key from storage', async () => {
+            const item = storage.defineItem(`${storageArea}:count`);
+            await fakeBrowser.storage[storageArea].set({ count: 456 });
+
+            await item.removeValue();
+            const actual = await item.getValue();
+
+            expect(actual).toBeNull();
+          });
+
+          it('should not remove the metadata by default', async () => {
+            const item = storage.defineItem(`${storageArea}:count`);
+            const expected = { v: 1 };
+            await fakeBrowser.storage[storageArea].set({
+              count$: expected,
+              count: 3,
+            });
+
+            await item.removeValue();
+            const actual = await item.getMeta();
+
+            expect(actual).toEqual(expected);
+          });
+
+          it('should remove the metadata when requested', async () => {
+            const item = storage.defineItem(`${storageArea}:count`);
+            await fakeBrowser.storage[storageArea].set({
+              count$: { v: 1 },
+              count: 3,
+            });
+
+            await item.removeValue({ removeMeta: true });
+            const actual = await item.getMeta();
+
+            expect(actual).toEqual({});
+          });
+        });
+
+        describe('removeMeta', () => {
+          it('should remove all metadata', async () => {
+            const item = storage.defineItem<number, { v: number }>(
+              `${storageArea}:count`,
+            );
+            await fakeBrowser.storage[storageArea].set({ count$: { v: 4 } });
+
+            await item.removeMeta();
+            const actual = await item.getMeta();
+
+            expect(actual).toEqual({});
+          });
+
+          it('should only remove specific properties', async () => {
+            const item = storage.defineItem<number, { v: number; d: number }>(
+              `${storageArea}:count`,
+            );
+            await fakeBrowser.storage[storageArea].set({
+              count$: { v: 4, d: Date.now() },
+            });
+
+            await item.removeMeta(['d']);
+            const actual = await item.getMeta();
+
+            expect(actual).toEqual({ v: 4 });
+          });
+        });
+
+        describe('watch', () => {
+          it("should not trigger if the changed key is different from the item's key", async () => {
+            const item = storage.defineItem(`${storageArea}:key`);
+            const cb = vi.fn();
+
+            item.watch(cb);
+            await storage.setItem(`${storageArea}:not-the-key`, '123');
+
+            expect(cb).not.toBeCalled();
+          });
+
+          it("should not trigger if the value doesn't change", async () => {
+            const item = storage.defineItem(`${storageArea}:key`);
+            const cb = vi.fn();
+            const value = '123';
+
+            await item.setValue(value);
+            item.watch(cb);
+            await item.setValue(value);
+
+            expect(cb).not.toBeCalled();
+          });
+
+          it('should call the callback when the value changes', async () => {
+            const item = storage.defineItem(`${storageArea}:key`);
+            const cb = vi.fn();
+            const newValue = '123';
+            const oldValue = null;
+
+            item.watch(cb);
+            await item.setValue(newValue);
+
+            expect(cb).toBeCalledTimes(1);
+            expect(cb).toBeCalledWith(newValue, oldValue);
+          });
+
+          it('should remove the listener when calling the returned function', async () => {
+            const item = storage.defineItem(`${storageArea}:key`);
+            const cb = vi.fn();
+
+            const unwatch = item.watch(cb);
+            unwatch();
+            await item.setValue('123');
+
+            expect(cb).not.toBeCalled();
+          });
+        });
+
+        describe('unwatch', () => {
+          it('should remove all watch listeners', async () => {
+            const item = storage.defineItem(`${storageArea}:key`);
+            const cb = vi.fn();
+
+            item.watch(cb);
+            storage.unwatch();
+            await item.setValue('123');
+
+            expect(cb).not.toBeCalled();
+          });
         });
       });
     },

src/cli.ts

@@ -5,6 +5,9 @@ import consola, { LogLevels } from 'consola';
 import { printHeader } from '~/core/utils/log';
 import { formatDuration } from '~/core/utils/time';
 
+// TODO: Remove. See https://github.com/wxt-dev/wxt/issues/277
+process.env.VITE_CJS_IGNORE_WARNING = 'true';
+
 const cli = cac('wxt');
 cli.help();
 cli.version(version);

src/client/content-scripts/__tests__/content-script-ui.test.ts

@@ -5,6 +5,7 @@ import { ContentScriptContext } from '~/client/content-scripts/content-script-co
 import { createIsolatedElement } from '@webext-core/isolated-element';
 import { mock } from 'vitest-mock-extended';
 import { browser } from '~/browser';
+import { faker } from '@faker-js/faker';
 
 vi.mock('@webext-core/isolated-element', async () => {
   const { vi } = await import('vitest');
@@ -332,4 +333,26 @@ describe('createContentScriptUi', () => {
       expect(document.querySelector('test-app')).toBeDefined();
     });
   });
+
+  it('should forward isolateEvents into createIsolatedElement', async () => {
+    const isolateEvents = faker.helpers.arrayElement([
+      undefined,
+      true,
+      false,
+      ['click', 'keydown'],
+    ]);
+    await createContentScriptUi(createCtx(), {
+      name: 'test-app',
+      type: 'inline',
+      mount: testApp,
+      isolateEvents,
+    });
+
+    expect(createIsolatedElementMock).toBeCalledTimes(1);
+    expect(createIsolatedElementMock).toBeCalledWith(
+      expect.objectContaining({
+        isolateEvents,
+      }),
+    );
+  });
 });

src/client/content-scripts/content-script-ui.ts

@@ -10,8 +10,8 @@ import {
 } from '../utils/content-script-ui';
 
 /**
- * Utility for mounting content script UI's with isolated styles. Automatically removed from the DOM
- * when the content script's context is invalidated.
+ * Utility for mounting content script UI's with isolated styles and controlled event bubbling.
+ * Automatically removed from the DOM when the content script's context is invalidated.
  *
  * See https://wxt.dev/guide/content-script-ui.html for full documentation.
  *
@@ -31,7 +31,7 @@ import {
  *         const app = document.createElement("div");
  *         app.textContent = "Content Script UI";
  *         container.append(app);
- *       }
+ *       },
  *     })
  *     ui.mount();
  *   }
@@ -56,6 +56,7 @@ export async function createContentScriptUi<TApp>(
       textContent: css.join('\n').trim(),
     },
     mode: 'open',
+    isolateEvents: options.isolateEvents,
   });
 
   let mounted: TApp;
@@ -170,4 +171,13 @@ export type ContentScriptUiOptions<TApp> = ContentScriptPositioningOptions &
      * See https://wxt.dev/guide/content-script-ui.html for more info.
      */
     css?: string;
+    /**
+     * When enabled, `event.stopPropagation` will be called on events trying to bubble out of the
+     * shadow root.
+     *
+     * - Set to `true` to stop the propagation of a default set of events,
+     *   `["keyup", "keydown", "keypress"]`
+     * - Set to an array of event names to stop the propagation of a custom list of events
+     */
+    isolateEvents?: boolean | string[];
   };

src/core/builders/vite/plugins/index.ts

@@ -9,7 +9,6 @@ export * from './noopBackground';
 export * from './cssEntrypoints';
 export * from './bundleAnalysis';
 export * from './globals';
-export * from './webextensionPolyfillAlias';
-export * from './webextensionPolyfillInlineDeps';
+export * from './webextensionPolyfillMock';
 export * from './excludeBrowserPolyfill';
 export * from './entrypointGroupGlobals';

src/core/builders/vite/plugins/noopBackground.ts

@@ -2,9 +2,8 @@ import { Plugin } from 'vite';
 import { VIRTUAL_NOOP_BACKGROUND_MODULE_ID } from '~/core/utils/constants';
 
 /**
- * In dev mode, if there's not a background script listed, we need to add one.
- *
- * This define's a virtual module that is basically just a noop.
+ * In dev mode, if there's not a background script listed, we need to add one so that the web socket
+ * connection is setup and the extension reloads HTML pages and content scripts correctly.
  */
 export function noopBackground(): Plugin {
   const virtualModuleId = VIRTUAL_NOOP_BACKGROUND_MODULE_ID;
@@ -16,7 +15,7 @@ export function noopBackground(): Plugin {
     },
     load(id) {
       if (id === resolvedVirtualModuleId) {
-        return `import { defineBackground } from 'wxt/client';\nexport default defineBackground(() => void 0)`;
+        return `import { defineBackground } from 'wxt/sandbox';\nexport default defineBackground(() => void 0)`;
       }
     },
   };

src/core/builders/vite/plugins/webextensionPolyfillAlias.ts

@@ -1,28 +0,0 @@
-import path from 'node:path';
-import type * as vite from 'vite';
-import { InternalConfig } from '~/types';
-
-/**
- * Creates an alias to redirect "webextension-polyfill" imports to WXT's `fakeBrowser`.
- *
- * This should only be used during tests.
- */
-export function webextensionPolyfillAlias(
-  config: Omit<InternalConfig, 'builder'>,
-): vite.PluginOption {
-  return {
-    name: 'wxt:webextension-polyfill-test-alias',
-    config() {
-      return {
-        resolve: {
-          alias: {
-            'webextension-polyfill': path.resolve(
-              config.root,
-              'node_modules/wxt/dist/virtual/mock-browser',
-            ),
-          },
-        },
-      };
-    },
-  };
-}

src/core/builders/vite/plugins/webextensionPolyfillInlineDeps.ts

@@ -1,24 +0,0 @@
-import type * as vite from 'vite';
-
-/**
- * Add all deps that import `webextension-polyfill` to `test.server.deps.inline`.
- *
- * TODO: Auto-detect non-wxt dependencies via `npm list`.
- */
-export function webextensionPolyfillInlineDeps(): vite.PluginOption {
-  return {
-    name: 'wxt:testing-inline-deps',
-    config() {
-      const wxtModules = ['wxt/browser'];
-      return {
-        test: {
-          server: {
-            deps: {
-              inline: [...wxtModules],
-            },
-          },
-        },
-      };
-    },
-  };
-}

src/core/builders/vite/plugins/webextensionPolyfillMock.ts

@@ -0,0 +1,41 @@
+import path from 'node:path';
+import type * as vite from 'vite';
+import { InternalConfig } from '~/types';
+
+/**
+ * Mock `webextension-polyfill` by inlining all dependencies that import it and adding a custom
+ * alias so that Vite resolves to a mocked version of the module.
+ *
+ * There are two ways to mark a module as inline:
+ * 1. Use partial file paths ("wxt/dist/browser.js") in the `test.server.deps.inline` option.
+ * 2. Use module names ("wxt" or "@webext-core/messaging") in the `ssr.noExternalize` option.
+ *
+ * This plugin uses the second approach since it's a little more intuative to understand.
+ *
+ * TODO: Detect non-wxt dependencies (like `@webext-core/*`) that import `webextension-polyfill` via
+ * `npm list` and inline them automatically.
+ */
+export function webextensionPolyfillMock(
+  config: Omit<InternalConfig, 'builder'>,
+): vite.PluginOption {
+  return {
+    name: 'wxt:testing-inline-deps',
+    config() {
+      return {
+        resolve: {
+          alias: {
+            // Alias to use a mocked version of the polyfill
+            'webextension-polyfill': path.resolve(
+              config.root,
+              'node_modules/wxt/dist/virtual/mock-browser',
+            ),
+          },
+        },
+        ssr: {
+          // Inline all WXT modules
+          noExternal: ['wxt'],
+        },
+      };
+    },
+  };
+}

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

@@ -0,0 +1,912 @@
+import { describe, expect, it } from 'vitest';
+import { generateManifest } from '../manifest';
+import {
+  fakeArray,
+  fakeBackgroundEntrypoint,
+  fakeBuildOutput,
+  fakeEntrypoint,
+  fakeInternalConfig,
+  fakeOptionsEntrypoint,
+  fakePopupEntrypoint,
+} from '../testing/fake-objects';
+import { Manifest } from 'webextension-polyfill';
+import {
+  BuildOutput,
+  ContentScriptEntrypoint,
+  Entrypoint,
+  OutputAsset,
+} from '~/types';
+
+const outDir = '/output';
+const contentScriptOutDir = '/output/content-scripts';
+
+describe('Manifest Utils', () => {
+  describe('generateManifest', () => {
+    describe('popup', () => {
+      type ActionType = 'browser_action' | 'page_action';
+      const popupEntrypoint = (type?: ActionType) =>
+        fakePopupEntrypoint({
+          options: {
+            // @ts-expect-error: Force this to be undefined instead of inheriting the random value
+            mv2Key: type ?? null,
+            defaultIcon: {
+              '16': '/icon/16.png',
+            },
+            defaultTitle: 'Default Iitle',
+          },
+          outputDir: outDir,
+        });
+
+      it('should include an action for mv3', async () => {
+        const popup = popupEntrypoint();
+        const buildOutput = fakeBuildOutput();
+        const config = fakeInternalConfig({
+          manifestVersion: 3,
+          outDir,
+        });
+        const expected: Partial<Manifest.WebExtensionManifest> = {
+          action: {
+            default_icon: popup.options.defaultIcon,
+            default_title: popup.options.defaultTitle,
+            default_popup: 'popup.html',
+          },
+        };
+
+        const actual = await generateManifest([popup], buildOutput, config);
+
+        expect(actual).toMatchObject(expected);
+      });
+
+      it.each<{
+        inputType: ActionType | undefined;
+        expectedType: ActionType;
+      }>([
+        { inputType: undefined, expectedType: 'browser_action' },
+        { inputType: 'browser_action', expectedType: 'browser_action' },
+        { inputType: 'page_action', expectedType: 'page_action' },
+      ])(
+        'should use the correct action for mv2: %j',
+        async ({ inputType, expectedType }) => {
+          const popup = popupEntrypoint(inputType);
+          const buildOutput = fakeBuildOutput();
+          const config = fakeInternalConfig({
+            manifestVersion: 2,
+            outDir,
+          });
+          const expected = {
+            default_icon: popup.options.defaultIcon,
+            default_title: popup.options.defaultTitle,
+            default_popup: 'popup.html',
+          };
+
+          const actual = await generateManifest([popup], buildOutput, config);
+
+          expect(actual[expectedType]).toEqual(expected);
+        },
+      );
+    });
+
+    describe('action without popup', () => {
+      it('should respect the action field in the manifest without a popup', async () => {
+        const buildOutput = fakeBuildOutput();
+        const config = fakeInternalConfig({
+          outDir,
+          manifest: {
+            action: {
+              default_icon: 'icon-16.png',
+              default_title: 'Example title',
+            },
+          },
+        });
+        const expected: Partial<Manifest.WebExtensionManifest> = {
+          action: config.manifest.action,
+        };
+
+        const actual = await generateManifest([], buildOutput, config);
+
+        expect(actual).toMatchObject(expected);
+      });
+    });
+
+    describe('options', () => {
+      const options = fakeOptionsEntrypoint({
+        outputDir: outDir,
+        options: {
+          openInTab: false,
+          chromeStyle: true,
+          browserStyle: true,
+        },
+      });
+
+      it('should include a options_ui and chrome_style for chrome', async () => {
+        const config = fakeInternalConfig({
+          manifestVersion: 3,
+          outDir,
+          browser: 'chrome',
+        });
+        const buildOutput = fakeBuildOutput();
+        const expected = {
+          open_in_tab: false,
+          chrome_style: true,
+          page: 'options.html',
+        };
+
+        const actual = await generateManifest([options], buildOutput, config);
+
+        expect(actual.options_ui).toEqual(expected);
+      });
+
+      it('should include a options_ui and browser_style for firefox', async () => {
+        const config = fakeInternalConfig({
+          manifestVersion: 3,
+          browser: 'firefox',
+          outDir,
+        });
+        const buildOutput = fakeBuildOutput();
+        const expected = {
+          open_in_tab: false,
+          browser_style: true,
+          page: 'options.html',
+        };
+
+        const actual = await generateManifest([options], buildOutput, config);
+
+        expect(actual.options_ui).toEqual(expected);
+      });
+    });
+
+    describe('background', () => {
+      const background = fakeBackgroundEntrypoint({
+        outputDir: outDir,
+        options: {
+          persistent: true,
+          type: 'module',
+        },
+      });
+
+      describe('MV3', () => {
+        it.each(['chrome', 'safari'])(
+          'should include a service worker and type for %s',
+          async (browser) => {
+            const config = fakeInternalConfig({
+              outDir,
+              manifestVersion: 3,
+              browser,
+            });
+            const buildOutput = fakeBuildOutput();
+            const expected = {
+              type: 'module',
+              service_worker: 'background.js',
+            };
+
+            const actual = await generateManifest(
+              [background],
+              buildOutput,
+              config,
+            );
+
+            expect(actual.background).toEqual(expected);
+          },
+        );
+
+        it('should include a background script and type for firefox', async () => {
+          const config = fakeInternalConfig({
+            outDir,
+            manifestVersion: 3,
+            browser: 'firefox',
+          });
+          const buildOutput = fakeBuildOutput();
+          const expected = {
+            type: 'module',
+            scripts: ['background.js'],
+          };
+
+          const actual = await generateManifest(
+            [background],
+            buildOutput,
+            config,
+          );
+
+          expect(actual.background).toEqual(expected);
+        });
+      });
+
+      describe('MV2', () => {
+        it.each(['chrome', 'safari'])(
+          'should include scripts and persistent for %s',
+          async (browser) => {
+            const config = fakeInternalConfig({
+              outDir,
+              manifestVersion: 2,
+              browser,
+            });
+            const buildOutput = fakeBuildOutput();
+            const expected = {
+              persistent: true,
+              scripts: ['background.js'],
+            };
+
+            const actual = await generateManifest(
+              [background],
+              buildOutput,
+              config,
+            );
+
+            expect(actual.background).toEqual(expected);
+          },
+        );
+
+        it('should include a background script and persistent for firefox mv2', async () => {
+          const config = fakeInternalConfig({
+            outDir,
+            manifestVersion: 2,
+            browser: 'firefox',
+          });
+          const buildOutput = fakeBuildOutput();
+          const expected = {
+            persistent: true,
+            scripts: ['background.js'],
+          };
+
+          const actual = await generateManifest(
+            [background],
+            buildOutput,
+            config,
+          );
+
+          expect(actual.background).toEqual(expected);
+        });
+      });
+    });
+
+    describe('icons', () => {
+      it('should auto-discover icons with the correct name', async () => {
+        const entrypoints = fakeArray(fakeEntrypoint);
+        const buildOutput = fakeBuildOutput({
+          publicAssets: [
+            { type: 'asset', fileName: 'icon-16.png' },
+            { type: 'asset', fileName: 'icon/32.png' },
+            { type: 'asset', fileName: 'icon@48w.png' },
+            { type: 'asset', fileName: 'icon-64x64.png' },
+            { type: 'asset', fileName: 'icon@96.png' },
+            { type: 'asset', fileName: 'icons/128x128.png' },
+          ],
+        });
+        const config = fakeInternalConfig();
+
+        const actual = await generateManifest(entrypoints, buildOutput, config);
+
+        expect(actual.icons).toEqual({
+          16: 'icon-16.png',
+          32: 'icon/32.png',
+          48: 'icon@48w.png',
+          64: 'icon-64x64.png',
+          96: 'icon@96.png',
+          128: 'icons/128x128.png',
+        });
+      });
+
+      it('should return undefined when no icons are found', async () => {
+        const entrypoints = fakeArray(fakeEntrypoint);
+        const buildOutput = fakeBuildOutput({
+          publicAssets: [
+            { type: 'asset', fileName: 'logo.png' },
+            { type: 'asset', fileName: 'icon-16.jpeg' },
+          ],
+        });
+        const config = fakeInternalConfig();
+
+        const actual = await generateManifest(entrypoints, buildOutput, config);
+
+        expect(actual.icons).toBeUndefined();
+      });
+
+      it('should allow icons to be overwritten from the wxt.config.ts file', async () => {
+        const entrypoints = fakeArray(fakeEntrypoint);
+        const buildOutput = fakeBuildOutput({
+          publicAssets: [
+            { type: 'asset', fileName: 'icon-16.png' },
+            { type: 'asset', fileName: 'icon-32.png' },
+            { type: 'asset', fileName: 'logo-16.png' },
+            { type: 'asset', fileName: 'logo-32.png' },
+            { type: 'asset', fileName: 'logo-48.png' },
+          ],
+        });
+        const expected = {
+          16: 'logo-16.png',
+          32: 'logo-32.png',
+          48: 'logo-48.png',
+        };
+        const config = fakeInternalConfig({
+          manifest: {
+            icons: expected,
+          },
+        });
+
+        const actual = await generateManifest(entrypoints, buildOutput, config);
+
+        expect(actual.icons).toEqual(expected);
+      });
+    });
+
+    describe('content_scripts', () => {
+      it('should group content scripts and styles together based on their manifest properties', async () => {
+        const cs1: ContentScriptEntrypoint = {
+          type: 'content-script',
+          name: 'one',
+          inputPath: 'entrypoints/one.content/index.ts',
+          outputDir: contentScriptOutDir,
+          options: {
+            matches: ['*://google.com/*'],
+          },
+        };
+        const cs1Styles: OutputAsset = {
+          type: 'asset',
+          fileName: 'content-scripts/one.css',
+        };
+        const cs2: ContentScriptEntrypoint = {
+          type: 'content-script',
+          name: 'two',
+          inputPath: 'entrypoints/two.content/index.ts',
+          outputDir: contentScriptOutDir,
+          options: {
+            matches: ['*://google.com/*'],
+            runAt: 'document_end',
+          },
+        };
+        const cs2Styles: OutputAsset = {
+          type: 'asset',
+          fileName: 'content-scripts/two.css',
+        };
+        const cs3: ContentScriptEntrypoint = {
+          type: 'content-script',
+          name: 'three',
+          inputPath: 'entrypoints/three.content/index.ts',
+          outputDir: contentScriptOutDir,
+          options: {
+            matches: ['*://google.com/*'],
+            runAt: 'document_end',
+          },
+        };
+        const cs3Styles: OutputAsset = {
+          type: 'asset',
+          fileName: 'content-scripts/three.css',
+        };
+        const cs4: ContentScriptEntrypoint = {
+          type: 'content-script',
+          name: 'four',
+          inputPath: 'entrypoints/four.content/index.ts',
+          outputDir: contentScriptOutDir,
+          options: {
+            matches: ['*://duckduckgo.com/*'],
+            runAt: 'document_end',
+          },
+        };
+        const cs4Styles: OutputAsset = {
+          type: 'asset',
+          fileName: 'content-scripts/four.css',
+        };
+        const cs5: ContentScriptEntrypoint = {
+          type: 'content-script',
+          name: 'five',
+          inputPath: 'entrypoints/five.content/index.ts',
+          outputDir: contentScriptOutDir,
+          options: {
+            matches: ['*://google.com/*'],
+            world: 'MAIN',
+          },
+        };
+        const cs5Styles: OutputAsset = {
+          type: 'asset',
+          fileName: 'content-scripts/five.css',
+        };
+
+        const entrypoints = [cs1, cs2, cs3, cs4, cs5];
+        const config = fakeInternalConfig({
+          command: 'build',
+          outDir,
+          manifestVersion: 3,
+        });
+        const buildOutput: Omit<BuildOutput, 'manifest'> = {
+          publicAssets: [],
+          steps: [
+            { entrypoints: cs1, chunks: [cs1Styles] },
+            { entrypoints: cs2, chunks: [cs2Styles] },
+            { entrypoints: cs3, chunks: [cs3Styles] },
+            { entrypoints: cs4, chunks: [cs4Styles] },
+            { entrypoints: cs5, chunks: [cs5Styles] },
+          ],
+        };
+
+        const actual = await generateManifest(entrypoints, buildOutput, config);
+
+        expect(actual.content_scripts).toContainEqual({
+          matches: ['*://google.com/*'],
+          css: ['content-scripts/one.css'],
+          js: ['content-scripts/one.js'],
+        });
+        expect(actual.content_scripts).toContainEqual({
+          matches: ['*://google.com/*'],
+          run_at: 'document_end',
+          css: ['content-scripts/two.css', 'content-scripts/three.css'],
+          js: ['content-scripts/two.js', 'content-scripts/three.js'],
+        });
+        expect(actual.content_scripts).toContainEqual({
+          matches: ['*://duckduckgo.com/*'],
+          run_at: 'document_end',
+          css: ['content-scripts/four.css'],
+          js: ['content-scripts/four.js'],
+        });
+        expect(actual.content_scripts).toContainEqual({
+          matches: ['*://google.com/*'],
+          css: ['content-scripts/five.css'],
+          js: ['content-scripts/five.js'],
+          world: 'MAIN',
+        });
+      });
+
+      it('should merge any content scripts declared in wxt.config.ts', async () => {
+        const cs: ContentScriptEntrypoint = {
+          type: 'content-script',
+          name: 'one',
+          inputPath: 'entrypoints/one.content.ts',
+          outputDir: contentScriptOutDir,
+          options: {
+            matches: ['*://google.com/*'],
+          },
+        };
+        const generatedContentScript = {
+          matches: ['*://google.com/*'],
+          js: ['content-scripts/one.js'],
+        };
+        const userContentScript = {
+          css: ['content-scripts/two.css'],
+          matches: ['*://*.google.com/*'],
+        };
+
+        const entrypoints = [cs];
+        const buildOutput = fakeBuildOutput();
+        const config = fakeInternalConfig({
+          outDir,
+          command: 'build',
+          manifest: {
+            content_scripts: [userContentScript],
+          },
+        });
+
+        const actual = await generateManifest(entrypoints, buildOutput, config);
+
+        expect(actual.content_scripts).toContainEqual(userContentScript);
+        expect(actual.content_scripts).toContainEqual(generatedContentScript);
+      });
+
+      describe('cssInjectionMode', () => {
+        it.each([undefined, 'manifest'] as const)(
+          'should add a CSS entry when cssInjectionMode is %s',
+          async (cssInjectionMode) => {
+            const cs: ContentScriptEntrypoint = {
+              type: 'content-script',
+              name: 'one',
+              inputPath: 'entrypoints/one.content.ts',
+              outputDir: contentScriptOutDir,
+              options: {
+                matches: ['*://google.com/*'],
+                cssInjectionMode,
+              },
+            };
+            const styles: OutputAsset = {
+              type: 'asset',
+              fileName: 'content-scripts/one.css',
+            };
+
+            const entrypoints = [cs];
+            const buildOutput: Omit<BuildOutput, 'manifest'> = {
+              publicAssets: [],
+              steps: [{ entrypoints: cs, chunks: [styles] }],
+            };
+            const config = fakeInternalConfig({
+              outDir,
+              command: 'build',
+            });
+
+            const actual = await generateManifest(
+              entrypoints,
+              buildOutput,
+              config,
+            );
+
+            expect(actual.content_scripts).toEqual([
+              {
+                js: ['content-scripts/one.js'],
+                css: ['content-scripts/one.css'],
+                matches: ['*://google.com/*'],
+              },
+            ]);
+          },
+        );
+
+        it.each(['manual', 'ui'] as const)(
+          'should not add an entry for CSS when cssInjectionMode is %s',
+          async (cssInjectionMode) => {
+            const cs: ContentScriptEntrypoint = {
+              type: 'content-script',
+              name: 'one',
+              inputPath: 'entrypoints/one.content.ts',
+              outputDir: contentScriptOutDir,
+              options: {
+                matches: ['*://google.com/*'],
+                cssInjectionMode,
+              },
+            };
+            const styles: OutputAsset = {
+              type: 'asset',
+              fileName: 'content-scripts/one.css',
+            };
+
+            const entrypoints = [cs];
+            const buildOutput: Omit<BuildOutput, 'manifest'> = {
+              publicAssets: [],
+              steps: [{ entrypoints: cs, chunks: [styles] }],
+            };
+            const config = fakeInternalConfig({
+              outDir,
+              command: 'build',
+            });
+
+            const actual = await generateManifest(
+              entrypoints,
+              buildOutput,
+              config,
+            );
+
+            expect(actual.content_scripts).toEqual([
+              {
+                js: ['content-scripts/one.js'],
+                matches: ['*://google.com/*'],
+              },
+            ]);
+          },
+        );
+
+        it('should add CSS file to `web_accessible_resources` when cssInjectionMode is "ui" for MV3', async () => {
+          const cs: ContentScriptEntrypoint = {
+            type: 'content-script',
+            name: 'one',
+            inputPath: 'entrypoints/one.content.ts',
+            outputDir: contentScriptOutDir,
+            options: {
+              matches: ['*://google.com/*'],
+              cssInjectionMode: 'ui',
+            },
+          };
+          const styles: OutputAsset = {
+            type: 'asset',
+            fileName: 'content-scripts/one.css',
+          };
+
+          const entrypoints = [cs];
+          const buildOutput: Omit<BuildOutput, 'manifest'> = {
+            publicAssets: [],
+            steps: [{ entrypoints: cs, chunks: [styles] }],
+          };
+          const config = fakeInternalConfig({
+            outDir,
+            command: 'build',
+            manifestVersion: 3,
+          });
+
+          const actual = await generateManifest(
+            entrypoints,
+            buildOutput,
+            config,
+          );
+
+          expect(actual.web_accessible_resources).toEqual([
+            {
+              matches: ['*://google.com/*'],
+              resources: ['content-scripts/one.css'],
+            },
+          ]);
+        });
+
+        it('should add CSS file to `web_accessible_resources` when cssInjectionMode is "ui" for MV2', async () => {
+          const cs: ContentScriptEntrypoint = {
+            type: 'content-script',
+            name: 'one',
+            inputPath: 'entrypoints/one.content.ts',
+            outputDir: contentScriptOutDir,
+            options: {
+              matches: ['*://google.com/*'],
+              cssInjectionMode: 'ui',
+            },
+          };
+          const styles: OutputAsset = {
+            type: 'asset',
+            fileName: 'content-scripts/one.css',
+          };
+
+          const entrypoints = [cs];
+          const buildOutput: Omit<BuildOutput, 'manifest'> = {
+            publicAssets: [],
+            steps: [{ entrypoints: cs, chunks: [styles] }],
+          };
+          const config = fakeInternalConfig({
+            outDir,
+            command: 'build',
+            manifestVersion: 2,
+          });
+
+          const actual = await generateManifest(
+            entrypoints,
+            buildOutput,
+            config,
+          );
+
+          expect(actual.web_accessible_resources).toEqual([
+            'content-scripts/one.css',
+          ]);
+        });
+      });
+    });
+
+    describe('web_accessible_resources', () => {
+      it('should combine user defined resources and generated resources for MV3', async () => {
+        const cs: ContentScriptEntrypoint = {
+          type: 'content-script',
+          name: 'one',
+          inputPath: 'entrypoints/one.content.ts',
+          outputDir: contentScriptOutDir,
+          options: {
+            matches: ['*://google.com/*'],
+            cssInjectionMode: 'ui',
+          },
+        };
+        const styles: OutputAsset = {
+          type: 'asset',
+          fileName: 'content-scripts/one.css',
+        };
+
+        const entrypoints = [cs];
+        const buildOutput: Omit<BuildOutput, 'manifest'> = {
+          publicAssets: [],
+          steps: [{ entrypoints: cs, chunks: [styles] }],
+        };
+        const config = fakeInternalConfig({
+          outDir,
+          command: 'build',
+          manifestVersion: 3,
+          manifest: {
+            web_accessible_resources: [
+              { resources: ['one.png'], matches: ['*://one.com/*'] },
+            ],
+          },
+        });
+
+        const actual = await generateManifest(entrypoints, buildOutput, config);
+
+        expect(actual.web_accessible_resources).toEqual([
+          { resources: ['one.png'], matches: ['*://one.com/*'] },
+          {
+            resources: ['content-scripts/one.css'],
+            matches: ['*://google.com/*'],
+          },
+        ]);
+      });
+
+      it('should combine user defined resources and generated resources for MV2', async () => {
+        const cs: ContentScriptEntrypoint = {
+          type: 'content-script',
+          name: 'one',
+          inputPath: 'entrypoints/one.content.ts',
+          outputDir: contentScriptOutDir,
+          options: {
+            matches: ['*://google.com/*'],
+            cssInjectionMode: 'ui',
+          },
+        };
+        const styles: OutputAsset = {
+          type: 'asset',
+          fileName: 'content-scripts/one.css',
+        };
+
+        const entrypoints = [cs];
+        const buildOutput: Omit<BuildOutput, 'manifest'> = {
+          publicAssets: [],
+          steps: [{ entrypoints: cs, chunks: [styles] }],
+        };
+        const config = fakeInternalConfig({
+          outDir,
+          command: 'build',
+          manifestVersion: 2,
+          manifest: {
+            web_accessible_resources: ['one.png'],
+          },
+        });
+
+        const actual = await generateManifest(entrypoints, buildOutput, config);
+
+        expect(actual.web_accessible_resources).toEqual([
+          'one.png',
+          'content-scripts/one.css',
+        ]);
+      });
+    });
+
+    describe('transformManifest option', () => {
+      it("should call the transformManifest option after the manifest is generated, but before it's returned", async () => {
+        const entrypoints: Entrypoint[] = [];
+        const buildOutput = fakeBuildOutput();
+        const newAuthor = 'Custom Author';
+        const config = fakeInternalConfig({
+          transformManifest(manifest: any) {
+            manifest.author = newAuthor;
+          },
+        });
+        const expected = {
+          author: newAuthor,
+        };
+
+        const actual = await generateManifest(entrypoints, buildOutput, config);
+
+        expect(actual).toMatchObject(expected);
+      });
+    });
+
+    describe('version', () => {
+      it.each(['chrome', 'safari', 'edge'] as const)(
+        'should include version and version_name as is on %s',
+        async (browser) => {
+          const version = '1.0.0';
+          const versionName = '1.0.0-alpha1';
+          const entrypoints: Entrypoint[] = [];
+          const buildOutput = fakeBuildOutput();
+          const config = fakeInternalConfig({
+            browser,
+            manifest: {
+              version,
+              version_name: versionName,
+            },
+          });
+
+          const actual = await generateManifest(
+            entrypoints,
+            buildOutput,
+            config,
+          );
+
+          expect(actual.version).toBe(version);
+          expect(actual.version_name).toBe(versionName);
+        },
+      );
+
+      it.each(['firefox'] as const)(
+        'should not include a version_name on %s because it is unsupported',
+        async (browser) => {
+          const version = '1.0.0';
+          const versionName = '1.0.0-alpha1';
+          const entrypoints: Entrypoint[] = [];
+          const buildOutput = fakeBuildOutput();
+          const config = fakeInternalConfig({
+            browser,
+            manifest: {
+              version,
+              version_name: versionName,
+            },
+          });
+
+          const actual = await generateManifest(
+            entrypoints,
+            buildOutput,
+            config,
+          );
+
+          expect(actual.version).toBe(version);
+          expect(actual.version_name).toBeUndefined();
+        },
+      );
+
+      it.each(['chrome', 'firefox', 'safari', 'edge'])(
+        'should not include the version_name if it is equal to version',
+        async (browser) => {
+          const version = '1.0.0';
+          const entrypoints: Entrypoint[] = [];
+          const buildOutput = fakeBuildOutput();
+          const config = fakeInternalConfig({
+            browser,
+            manifest: {
+              version,
+              version_name: version,
+            },
+          });
+
+          const actual = await generateManifest(
+            entrypoints,
+            buildOutput,
+            config,
+          );
+
+          expect(actual.version).toBe(version);
+          expect(actual.version_name).toBeUndefined();
+        },
+      );
+
+      it('should log a warning if the version could not be detected', async () => {
+        const entrypoints: Entrypoint[] = [];
+        const buildOutput = fakeBuildOutput();
+        const config = fakeInternalConfig({
+          manifest: {
+            // @ts-ignore: Purposefully removing version from fake object
+            version: null,
+          },
+        });
+
+        const actual = await generateManifest(entrypoints, buildOutput, config);
+
+        expect(actual.version).toBe('0.0.0');
+        expect(actual.version_name).toBeUndefined();
+        expect(config.logger.warn).toBeCalledTimes(1);
+        expect(config.logger.warn).toBeCalledWith(
+          expect.stringContaining('Extension version not found'),
+        );
+      });
+    });
+
+    describe('commands', () => {
+      const reloadCommandName = 'wxt:reload-extension';
+      const reloadCommand = {
+        suggested_key: {
+          default: 'Ctrl+E',
+        },
+      };
+
+      it('should include a command for reloading the extension during development', async () => {
+        const config = fakeInternalConfig({ command: 'serve' });
+        const output = fakeBuildOutput();
+        const entrypoints = fakeArray(fakeEntrypoint);
+
+        const actual = await generateManifest(entrypoints, output, config);
+
+        expect(actual.commands).toMatchObject({
+          [reloadCommandName]: reloadCommand,
+        });
+      });
+
+      it('should not override any existing commands when adding the one to reload the extension', async () => {
+        const customCommandName = 'custom-command';
+        const customCommand = {
+          description: 'Some other command',
+          suggested_key: {
+            default: 'Ctrl+H',
+          },
+        };
+        const config = fakeInternalConfig({
+          command: 'serve',
+          manifest: {
+            commands: {
+              [customCommandName]: customCommand,
+            },
+          },
+        });
+        const output = fakeBuildOutput();
+        const entrypoints = fakeArray(fakeEntrypoint);
+
+        const actual = await generateManifest(entrypoints, output, config);
+
+        expect(actual.commands).toMatchObject({
+          [reloadCommandName]: reloadCommand,
+          [customCommandName]: customCommand,
+        });
+      });
+
+      it('should not include the command when building an extension', async () => {
+        const config = fakeInternalConfig({ command: 'build' });
+        const output = fakeBuildOutput();
+        const entrypoints = fakeArray(fakeEntrypoint);
+
+        const actual = await generateManifest(entrypoints, output, config);
+
+        expect(actual.commands).toBeUndefined();
+      });
+    });
+  });
+});

src/core/utils/building/generate-wxt-dir.ts

@@ -180,7 +180,7 @@ async function writeMainDeclarationFile(
     filePath,
     [
       '// Generated by wxt',
-      `/// <reference types="vite/client" />`,
+      `/// <reference types="wxt/vite-builder-env" />`,
       ...references.map(
         (ref) =>
           `/// <reference types="./${normalizePath(relative(dir, ref))}" />`,

src/core/utils/building/rebuild.ts

@@ -3,7 +3,7 @@ import { BuildOutput, EntrypointGroup, InternalConfig } from '~/types';
 import { findEntrypoints } from './find-entrypoints';
 import { generateTypesDir } from './generate-wxt-dir';
 import { buildEntrypoints } from './build-entrypoints';
-import { generateMainfest, writeManifest } from '~/core/utils/manifest';
+import { generateManifest, writeManifest } from '~/core/utils/manifest';
 
 /**
  * Given a configuration, list of entrypoints, and an existing, partial output, build the
@@ -41,7 +41,7 @@ export async function rebuild(
     publicAssets: [...existingOutput.publicAssets, ...newOutput.publicAssets],
   };
 
-  const newManifest = await generateMainfest(
+  const newManifest = await generateManifest(
     allEntrypoints,
     mergedOutput,
     config,

src/core/utils/manifest.ts

@@ -50,29 +50,41 @@ export async function writeManifest(
 /**
  * Generates the manifest based on the config and entrypoints.
  */
-export async function generateMainfest(
+export async function generateManifest(
   entrypoints: Entrypoint[],
   buildOutput: Omit<BuildOutput, 'manifest'>,
   config: InternalConfig,
 ): Promise<Manifest.WebExtensionManifest> {
   const pkg = await getPackageJson(config);
 
-  const versionName = config.manifest.version_name ?? pkg?.version;
-  const version = config.manifest.version ?? simplifyVersion(pkg?.version);
+  let versionName =
+    config.manifest.version_name ?? config.manifest.version ?? pkg?.version;
+  if (versionName == null) {
+    versionName = '0.0.0';
+    config.logger.warn(
+      'Extension version not found, defaulting to "0.0.0". Add a version to your `package.json` or `wxt.config.ts` file. For more details, see: https://wxt.dev/guide/manifest.html#version-and-version-name',
+    );
+  }
+  let version = config.manifest.version ?? simplifyVersion(versionName);
 
   const baseManifest: Manifest.WebExtensionManifest = {
     manifest_version: config.manifestVersion,
     name: pkg?.name,
     description: pkg?.description,
     version,
-    version_name:
-      // Firefox doesn't support version_name
-      config.browser === 'firefox' || versionName === version
-        ? undefined
-        : versionName,
     short_name: pkg?.shortName,
     icons: discoverIcons(buildOutput),
   };
+  if (config.command === 'serve') {
+    baseManifest.commands = {
+      'wxt:reload-extension': {
+        description: 'Reload the extension during development',
+        suggested_key: {
+          default: 'Ctrl+E',
+        },
+      },
+    };
+  }
   const userManifest = config.manifest;
 
   const manifest = defu(
@@ -80,6 +92,14 @@ export async function generateMainfest(
     baseManifest,
   ) as Manifest.WebExtensionManifest;
 
+  // Apply the final version fields after merging the user manifest
+  manifest.version = version;
+  manifest.version_name =
+    // Firefox doesn't support version_name
+    config.browser === 'firefox' || versionName === version
+      ? undefined
+      : versionName;
+
   addEntrypoints(manifest, entrypoints, buildOutput, config);
 
   if (config.command === 'serve') addDevModeCsp(manifest, config);

src/core/utils/testing/fake-objects.ts

@@ -17,6 +17,9 @@ import {
   OutputChunk,
   OutputFile,
   OutputAsset,
+  BuildOutput,
+  BuildStepOutput,
+  UserManifest,
 } from '~/types';
 import { mock } from 'vitest-mock-extended';
 
@@ -39,6 +42,16 @@ export function fakeDir(root = process.cwd()): string {
   return resolve(root, faker.string.alphanumeric());
 }
 
+export const fakeEntrypoint = () =>
+  faker.helpers.arrayElement([
+    fakePopupEntrypoint,
+    fakeGenericEntrypoint,
+    fakeOptionsEntrypoint,
+    fakeBackgroundEntrypoint,
+    fakeContentScriptEntrypoint,
+    fakeUnlistedScriptEntrypoint,
+  ])();
+
 export const fakeContentScriptEntrypoint =
   fakeObjectCreator<ContentScriptEntrypoint>(() => ({
     type: 'content-script',
@@ -65,8 +78,8 @@ export const fakeContentScriptEntrypoint =
 export const fakeBackgroundEntrypoint = fakeObjectCreator<BackgroundEntrypoint>(
   () => ({
     type: 'background',
-    inputPath: fakeFile('src'),
-    name: faker.string.alpha(),
+    inputPath: 'entrypoints/background.ts',
+    name: 'background',
     options: {
       persistent: faker.helpers.arrayElement([true, false, undefined]),
       type: faker.helpers.maybe(() => 'module'),
@@ -87,8 +100,8 @@ export const fakeUnlistedScriptEntrypoint =
 export const fakeOptionsEntrypoint = fakeObjectCreator<OptionsEntrypoint>(
   () => ({
     type: 'options',
-    inputPath: fakeFile('src'),
-    name: faker.string.alpha(),
+    inputPath: 'entrypoints/options.html',
+    name: 'options',
     outputDir: fakeDir('.output'),
     options: {
       browserStyle: faker.helpers.arrayElement([true, false, undefined]),
@@ -100,8 +113,8 @@ export const fakeOptionsEntrypoint = fakeObjectCreator<OptionsEntrypoint>(
 
 export const fakePopupEntrypoint = fakeObjectCreator<PopupEntrypoint>(() => ({
   type: 'popup',
-  inputPath: fakeFile('src'),
-  name: faker.string.alpha(),
+  inputPath: 'entrypoints/popup.html',
+  name: 'popup',
   outputDir: fakeDir('.output'),
   options: {
     defaultTitle: faker.helpers.arrayElement([
@@ -165,6 +178,11 @@ export const fakeManifest = fakeObjectCreator<Manifest.WebExtensionManifest>(
   }),
 );
 
+export const fakeUserManifest = fakeObjectCreator<UserManifest>(() => ({
+  name: faker.string.alphanumeric(),
+  version: `${faker.number.int()}.${faker.number.int()}.${faker.number.int()}`,
+}));
+
 export function fakeArray<T>(createItem: () => T, count = 3): T[] {
   const array: T[] = [];
   for (let i = 0; i < count; i++) {
@@ -187,7 +205,7 @@ export const fakeInternalConfig = fakeObjectCreator<InternalConfig>(() => {
     fsCache: mock<FsCache>(),
     imports: {},
     logger: mock(),
-    manifest: fakeManifest(),
+    manifest: fakeUserManifest(),
     manifestVersion,
     mode,
     outBaseDir: fakeDir(),
@@ -222,3 +240,14 @@ export const fakeInternalConfig = fakeObjectCreator<InternalConfig>(() => {
     builder: mock(),
   };
 });
+
+export const fakeBuildOutput = fakeObjectCreator<BuildOutput>(() => ({
+  manifest: fakeManifest(),
+  publicAssets: fakeArray(fakeOutputAsset),
+  steps: fakeArray(fakeBuildStepOutput),
+}));
+
+export const fakeBuildStepOutput = fakeObjectCreator<BuildStepOutput>(() => ({
+  chunks: fakeArray(fakeOutputChunk),
+  entrypoints: fakeArray(fakeEntrypoint),
+}));

src/storage.ts

@@ -1,118 +1,589 @@
 /**
+ * Simplfied storage APIs with support for versioned fields, snapshots, metadata, and item definitions.
+ *
+ * See [the guide](https://wxt.dev/guide/storage.html) for more information.
+ *
  * @module wxt/storage
  */
-import {
-  Driver,
-  WatchCallback,
-  createStorage,
-  defineDriver,
-  Storage,
-} from 'unstorage';
-import { browser, Storage as BrowserStorage } from '~/browser';
+import { Storage, browser } from '~/browser';
+import { dequal } from 'dequal/lite';
 
-export interface WebExtensionDriverOptions {
-  storageArea: 'sync' | 'local' | 'managed' | 'session';
-}
+export const storage = createStorage();
 
-export const webExtensionDriver: (opts: WebExtensionDriverOptions) => Driver =
-  defineDriver((opts) => {
-    const checkPermission = () => {
-      if (browser.storage == null)
-        throw Error(
-          "You must request the 'storage' permission to use webExtensionDriver",
-        );
-    };
-
-    const _storageListener: (
-      changes: BrowserStorage.StorageAreaSyncOnChangedChangesType,
-    ) => void = (changes) => {
-      Object.entries(changes).forEach(([key, { newValue }]) => {
-        _listeners.forEach((callback) => {
-          callback(newValue ? 'update' : 'remove', key);
-        });
-      });
-    };
-    const _listeners = new Set<WatchCallback>();
+function createStorage(): WxtStorage {
+  const drivers: Record<string, WxtStorageDriver> = {
+    local: createDriver('local'),
+    session: createDriver('session'),
+    sync: createDriver('sync'),
+    managed: createDriver('managed'),
+  };
+  const getDriver = (area: string) => {
+    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: string) => {
+    const deliminatorIndex = key.indexOf(':');
+    const driverArea = key.substring(0, deliminatorIndex);
+    const driverKey = key.substring(deliminatorIndex + 1);
+    if (driverKey == null)
+      throw Error(
+        `Storage key should be in the form of "area:key", but recieved "${key}"`,
+      );
 
     return {
-      name: 'web-extension:' + opts.storageArea,
-      async hasItem(key) {
-        checkPermission();
-        const res = await browser.storage[opts.storageArea].get(key);
-        return res[key] != null;
-      },
-      async getItem(key) {
-        checkPermission();
-        const res = await browser.storage[opts.storageArea].get(key);
-        return res[key] ?? null;
-      },
-      async getItems(items) {
-        checkPermission();
-        const res = await browser.storage[opts.storageArea].get(
-          items.map((item) => item.key),
+      driverArea,
+      driverKey,
+      driver: getDriver(driverArea),
+    };
+  };
+  const getMetaKey = (key: string) => key + '$';
+  const getValueOrDefault = (value: any, defaultValue: any) =>
+    value ?? defaultValue ?? 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 getValueOrDefault(res, 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));
+    const newFields = { ...existingFields };
+    Object.entries(properties).forEach(([key, value]) => {
+      if (value == null) {
+        delete newFields[key];
+      } else {
+        newFields[key] = value;
+      }
+    });
+    await driver.setItem(metaKey, newFields);
+  };
+  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<string, string[]>();
+      const keyToOptsMap = new Map<string, GetItemOptions<any> | undefined>();
+      keys.forEach((key) => {
+        let keyStr: string;
+        let opts: GetItemOptions<any> | undefined;
+        if (typeof key === 'string') {
+          keyStr = key;
+        } else {
+          keyStr = key.key;
+          opts = key.options;
+        }
+        const { driverArea, driverKey } = resolveKey(keyStr);
+        const keys = areaToKeyMap.get(driverArea) ?? [];
+        areaToKeyMap.set(driverArea, keys.concat(driverKey));
+        keyToOptsMap.set(keyStr, opts);
+      });
+
+      const results = await Promise.all(
+        Array.from(areaToKeyMap.entries()).map(async ([driverArea, keys]) => {
+          const driverResults = await drivers[driverArea].getItems(keys);
+          return driverResults.map((driverResult) => {
+            const key = `${driverArea}:${driverResult.key}`;
+            const value = getValueOrDefault(
+              driverResult.value,
+              keyToOptsMap.get(key)?.defaultValue,
+            );
+            return { key, value };
+          });
+        }),
+      );
+      return results.flat();
+    },
+    getMeta: async (key) => {
+      const { driver, driverKey } = resolveKey(key);
+      return await getMeta(driver, driverKey);
+    },
+    setItem: async (key, value) => {
+      const { driver, driverKey } = resolveKey(key);
+      await setItem(driver, driverKey, value);
+    },
+    setItems: async (values) => {
+      const areaToKeyValueMap = new Map<
+        string,
+        Array<{ key: string; value: any }>
+      >();
+      values.forEach(({ key, value }) => {
+        const { driverArea, driverKey } = resolveKey(key);
+        const values = areaToKeyValueMap.get(driverArea) ?? [];
+        areaToKeyValueMap.set(
+          driverArea,
+          values.concat({ key: driverKey, value }),
         );
-        return items.map((item) => ({
-          key: item.key,
-          value: res[item.key] ?? null,
-        }));
-      },
-      async setItem(key, value) {
-        checkPermission();
-        await browser.storage[opts.storageArea].set({ [key]: value ?? null });
-      },
-      async setItems(items) {
-        checkPermission();
-        const map = items.reduce<Record<string, any>>((map, item) => {
-          map[item.key] = item.value ?? null;
-          return map;
-        }, {});
-        await browser.storage[opts.storageArea].set(map);
-      },
-      async removeItem(key) {
-        checkPermission();
-        await browser.storage[opts.storageArea].remove(key);
-      },
-      async getKeys() {
-        checkPermission();
-        const all = await browser.storage[opts.storageArea].get();
-        return Object.keys(all);
-      },
-      async clear() {
-        checkPermission();
-        await browser.storage[opts.storageArea].clear();
-      },
-      watch(callback) {
-        checkPermission();
-        _listeners.add(callback);
-        if (_listeners.size === 1) {
-          browser.storage[opts.storageArea].onChanged.addListener(
-            _storageListener,
+      });
+      await Promise.all(
+        Array.from(areaToKeyValueMap.entries()).map(
+          async ([driverArea, values]) => {
+            const driver = getDriver(driverArea);
+            await driver.setItems(values);
+          },
+        ),
+      );
+    },
+    setMeta: async (key, properties) => {
+      const { driver, driverKey } = resolveKey(key);
+      await setMeta(driver, driverKey, properties);
+    },
+    removeItem: async (key, opts) => {
+      const { driver, driverKey } = resolveKey(key);
+      await removeItem(driver, driverKey, opts);
+    },
+    removeItems: async (keys) => {
+      const areaToKeysMap = new Map<string, string[]>();
+      keys.forEach((key) => {
+        let keyStr: string;
+        let opts: RemoveItemOptions | undefined;
+        if (typeof key === 'string') {
+          keyStr = key;
+        } else {
+          keyStr = key.key;
+          opts = key.options;
+        }
+        const { driverArea, driverKey } = resolveKey(keyStr);
+        const areaKeys = areaToKeysMap.get(driverArea) ?? [];
+        areaKeys.push(driverKey);
+        if (opts?.removeMeta) {
+          areaKeys.push(getMetaKey(driverKey));
+        }
+        areaToKeysMap.set(driverArea, areaKeys);
+      });
+
+      await Promise.all(
+        Array.from(areaToKeysMap.entries()).map(async ([driverArea, keys]) => {
+          const driver = getDriver(driverArea);
+          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) => {
+      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 runMigrations = async () => {
+        const [value, meta] = await Promise.all([
+          // TODO: Optimize with getItems
+          getItem(driver, driverKey, undefined),
+          getMeta(driver, driverKey),
+        ]);
+        if (value == null) return;
+
+        const currentVersion = meta.v ?? 1;
+        if (currentVersion > targetVersion) {
+          throw Error(
+            `[wxt/storage] Migration ignored for "${key}", version downgrade detected (${currentVersion} -> ${targetVersion})`,
           );
         }
 
-        return () => {
-          _listeners.delete(callback);
-          if (_listeners.size === 0) {
-            browser.storage[opts.storageArea].onChanged.removeListener(
-              _storageListener,
-            );
-          }
-        };
-      },
-    };
-  });
+        const migrationsToRun = Array.from(
+          { length: targetVersion - currentVersion },
+          (_, i) => currentVersion + i + 1,
+        );
+        let migratedValue = value;
+        for (const migrateToVersion of migrationsToRun) {
+          migratedValue =
+            (await migrations?.[migrateToVersion]?.(migratedValue)) ??
+            migratedValue;
+        }
+        await Promise.all([
+          // TODO: Optimize with `setItem`
+          setItem(driver, driverKey, migratedValue),
+          setMeta(driver, driverKey, { v: targetVersion }),
+        ]);
+      };
+      let _migrationsCompleted = runMigrations();
 
-function createWebExtensionStorage() {
-  const storage = createStorage();
-  storage.mount('local', webExtensionDriver({ storageArea: 'local' }));
-  storage.mount('session', webExtensionDriver({ storageArea: 'session' }));
-  storage.mount('sync', webExtensionDriver({ storageArea: 'sync' }));
-  storage.mount('managed', webExtensionDriver({ storageArea: 'managed' }));
+      return {
+        _migrationsCompleted,
+        getValue: () => getItem(driver, driverKey, opts),
+        getMeta: () => getMeta(driver, driverKey),
+        setValue: (value) => setItem(driver, driverKey, value),
+        setMeta: (properties) => setMeta(driver, driverKey, properties),
+        removeValue: (opts) => removeItem(driver, driverKey, opts),
+        removeMeta: (properties) => removeMeta(driver, driverKey, properties),
+        watch: (cb) => watch(driver, driverKey, cb),
+      };
+    },
+  };
   return storage;
 }
 
-export type StorageValue = null | string | number | boolean | object;
+function createDriver(
+  storageArea: 'local' | 'session' | 'sync' | 'managed',
+): WxtStorageDriver {
+  const getStorageArea = () => {
+    if (browser.storage == null)
+      throw Error(
+        "You must add the 'storage' permission to your manifest to use 'wxt/storage'",
+      );
 
-export const storage: Storage<StorageValue> = createWebExtensionStorage();
+    return browser.storage[storageArea];
+  };
+  const watchListeners = new Set<
+    (changes: Storage.StorageAreaOnChangedChangesType) => 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: Storage.StorageAreaOnChangedChangesType) => {
+        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 * from 'unstorage';
+export interface WxtStorage {
+  /**
+   * Get an item from storage, or return `null` if it doesn't exist.
+   *
+   * @example
+   * await storage.getItem<number>("local:installDate");
+   */
+  getItem<T>(key: string, opts?: GetItemOptions<T>): Promise<T | null>;
+  /**
+   * Get multiple items from storage. There is no guarentee of order in the returned array.
+   *
+   * @example
+   * await storage.getItems(["local:installDate", "session:someCounter"]);
+   */
+  getItems(
+    keys: Array<string | { key: string; options?: GetItemOptions<any> }>,
+  ): Promise<Array<{ key: string; 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: string): Promise<T>;
+  /**
+   * 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: string, 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: string; 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: string,
+    properties: T | null,
+  ): Promise<void>;
+  /**
+   * Removes an item from storage.
+   *
+   * @example
+   * await storage.removeItem("local:installDate");
+   */
+  removeItem(key: string, opts?: RemoveItemOptions): Promise<void>;
+  /**
+   * Remove a list of keys from storage.
+   */
+  removeItems(
+    keys: Array<string | { key: string; 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: string, properties?: string | string[]): Promise<void>;
+  /**
+   * Return all the items in storage.
+   */
+  snapshot(
+    base: string,
+    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 overritten.
+   */
+  restoreSnapshot(base: string, data: any): Promise<void>;
+  /**
+   * Watch for changes to a specific key in storage.
+   */
+  watch<T>(key: string, cb: WatchCallback<T>): Unwatch;
+  /**
+   * Remove all watch listeners.
+   */
+  unwatch(): void;
+  /**
+   * Define a constant with utilities for reading/writing to a single value in storage.
+   *
+   * @example
+   * export const installDate = storage.defineItem<number>("local:installDate");
+   */
+  defineItem<TValue, TMetadata extends Record<string, unknown> = {}>(
+    key: string,
+    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>): Unwatch;
+  unwatch(): void;
+}
+
+export interface WxtStorageItem<
+  TValue,
+  TMetadata extends Record<string, unknown>,
+> {
+  /**
+   * Get the latest value from storage.
+   */
+  getValue(): Promise<TValue>;
+  /**
+   * Get metadata.
+   */
+  getMeta(): Promise<NullablePartial<TMetadata>>;
+  /**
+   * Set the value in storage.
+   */
+  setValue(value: TValue | null): 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;
+}
+
+export interface GetItemOptions<T> {
+  /**
+   * Value returned from `getValue` when it would otherwise return null.
+   */
+  defaultValue?: 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> extends GetItemOptions<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>;
+}
+
+/**
+ * Same as `Partial`, but includes `| null`. It makes all the properties of an object optional and
+ * nullable.
+ */
+export 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 | null, oldValue: T | null) => void;
+/**
+ * Call to remove a watch listener
+ */
+export type Unwatch = () => void;

src/testing/wxt-vitest-plugin.ts

@@ -4,8 +4,7 @@ import {
   download,
   tsconfigPaths,
   globals,
-  webextensionPolyfillAlias,
-  webextensionPolyfillInlineDeps,
+  webextensionPolyfillMock,
 } from '../core/builders/vite/plugins';
 import { getInternalConfig } from '~/core/utils/building';
 import { InlineConfig } from '../types';
@@ -27,8 +26,7 @@ import { InlineConfig } from '../types';
  */
 export function WxtVitest(inlineConfig?: InlineConfig): vite.PluginOption {
   return getInternalConfig(inlineConfig ?? {}, 'serve').then((config) => [
-    webextensionPolyfillAlias(config),
-    webextensionPolyfillInlineDeps(),
+    webextensionPolyfillMock(config),
     unimport(config),
     globals(config),
     download(config),

src/virtual/background-entrypoint.ts

@@ -26,6 +26,12 @@ if (__COMMAND__ === 'serve') {
   } catch (err) {
     logger.error('Failed to setup web socket connection with dev server', err);
   }
+
+  browser.commands.onCommand.addListener((command) => {
+    if (command === 'wxt:reload-extension') {
+      browser.runtime.reload();
+    }
+  });
 }
 
 try {

src/vite-builder-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

templates/react/package.json

@@ -19,10 +19,10 @@
     "react-dom": "^18.2.0"
   },
   "devDependencies": {
-    "@types/react": "^18.2.14",
-    "@types/react-dom": "^18.2.6",
+    "@types/react": "^18.2.46",
+    "@types/react-dom": "^18.2.18",
     "@vitejs/plugin-react": "^4.2.1",
-    "typescript": "^5.3.2",
-    "wxt": "^0.12.0"
+    "typescript": "^5.3.3",
+    "wxt": "^0.13.0"
   }
 }

templates/solid/package.json

@@ -15,11 +15,11 @@
     "postinstall": "wxt prepare"
   },
   "dependencies": {
-    "solid-js": "^1.7.8"
+    "solid-js": "^1.8.7"
   },
   "devDependencies": {
-    "typescript": "^5.3.2",
+    "typescript": "^5.3.3",
     "vite-plugin-solid": "^2.8.0",
-    "wxt": "^0.12.0"
+    "wxt": "^0.13.0"
   }
 }

templates/svelte/package.json

@@ -14,12 +14,12 @@
     "postinstall": "wxt prepare"
   },
   "devDependencies": {
-    "@sveltejs/vite-plugin-svelte": "^3.0.0",
-    "@tsconfig/svelte": "^5.0.0",
-    "svelte": "^4.0.5",
-    "svelte-check": "^3.4.6",
-    "tslib": "^2.6.0",
-    "typescript": "^5.3.2",
-    "wxt": "^0.12.0"
+    "@sveltejs/vite-plugin-svelte": "^3.0.1",
+    "@tsconfig/svelte": "^5.0.2",
+    "svelte": "^4.2.8",
+    "svelte-check": "^3.6.2",
+    "tslib": "^2.6.2",
+    "typescript": "^5.3.3",
+    "wxt": "^0.13.0"
   }
 }

templates/vanilla/package.json

@@ -15,7 +15,7 @@
     "postinstall": "wxt prepare"
   },
   "devDependencies": {
-    "typescript": "^5.3.2",
-    "wxt": "^0.12.0"
+    "typescript": "^5.3.3",
+    "wxt": "^0.13.0"
   }
 }

templates/vue/package.json

@@ -15,12 +15,12 @@
     "postinstall": "wxt prepare"
   },
   "dependencies": {
-    "vue": "^3.3.4"
+    "vue": "^3.4.0"
   },
   "devDependencies": {
-    "@vitejs/plugin-vue": "^4.5.1",
-    "typescript": "^5.3.2",
-    "vue-tsc": "^1.8.25",
-    "wxt": "^0.12.0"
+    "@vitejs/plugin-vue": "^5.0.1",
+    "typescript": "^5.3.3",
+    "vue-tsc": "^1.8.27",
+    "wxt": "^0.13.0"
   }
 }