Bump version to alpha2

Fix tests
Bump version to 0.14.2-alpha1
2024-01-14 16:27:38 -06:00 · 2024-01-14 16:26:54 -06:00 · 2024-01-14 16:19:54 -06:00 · 2024-01-14 16:18:47 -06:00 · 2024-01-14 16:18:19 -06:00 · 2024-01-14 15:05:52 -06:00
143 changed files with 6269 additions and 3750 deletions
@@ -12,14 +12,22 @@ A clear and concise description of what the bug is.

 ### To Reproduce

-Upload a ZIP or share a link to a repo representing the minimal reproduction. **_If you don't upload a minimal reproduction, you bug report will be closed._**
+Share minimal reproduction. Examples of a minimal reproduction:

-Steps to reproduce the behavior:
+- PR with a failing test case
+- ZIP file containing a minimal WXT project (be sure to include your lockfile!!)

-1. Go to '...'
-2. Click on '....'
-3. Scroll down to '....'
-4. See error
+> **_⚠️ If you don't upload a minimal reproduction, your issue will be closed until a reproduction is added._**
+>
+> Why? https://antfu.me/posts/why-reproductions-are-required
+
+Steps to reproduce the bug using the reproduction:
+
+1. Install dependencies: `pnpm i`
+2. Start dev mode: `pnpm dev`
+3. Click this...
+4. Do that...
+5. Etc...

 ### Expected behavior

@@ -13,6 +13,12 @@ jobs:
      - uses: actions/checkout@v3
      - uses: ./.github/actions/setup
      - run: pnpm format:check
+  lint:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v3
+      - uses: ./.github/actions/setup
+      - run: pnpm lint
  type-check:
    runs-on: ubuntu-22.04
    steps:
@@ -54,7 +60,7 @@ jobs:
      matrix:
        template:
          - react
-          # - solid
+          - solid
          - svelte
          - vanilla
          - vue
@@ -1,5 +1,226 @@
 # Changelog

+## v0.14.1
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.14.0...v0.14.1)
+
+### 🩹 Fixes
+
+- Use `Alt+R`/`Opt+R` to reload extension during development ([b6ab7a9](https://github.com/wxt-dev/wxt/commit/b6ab7a9))
+
+## v0.14.0
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.13.5...v0.14.0)
+
+### 🚀 Enhancements
+
+- ⚠️  Refactor content script UI functions and add helper for "integrated" UIs ([#333](https://github.com/wxt-dev/wxt/pull/333))
+
+#### ⚠️ Breaking Changes
+
+`createContentScriptUi` and `createContentScriptIframe`, and some of their options, have been renamed:
+
+- `createContentScriptUi({ ... })` &rarr; `createShadowRootUi({ ... })`
+- `createContentScriptIframe({ ... })` &rarr; `createIframeUi({ ... })`
+- `type: "inline" | "overlay" | "modal"` has been changed to `position: "inline" | "overlay" | "modal"`
+- `onRemove` is now called ***before*** the UI is removed from the DOM, previously it was called after the UI was removed
+- `mount` option has been renamed to `onMount`, to better match the related option, `onRemove`.
+
+## v0.13.5
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.13.4...v0.13.5)
+
+### 🩹 Fixes
+
+- Strip path from `web_accessible_resources[0].matches` ([#332](https://github.com/wxt-dev/wxt/pull/332))
+
+### 📖 Documentation
+
+- Add section about customizing other browser options during development ([8683bd4](https://github.com/wxt-dev/wxt/commit/8683bd4))
+
+### 🏡 Chore
+
+- Update bug report template ([9a2cc18](https://github.com/wxt-dev/wxt/commit/9a2cc18))
+
+## v0.13.4
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.13.3...v0.13.4)
+
+### 🩹 Fixes
+
+- Disable minification during development ([b7cdf15](https://github.com/wxt-dev/wxt/commit/b7cdf15))
+
+### 🏡 Chore
+
+- Use `const` instead of `let` ([2770974](https://github.com/wxt-dev/wxt/commit/2770974))
+
+## 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)
+
+### 🚀 Enhancements
+
+- Support PNPM without hoisting dependencies ([#291](https://github.com/wxt-dev/wxt/pull/291))
+
+## v0.12.1
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.12.0...v0.12.1)
+
+### 🩹 Fixes
+
+- Upgrade `@webext-core/match-patterns` to `1.0.3` ([#289](https://github.com/wxt-dev/wxt/pull/289))
+- Fix `package.json` lint errors ([#290](https://github.com/wxt-dev/wxt/pull/290))
+
+### 🏡 Chore
+
+- Upgrade templates to `wxt@^0.12.0` ([#285](https://github.com/wxt-dev/wxt/pull/285))
+
+## v0.12.0
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.11.2...v0.12.0)
+
+### 🚀 Enhancements
+
+- ⚠️  Add support for "main world" content scripts ([#284](https://github.com/wxt-dev/wxt/pull/284))
+
+### 🩹 Fixes
+
+- Only use type imports for Vite ([#278](https://github.com/wxt-dev/wxt/pull/278))
+- Throw error when no entrypoints are found ([#283](https://github.com/wxt-dev/wxt/pull/283))
+
+### 📖 Documentation
+
+- Improve content script UI guide ([#272](https://github.com/wxt-dev/wxt/pull/272))
+- Fix dead links ([291d25b](https://github.com/wxt-dev/wxt/commit/291d25b))
+
+### 🏡 Chore
+
+- Convert WXT CLI to an ESM binary ([#279](https://github.com/wxt-dev/wxt/pull/279))
+
+#### ⚠️ Breaking Changes
+
+`defineContentScript` and `defineBackground` are now exported from `wxt/sandbox` instead of `wxt/client`. ([#284](https://github.com/wxt-dev/wxt/pull/284))
+
+- If you use auto-imports, no changes are required.
+- If you have disabled auto-imports, you'll need to manually update your import statements:
+   ```diff
+   - import { defineBackground, defineContentScript } from 'wxt/client';
+   + import { defineBackground, defineContentScript } from 'wxt/sandbox';
+   ```
+
+## v0.11.2
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.11.1...v0.11.2)
+
+### 🩹 Fixes
+
+- Discover `.js`, `.jsx`, and `.tsx` unlisted scripts correctly ([#274](https://github.com/wxt-dev/wxt/pull/274))
+- Improve duplicate entrypoint name detection and catch the error before loading their config ([#276](https://github.com/wxt-dev/wxt/pull/276))
+
+### 📖 Documentation
+
+- Improve content script UI docs ([#268](https://github.com/wxt-dev/wxt/pull/268))
+
+### 🏡 Chore
+
+- Update sSolid template to vite 5 ([#265](https://github.com/wxt-dev/wxt/pull/265))
+- Add missing navigation item ([bcb93af](https://github.com/wxt-dev/wxt/commit/bcb93af))
+
 ## v0.11.1

 [compare changes](https://github.com/wxt-dev/wxt/compare/v0.11.0...v0.11.1)
@@ -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">
@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-require('../dist/cli.cjs');
@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/cli.js';
@@ -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:*"
  }
@@ -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();
+  });
 });
@@ -1,5 +1,3 @@
-import messages from 'public/_locales/en/messages.json';
-
 export default defineBackground(() => {
  console.log(browser.runtime.id);
  logId();
@@ -8,20 +6,32 @@ export default defineBackground(() => {
    chrome: __IS_CHROME__,
    firefox: __IS_FIREFOX__,
    manifestVersion: __MANIFEST_VERSION__,
-    messages,
  });

  // @ts-expect-error: should only accept entrypoints or public assets
  browser.runtime.getURL('/');
  browser.runtime.getURL('/background.js');
-  browser.runtime.getURL('/icon/128.png');
+  browser.runtime.getURL('/icon-128.png');

-  // @ts-expect-error: should only accept known message names
-  browser.i18n.getMessage('test');
-  browser.i18n.getMessage('prompt_for_name');
-  browser.i18n.getMessage('hello', 'Aaron');
-  browser.i18n.getMessage('bye', ['Aaron']);
-  browser.i18n.getMessage('@@extension_id');
+  console.log([
+    // @ts-expect-error: browser.i18n should only accept known message names
+    browser.i18n.getMessage('test'),
+    browser.i18n.getMessage('promptForName'),
+    browser.i18n.getMessage('hello', ['Aaron']),
+    browser.i18n.getMessage('bye', ['Aaron']),
+    browser.i18n.getMessage('@@extension_id'),
+    browser.i18n.getMessage('nItems'),
+  ]);
+
+  console.log([
+    // @ts-expect-error: i18n should only accept known message names
+    i18n.t('test'),
+    i18n.t('promptForName'),
+    i18n.t('hello', ['Aaron']),
+    i18n.t('bye', ['Aaron']),
+    i18n.t('@@extension_id'),
+    i18n.tp('nItems', 0, ['0']),
+  ]);

  console.log('WXT MODE:', {
    MODE: import.meta.env.MODE,
@@ -2,9 +2,9 @@ export default defineContentScript({
  matches: ['*://*.google.com/*'],

  main(ctx) {
-    const ui = createContentScriptIframe(ctx, {
+    const ui = createIframeUi(ctx, {
      page: '/iframe-src.html',
-      type: 'overlay',
+      position: 'overlay',
      anchor: 'form[action="/search"]',
    });
    ui.mount();
@@ -0,0 +1,8 @@
+export default defineContentScript({
+  matches: ['*://*/*'],
+  world: 'MAIN',
+
+  main() {
+    console.log(`Hello from ${location.hostname}!`);
+  },
+});
@@ -6,12 +6,12 @@ export default defineContentScript({
  cssInjectionMode: 'ui',

  async main(ctx) {
-    const ui = await createContentScriptUi(ctx, {
+    const ui = await createShadowRootUi(ctx, {
      name: 'demo-ui',
-      type: 'inline',
+      position: 'inline',
      append: 'before',
      anchor: 'form[role=search]',
-      mount: (container) => {
+      onMount: (container) => {
        const app = document.createElement('div');
        app.textContent = 'Custom content script UI';
        container.append(app);
@@ -0,0 +1,21 @@
+promptForName: What's your name?
+hello:
+  message: Hello, $USER$
+  description: Greet the user
+  placeholders:
+    user:
+      content: $1
+      example: Paul
+bye:
+  message: Goodbye, $USER$. Come back to $OUR_SITE$ soon!
+  description: Say goodbye to the user
+  placeholders:
+    our_site:
+      content: Example.com
+    user:
+      content: $1
+      example: Paul
+nItems:
+  0: 0 items
+  1: 1 item
+  n: $1 items
@@ -1,29 +0,0 @@
-{
-  "prompt_for_name": {
-    "message": "What's your name?",
-    "description": "Ask for the user's name"
-  },
-  "hello": {
-    "message": "Hello, $USER$",
-    "description": "Greet the user",
-    "placeholders": {
-      "user": {
-        "content": "$1",
-        "example": "Cira"
-      }
-    }
-  },
-  "bye": {
-    "message": "Goodbye, $USER$. Come back to $OUR_SITE$ soon!",
-    "description": "Say goodbye to the user",
-    "placeholders": {
-      "our_site": {
-        "content": "Example.com"
-      },
-      "user": {
-        "content": "$1",
-        "example": "Cira"
-      }
-    }
-  }
-}
@@ -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>
@@ -5,13 +5,18 @@ 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
  'bfbnagnphiehemkdgmmficmjfddgfhpl', // UltraWideo
  'elfaihghhjjoknimpccccmkioofjjfkf', // StayFree - Website Blocker & Web Analytics
  'okifoaikfmpfcamplcfjkpdnhfodpkil', // Doozy: Ai Made Easy
-  'lknmjhcajhfbbglglccadlfdjbaiifig' // tl;dv - Record, Transcribe & ChatGPT for Google Meet
+  '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);
 });

@@ -84,17 +84,19 @@ 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: 'Localization', link: '/guide/localization.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' },
          ],
        },
        {
@@ -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);
  },
 };
@@ -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
@@ -138,198 +138,4 @@ export default defineContentScript({
 });
 ```

-## UI
-
-WXT provides a utility function, `createContentScriptUi` to simplify mounting a UI from a content script. Internally, it uses the `ShadowRoot` API to isolate your CSS from the webpages.
-
-`createContentScriptUi` requires a `ContentScriptContext` so that when the context is invalidated, the UI is automatically removed from the webpage.
-
-:::details When to use `createContentScriptUi`
-You should only use `createContentScriptUi` if you want your UI's styles isolated from the webpages. If you want to create a more "integrated" UI that uses the page's styles, you can just use the regular JS API's to append your UI to the page.
-
-```ts
-const ui = document.createElement('div');
-const anchor = document.querySelector('#anchor-selector');
-anchor.append(ui);
-```
-
-You can try out [`createContentScriptIframe`](#createcontentscriptiframe) as an alternative solution
-
-:::
-
-### Usage
-
-To use `createContentScriptUi`, follow these steps:
-
-1. Import your CSS file at the top of your content script
-2. Set `cssInjectionMode: "ui"` inside `defineContentScript`
-3. Call `createContentScriptUi`
-4. Call `mount` to add the UI to the webpage
-
-Here's a basic example:
-
-```ts
-// entrypoints/ui.content/index.ts
-import './style.css';
-
-export default defineContentScript({
-  // ...
-  cssInjectionMode: 'ui',
-
-  async main(ctx) {
-    const ui = await createContentScriptUi(ctx, {
-      name: 'example-ui',
-      type: 'inline',
-      anchor: '#some-element',
-      append: 'after',
-      mount(container) {
-        // Mount UI inside `container`...
-      },
-    });
-
-    // You must call `mount` to add the UI to the page.
-    ui.mount();
-  },
-});
-```
-
-If you're using a frontend framework, you'll also need to include an `onRemoved` callback:
-
-:::code-group
-
-```ts [Vue]
-import { createApp } from 'vue';
-
-createContentScriptUi(ctx, {
-  // ...
-  mount(container) {
-    // Create a new app and mount it inside the container
-    const app = createApp(...);
-    app.mount(container);
-    return app;
-  },
-  onRemove(app) {
-    // When the UI is removed from the DOM, call unmount to stop the app
-    app.unmount();
-  },
-});
-```
-
-```ts [React]
-import ReactDOM from 'react-dom/client';
-
-createContentScriptUi(ctx, {
-  // ...
-  mount(container) {
-    // Create a root using the container and render your app
-    const root = ReactDOM.createRoot(container);
-    root.render(...);
-    return root;
-  },
-  onRemove(root) {
-    // When the UI is removed from the DOM, call unmount to stop the app
-    root.unmount();
-  },
-});
-```
-
-```ts [Svelte]
-import App from './App.svelte';
-
-createContentScriptUi(ctx, {
-  // ...
-  mount(container) {
-    // Mount your app component inside the container
-    return new App({
-      target: container,
-    });
-  },
-  onRemove(app) {
-    // When the UI is removed from the DOM, call $destroy to stop the app
-    app.$destroy();
-  },
-});
-```
-
-```ts [Solid]
-import { render } from 'solid-js/web';
-
-createContentScriptUi(ctx, {
-  // ...
-  mount(container) {
-    // Render your app component into the container
-    return render(() => ..., container)
-  },
-  onRemove(unmount) {
-    // When the UI is removed from the DOM, call unmount to stop the app
-    unmount();
-  },
-});
-```
-
-:::
-
-### `anchor`
-
-The anchor dictates where the UI will be mounted.
-
-### `append`
-
-Customize where the UI get's appended to the DOM, relative to the `anchor` element.
-
-### `type`
-
-There are 3 types of UI's you can mount.
-
- `inline`: Shows up inline based on the `anchor` and `append` options
- `overlay`: Shows up inline, but styled to be 0px by 0px, with overflow visible. This causes the UI to overlay on top of the webpage's content
- `modal`: A fullscreen overlay that covers the entire screen, regardless of where it's anchored.
-
-> TODO: Add visualization of the different UI types.
-
-### Overlay `alignment`
-
-Because the overlay UI type results in a 0px by 0px container being added to the webpage, the `alignment` option allows you to configure which corner of your UI is aligned with the 0x0 element.
-
-> TODO: Add visualization of the different alignments.
-
-## IFrame
-
-WXT provides a utility function, `createContentScriptIframe` to simplify mounting a UI from a content script. It creates an iframe to an unlisted HTML page. Unlike `createContentScriptUi`, this API support HMR.
-
-`createContentScriptIframe` requires a `ContentScriptContext` so that when the context is invalidated, the UI is automatically removed from the webpage.
-
-### Usage
-
-To use `createContentScriptIframe`, follow these steps:
-
-1. Create an unlisted HTML page that will be loaded into your iframe
-1. Add unlisted page to the manifest's `web_accessible_resouces`
-1. Call `createContentScriptUi`
-1. Call `mount` to add the UI to the webpage
-
-Here's a basic example:
-
-```ts
-export default defineContentScript({
-  // ...
-
-  async main(ctx) {
-    const ui = await createContentScriptIframe(ctx, {
-      page: '/your-unlisted-page.html',
-      type: 'inline',
-      anchor: '#some-element',
-      append: 'after',
-    });
-
-    // You must call `mount` to add the UI to the page.
-    ui.mount();
-  },
-});
-```
-
-The options, other than `page`, are the same as [`createContentScriptUi`](#anchor).
-
-### `page`
-
-The HTML page you want to load inside the iframe. This string will be passed into `browser.runtime.getURL` to resolve the full path of to your HTML page.
+See [Content Script UI](/guide/content-script-ui) for more info on creating UIs and including CSS in content scripts.
@@ -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" />
@@ -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` '],
  ]"
 />

@@ -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` '],
  ]"
 />

@@ -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

@@ -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.

@@ -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)
@@ -11,13 +11,15 @@ To setup your test environment for auto-imports, see [Testing](/guide/testing).
 Some WXT APIs can be used without importing them:

 - [`browser`](/api/wxt/browser/variables/browser) from `wxt/browser`, a small wrapper around `webextension-polyfill`
- [`defineContentScript`](/api/wxt/client/functions/defineContentScript) from `wxt/client`
- [`defineBackground`](/api/wxt/client/functions/defineBackground) from `wxt/client`
- [`createContentScriptUi`](/api/wxt/client/functions/createContentScriptUi) from `wxt/client`
+- [`defineContentScript`](/api/wxt/sandbox/functions/defineContentScript) from `wxt/sandbox`
+- [`defineBackground`](/api/wxt/sandbox/functions/defineBackground) from `wxt/sandbox`
 - [`defineUnlistedScript`](/api/wxt/sandbox/functions/defineUnlistedScript) from `wxt/sandbox`
+- [`createIntegratedUi`](/api/wxt/client/functions/createIntegratedUi) from `wxt/client`
+- [`createShadowRootUi`](/api/wxt/client/functions/createShadowRootUi) from `wxt/client`
+- [`createIframeUi`](/api/wxt/client/functions/createIframeUi) from `wxt/client`
 - [`fakeBrowser`](/api/wxt/testing/variables/fakeBrowser) from `wxt/testing`

-And more. All `wxt/*` APIs can be used without imports.
+And more!

 ## Project Auto-imports

@@ -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.
+:::
@@ -0,0 +1,396 @@
+# Content Script UI
+
+There are three ways to mount a UI inside a content script:
+
+[[toc]]
+
+Each has their own set of advantages and disadvantages.
+
+| Method      | Isolated Styles |   Isolated Events   | HMR | Use page's context |
+| ----------- | :-------------: | :-----------------: | :-: | :----------------: |
+| Integrated  |       ❌        |         ❌          | ❌  |         ✅         |
+| Shadow Root |       ✅        | ✅ (off by default) | ❌  |         ✅         |
+| IFrame      |       ✅        |         ✅          | ✅  |         ❌         |
+
+## Integrated
+
+Integrated content script UIs are injected alongside the content of a page. This means that they are affected by CSS on that page.
+
+:::code-group
+
+```ts [Vanilla]
+// entrypoints/example-ui.content.ts
+export default defineContentScript({
+  main(ctx) {
+    const ui = createIntegratedUi(ctx, {
+      position: 'inline',
+      anchor: '#anchor',
+      onMount: (container) => {
+        // Append children to the container
+        const app = document.createElement('p');
+        app.textContent = '...';
+        container.append(app);
+      },
+    });
+
+    // Call mount to add the UI to the DOM
+    ui.mount();
+  },
+});
+```
+
+```ts [Vue]
+// entrypoints/example-ui.content/index.ts
+import { createApp } from 'vue';
+import App from './App.vue';
+
+export default defineContentScript({
+  main(ctx) {
+    const ui = createIntegratedUi(ctx, {
+      position: 'inline',
+      anchor: '#anchor',
+      onMount: (container) => {
+        // Create the app and mount it to the UI container
+        const app = createApp(App);
+        app.mount(container);
+        return app;
+      },
+      onRemove: (app) => {
+        // Unmount the app when the UI is removed
+        app.unmount();
+      },
+    });
+
+    // Call mount to add the UI to the DOM
+    ui.mount();
+  },
+});
+```
+
+```tsx [React]
+// entrypoints/example-ui.content/index.tsx
+import ReactDOM from 'react-dom/client';
+import App from './App.tsx';
+
+export default defineContentScript({
+  main(ctx) {
+    const ui = createIntegratedUi(ctx, {
+      position: 'inline',
+      anchor: '#anchor',
+      onMount: (container) => {
+        // Create a root on the UI container and render a component
+        const root = ReactDOM.createRoot(container);
+        root.render(<App />);
+        return root;
+      },
+      onRemove: (root) => {
+        // Unmount the root when the UI is removed
+        root.unmount();
+      },
+    });
+
+    // Call mount to add the UI to the DOM
+    ui.mount();
+  },
+});
+```
+
+```ts [Svelete]
+// entrypoints/example-ui.content/index.ts
+import App from './App.svelte';
+
+export default defineContentScript({
+  main(ctx) {
+    const ui = createIntegratedUi(ctx, {
+      position: 'inline',
+      anchor: '#anchor',
+      onMount: (container) => {
+        // Create the Svelte app inside the UI container
+        const app = new App({
+          target: container,
+        });
+        return app;
+      },
+      onRemove: (app) => {
+        // Destroy the app when the UI is removed
+        app.$destroy();
+      },
+    });
+
+    // Call mount to add the UI to the DOM
+    ui.mount();
+  },
+});
+```
+
+```tsx [Solid]
+// entrypoints/example-ui.content/index.ts
+import { render } from 'solid-js/web';
+
+export default defineContentScript({
+  main(ctx) {
+    const ui = createIntegratedUi(ctx, {
+      position: 'inline',
+      anchor: '#anchor',
+      onMount: (container) => {
+        // Render your app to the UI container
+        const unmount = render(() => <div>...</div>, container);
+      },
+      onRemove: (unmount) => {
+        // Unmount the app when the UI is removed
+        unmount();
+      },
+    });
+
+    // Call mount to add the UI to the DOM
+    ui.mount();
+  },
+});
+```
+
+:::
+
+See the [API Reference](/api/wxt/client/functions/createIntegratedUi) for the complete list of options.
+
+You can control how CSS is injected for an integrated content script UI with the [`cssInjectionMode`](/api/wxt/interfaces/ContentScriptBaseDefinition#cssinjectionmode) property. Usually, you'll want to leave it as `"manifest"`, the default, so the UI inherits its style from the website's CSS.
+
+## Shadow Root
+
+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's [`createShadowRootUi`](/api/wxt/client/functions/createShadowRootUi) 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 `createShadowRootUi`, follow these steps:
+
+1. Import your CSS file at the top of your content script
+2. Set [`cssInjectionMode: "ui"`](/api/wxt/interfaces/ContentScriptBaseDefinition#cssinjectionmode) inside `defineContentScript`
+3. Define your UI with `createShadowRootUi()`
+4. Mount the UI so it is visible to users
+
+:::code-group
+
+```ts [Vanilla]
+// 1. Import the style
+import './style.css';
+
+export default defineContentScript({
+  // 2. Set cssInjectionMode
+  cssInjectionMode: 'ui',
+
+  async main(ctx) {
+    // 3. Define your UI
+    const ui = await createShadowRootUi(ctx, {
+      name: 'example-ui',
+      anchor: '#anchor',
+      type: 'inline',
+      onMount(container) {
+        // Define how your UI will be mounted inside the container
+        const app = document.createElement('p');
+        app.textContent = 'Hello world!';
+        container.append(app);
+      },
+    });
+
+    // 4. Mount the UI
+    ui.mount();
+  },
+});
+```
+
+```ts [Vue]
+// 1. Import the style
+import './style.css';
+import { createApp } from 'vue';
+import App from './App.vue';
+
+export default defineContentScript({
+  // 2. Set cssInjectionMode
+  cssInjectionMode: 'ui',
+
+  async main(ctx) {
+    // 3. Define your UI
+    const ui = await createShadowRootUi(ctx, {
+      name: 'example-ui',
+      anchor: '#anchor',
+      type: 'inline',
+      onMount: (container) => {
+        // Define how your UI will be mounted inside the container
+        const app = createApp(App);
+        app.mount(container);
+        return app;
+      },
+      onRemove: (app) => {
+        // Unmount the app when the UI is removed
+        app.unmount();
+      },
+    });
+
+    // 4. Mount the UI
+    ui.mount();
+  },
+});
+```
+
+```tsx [React]
+// 1. Import the style
+import './style.css';
+import ReactDOM from 'react-dom/client';
+import App from './App.tsx';
+
+export default defineContentScript({
+  // 2. Set cssInjectionMode
+  cssInjectionMode: 'ui',
+
+  main(ctx) {
+    // 3. Define your UI
+    const ui = createIntegratedUi(ctx, {
+      position: 'inline',
+      anchor: '#anchor',
+      onMount: (container) => {
+        // Create a root on the UI container and render a component
+        const root = ReactDOM.createRoot(container);
+        root.render(<App />);
+        return root;
+      },
+      onRemove: (root) => {
+        // Unmount the root when the UI is removed
+        root.unmount();
+      },
+    });
+
+    // 4. Mount the UI
+    ui.mount();
+  },
+});
+```
+
+```ts [Svelete]
+// 1. Import the style
+import './style.css';
+import App from './App.svelte';
+
+export default defineContentScript({
+  // 2. Set cssInjectionMode
+  cssInjectionMode: 'ui',
+
+  main(ctx) {
+    // 3. Define your UI
+    const ui = createIntegratedUi(ctx, {
+      position: 'inline',
+      anchor: '#anchor',
+      onMount: (container) => {
+        // Create the Svelte app inside the UI container
+        const app = new App({
+          target: container,
+        });
+        return app;
+      },
+      onRemove: (app) => {
+        // Destroy the app when the UI is removed
+        app.$destroy();
+      },
+    });
+
+    // 4. Mount the UI
+    ui.mount();
+  },
+});
+```
+
+```tsx [Solid]
+// 1. Import the style
+import './style.css';
+import { render } from 'solid-js/web';
+
+export default defineContentScript({
+  // 2. Set cssInjectionMode
+  cssInjectionMode: 'ui',
+
+  main(ctx) {
+    // 3. Define your UI
+    const ui = createIntegratedUi(ctx, {
+      position: 'inline',
+      anchor: '#anchor',
+      onMount: (container) => {
+        // Render your app to the UI container
+        const unmount = render(() => <div>...</div>, container);
+      },
+      onRemove: (unmount) => {
+        // Unmount the app when the UI is removed
+        unmount();
+      },
+    });
+
+    // 4. Mount the UI
+    ui.mount();
+  },
+});
+```
+
+:::
+
+See the [API Reference](/api/wxt/client/functions/createShadowRootUi) for the complete list of options.
+
+:::info TailwindCSS
+`createShadowRootUi` supports TailwindCSS out of the box! When importing the styles, just import the main CSS file containing the `@tailwind` directives, and everything will just work :+1:.
+:::
+
+## IFrame
+
+If you don't need to run your UI in the same frame as the content script, you can use an IFrame to host your UI instead. Since an IFrame just hosts an HTML page, **_HMR is supported_**.
+
+WXT provides a helper function, [`createIframeUi`](/api/wxt/client/functions/createIframeUi), which simplifies setting up the IFrame.
+
+1. Create an HTML page that will be loaded into your IFrame
+   ```html
+   <!-- entrypoints/example-iframe.html -->
+   <!doctype html>
+   <html lang="en">
+     <head>
+       <meta charset="UTF-8" />
+       <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+       <title>Your Content Script IFrame</title>
+     </head>
+     <body>
+       <!-- ... -->
+     </body>
+   </html>
+   ```
+1. Add the page to the manifest's `web_accessible_resouces`
+   ```ts
+   // wxt.config.ts
+   export default defineConfig({
+     manifest: {
+       web_accessible_resources: [
+         {
+           resources: ['example-iframe.html'],
+           matches: [...],
+         },
+       ],
+     },
+   });
+   ```
+1. Create and mount the IFrame
+
+   ```ts
+   export default defineContentScript({
+     // ...
+     async main(ctx) {
+       // Define the UI
+       const ui = await createIframeUi(ctx, {
+         page: '/example-iframe.html',
+         anchor: '#anchor',
+         type: 'inline',
+         onMount: (wrapper, iframe) => {
+           // Add styles to the iframe like width
+           iframe.width = 123;
+         },
+       });
+
+       // Show UI to user
+       ui.mount();
+     },
+   });
+   ```
+
+See the [API Reference](/api/wxt/client/functions/createIframeUi) for the complete list of options.
@@ -39,6 +39,8 @@ export default defineRunnerConfig({

 :::

+### Browser Binaries
+
 `web-ext`'s browser discovery is very limitted. By default, it only guesses at where Chrome and Firefox are installed. If you've customized your install locations, you may need to tell `web-ext` where the binaries/executables are located using the [`binaries` option](/api/wxt/interfaces/ExtensionRunnerConfig#binaries). For other Chromium based browsers, like Edge or Opera, you'll need to explicitly list them in the `binaries` option as well, otherwise they will open in Chrome by default.

 ```ts
@@ -57,3 +59,30 @@ 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.
 :::
+
+### Other options
+
+You can customize other options as well, like startup URLs, profiles, or additional command line arguments:
+
+```ts
+// web-ext.config.ts
+import { defineRunnerConfig } from 'wxt';
+
+export default defineRunnerConfig({
+  startUrls: ['https://google.com', 'https://duckduckgo.com'],
+  chromiumProfile: '/path/to/profile/to/use',
+  chromiumArgs: ['--window-size=400x300'],
+});
+```
+
+For a full list of options, see the [API Reference](/api/wxt/interfaces/ExtensionRunnerConfig).
+
+## 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`.
+:::
@@ -0,0 +1,159 @@
+---
+outline: deep
+---
+
+# Localization
+
+WXT includes a util, [`i18n`](/api/wxt/i18n/), that provides a type-safe feature-rich alternative to `browser.i18n.getMessage`.
+
+It is available automatically when you create a messages file under the `locales/` directory, and add a `default_locale` to the manifest:
+
+```
+<srcDir>
+└─ locales/
+   ├─ en.json
+   ├─ es.json5
+   ├─ fr.yml
+   ├─ de.yaml
+   └─ ...
+```
+
+> You can use JSON, JSON5, or YAML formats.
+
+```ts
+// wxt.config.ts
+export default defineConfig({
+  manifest: {
+    default_locale: 'en',
+  },
+});
+```
+
+## Message File Format
+
+```yml
+# Use plain strings
+simpleMessage: Hello world!
+
+# Nest strings in objects
+popup:
+  overview:
+    title: Nested text
+
+# Plural form support
+items:
+  1: 1 item
+  n: $1 items
+# Optionally include a custom string for 0
+cartSize:
+  0: Empty
+  1: 1 item
+  n: $1 items
+
+# Or stick with the standard web extension format (with a message, description, and placeholders)
+manifestMessage:
+  message: $THIS$ is translated
+  description: This is not-translated, helps translators
+  placeholder:
+    this:
+      content: This
+```
+
+:::tip
+`locales/<code>.json` is 100% compatible with the standard web extension localization format (`_locales/<code>/messages.json`). If you have existing messages files, just move them into the `locales/` directory.
+:::
+
+## Usage
+
+`i18n` is auto-imported, but can be manually imported from `wxt/i18n`.
+
+```ts
+import { i18n } from 'wxt/i18n';
+```
+
+### Basic Usage
+
+You can access messages by their name:
+
+```yml
+helloWorld: Hello world!
+```
+
+```ts
+i18n.t('helloWorld'); // "Hello world!"
+```
+
+Nested messages are combined into one string using an `_`.
+
+```yml
+popup:
+  overview:
+    title: Hello world!
+```
+
+```ts
+i18n.t('popup_overview_title'); // "Hello world!"
+```
+
+If a message is in the standard web extension format, don't include a `_message`, even if it's nested.
+
+```yml
+helloWorld:
+  message: Hello world!
+  description: Some description
+popup:
+  overview:
+    title:
+      message: Nested Title
+```
+
+```ts
+i18n.t('helloWorld'); // "Hello world!"
+i18n.t('popup_overview_title'); // "Nested Title"
+```
+
+### Substitutions
+
+To insert a custom string into a translation, pass an array of values as the second parameter of the `i18n.t` function:
+
+```yml
+hello: Hello, $1, my name is $2.
+```
+
+```ts
+i18n.t('hello', ['Aaron', 'Mark']); // "Hello Aaron, my name is Mark."
+```
+
+### Plural Form
+
+When getting the translation for text with a plural form, use the `i18n.tp` function.
+
+```yml
+friends:
+  0: I have no friends.
+  1: I have a friend.
+  n: I have many friends.
+```
+
+```ts
+i18n.tp('friends', 0); // "I have no friends."
+i18n.tp('friends', 1); // "I have one friend."
+i18n.tp('friends', 2); // "I have many friends."
+```
+
+The first number is the `count`. It is what decides which form will be used.
+
+Substitutions are not required. But usually, a plural form will look something like this:
+
+```yml
+items:
+  1: 1 item
+  n: $1 items
+```
+
+```ts
+i18n.tp('items', 0, ['0']); // "0 items"
+i18n.tp('items', 1, ['1']); // "1 item"
+i18n.tp('items', 2, ['2']); // "2 items"
+i18n.tp('items', 3, ['3']); // "3 items"
+```
@@ -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" />
@@ -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:

@@ -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 ++]
+  },
+);
+```
+
 :::
@@ -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.
@@ -5,7 +5,8 @@
    "../src/browser.ts",
    "../src/sandbox",
    "../src/storage.ts",
-    "../src/testing"
+    "../src/testing",
+    "../src/i18n"
  ],
  "plugin": ["typedoc-plugin-markdown", "typedoc-vitepress-theme"],
  "out": "./api",
@@ -17,25 +17,19 @@ describe('Auto Imports', () => {
          export {}
          declare global {
            const ContentScriptContext: typeof import('wxt/client')['ContentScriptContext']
+            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/client')['defineBackground']
+            const createIframeUi: typeof import('wxt/client')['createIframeUi']
+            const createIntegratedUi: typeof import('wxt/client')['createIntegratedUi']
+            const createShadowRootUi: typeof import('wxt/client')['createShadowRootUi']
+            const defineBackground: typeof import('wxt/sandbox')['defineBackground']
            const defineConfig: typeof import('wxt')['defineConfig']
-            const defineContentScript: typeof import('wxt/client')['defineContentScript']
-            const defineDriver: typeof import('wxt/storage')['defineDriver']
+            const defineContentScript: typeof import('wxt/sandbox')['defineContentScript']
            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 i18n: typeof import('wxt/i18n')['i18n']
            const storage: typeof import('wxt/storage')['storage']
-            const webExtensionDriver: typeof import('wxt/storage')['webExtensionDriver']
          }
          "
        `);
@@ -52,7 +46,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" />
@@ -91,7 +85,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" />
@@ -1,552 +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('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('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('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(
-      '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 },
@@ -575,91 +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',
-        });
-
-        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',
-        });
-
-        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',
-        });
-
-        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.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",
-      }
-    `);
-  });
 });
@@ -7,13 +7,18 @@ describe('Output Directory Structure', () => {
    project.addFile('entrypoints/.DS_Store');
    project.addFile('entrypoints/.hidden1/index.html');
    project.addFile('entrypoints/.hidden2.html');
+    project.addFile('entrypoints/unlisted.html');

    await project.build();

    expect(await project.serializeOutput()).toMatchInlineSnapshot(`
      ".output/chrome-mv3/manifest.json
      ----------------------------------------
-      {"manifest_version":3,"name":"E2E Extension","description":"Example description","version":"0.0.0"}"
+      {"manifest_version":3,"name":"E2E Extension","description":"Example description","version":"0.0.0"}
+      ================================================================================
+      .output/chrome-mv3/unlisted.html
+      ----------------------------------------
+      "
    `);
  });

@@ -211,6 +216,7 @@ describe('Output Directory Structure', () => {

  it("should output to a custom directory when overriding 'outDir'", async () => {
    const project = new TestProject();
+    project.addFile('entrypoints/unlisted.html');
    project.setConfigFileConfig({
      outDir: 'dist',
    });
@@ -4,6 +4,7 @@ import { TestProject } from '../utils';
 describe('TypeScript Project', () => {
  it('should generate defined constants correctly', async () => {
    const project = new TestProject();
+    project.addFile('entrypoints/unlisted.html');

    await project.build();

@@ -58,8 +59,9 @@ describe('TypeScript Project', () => {

  it('should augment the types for browser.i18n.getMessage', async () => {
    const project = new TestProject();
+    project.addFile('entrypoints/unlisted.html');
    project.addFile(
-      'public/_locales/en/messages.json',
+      'locales/en.json',
      JSON.stringify({
        prompt_for_name: {
          message: "What's your name?",
@@ -117,6 +119,36 @@ describe('TypeScript Project', () => {
        }

        export interface WxtI18n extends I18n.Static {
+          /**
+           * Ask for the user's name
+           *
+           * "What's your name?"
+           */
+          getMessage(
+            messageName: "prompt_for_name",
+            substitutions?: string | string[],
+            options?: GetMessageOptions,
+          ): string;
+          /**
+           * Greet the user
+           *
+           * "Hello, $USER$"
+           */
+          getMessage(
+            messageName: "hello",
+            substitutions?: string | string[],
+            options?: GetMessageOptions,
+          ): string;
+          /**
+           * Say goodbye to the user
+           *
+           * "Goodbye, $USER$. Come back to $OUR_SITE$ soon!"
+           */
+          getMessage(
+            messageName: "bye",
+            substitutions?: string | string[],
+            options?: GetMessageOptions,
+          ): string;
          /**
           * The extension or app ID; you might use this string to construct URLs for resources inside the extension. Even unlocalized extensions can use this message.
      Note: You can't use this message in a manifest file.
@@ -129,7 +161,7 @@ describe('TypeScript Project', () => {
            options?: GetMessageOptions,
          ): string;
          /**
-           * 
+           * No message description.
           *
           * "<browser.i18n.getUiLocale()>"
           */
@@ -178,36 +210,25 @@ describe('TypeScript Project', () => {
            substitutions?: string | string[],
            options?: GetMessageOptions,
          ): string;
-          /**
-           * Ask for the user's name
-           *
-           * "What's your name?"
-           */
-          getMessage(
-            messageName: "prompt_for_name",
-            substitutions?: string | string[],
-            options?: GetMessageOptions,
-          ): string;
-          /**
-           * Greet the user
-           *
-           * "Hello, $USER$"
-           */
-          getMessage(
-            messageName: "hello",
-            substitutions?: string | string[],
-            options?: GetMessageOptions,
-          ): string;
-          /**
-           * Say goodbye to the user
-           *
-           * "Goodbye, $USER$. Come back to $OUR_SITE$ soon!"
-           */
-          getMessage(
-            messageName: "bye",
-            substitutions?: string | string[],
-            options?: GetMessageOptions,
-          ): string;
+        }
+      }
+
+      declare module "wxt/i18n" {
+        export interface WxtMessageSchema {
+          t: {
+            "prompt_for_name": any;
+            "hello": any;
+            "bye": any;
+            "@@extension_id": any;
+            "@@ui_locale": any;
+            "@@bidi_dir": any;
+            "@@bidi_reversed_dir": any;
+            "@@bidi_start_edge": any;
+            "@@bidi_end_edge": any;
+          };
+          tp: {
+
+          };
        }
      }
      "
@@ -216,6 +237,7 @@ describe('TypeScript Project', () => {

  it('should reference all the required types in a single declaration file', async () => {
    const project = new TestProject();
+    project.addFile('entrypoints/unlisted.html');

    await project.build();

@@ -224,7 +246,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" />
@@ -235,6 +257,7 @@ describe('TypeScript Project', () => {

  it('should generate a TSConfig file for the project', async () => {
    const project = new TestProject();
+    project.addFile('entrypoints/unlisted.html');

    await project.build();

@@ -275,6 +298,7 @@ describe('TypeScript Project', () => {

  it('should generate correct path aliases for a custom srcDir', async () => {
    const project = new TestProject();
+    project.addFile('src/entrypoints/unlisted.html');
    project.setConfigFileConfig({
      srcDir: 'src',
    });
@@ -318,6 +342,7 @@ describe('TypeScript Project', () => {

  it('should add additional path aliases listed in the alias config, preventing defaults from being overridden', async () => {
    const project = new TestProject();
+    project.addFile('src/entrypoints/unlisted.html');
    project.setConfigFileConfig({
      srcDir: 'src',
      alias: {
@@ -61,6 +61,7 @@ describe('User Config', () => {

  it('should merge inline and user config based manifests', async () => {
    const project = new TestProject();
+    project.addFile('entrypoints/unlisted.html');
    project.addFile(
      'wxt.config.ts',
      `import { defineConfig } from 'wxt';
@@ -79,8 +80,8 @@ describe('User Config', () => {
      }),
    });

-    const output = await project.serializeOutput();
-    expect(output).toMatchInlineSnapshot(`
+    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","example_customization":["3","build","production","chrome"]}"
@@ -1,7 +1,7 @@
 {
  "name": "wxt",
  "type": "module",
-  "version": "0.11.1",
+  "version": "0.14.2-alpha2",
  "description": "Next gen framework for developing web extensions",
  "engines": {
    "node": ">=18",
@@ -30,47 +30,80 @@
    "bin",
    "dist"
  ],
-  "bin": "./bin/wxt.cjs",
+  "bin": "./bin/wxt.mjs",
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
-      "require": "./dist/index.cjs",
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
    },
    "./client": {
-      "import": "./dist/client.js",
-      "types": "./dist/client.d.ts"
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
    },
    "./sandbox": {
-      "import": "./dist/sandbox.js",
-      "types": "./dist/sandbox.d.ts"
+      "types": "./dist/sandbox.d.ts",
+      "import": "./dist/sandbox.js"
    },
    "./browser": {
-      "import": "./dist/browser.js",
-      "types": "./dist/browser.d.ts"
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/browser.js"
    },
    "./testing": {
-      "require": "./dist/testing.cjs",
-      "import": "./dist/testing.js",
-      "types": "./dist/testing.d.ts"
+      "import": {
+        "types": "./dist/testing.d.ts",
+        "default": "./dist/testing.js"
+      },
+      "require": {
+        "types": "./dist/testing.d.cts",
+        "default": "./dist/testing.cjs"
+      }
    },
    "./storage": {
-      "require": "./dist/storage.cjs",
-      "import": "./dist/storage.js",
-      "types": "./dist/storage.d.ts"
+      "import": {
+        "types": "./dist/storage.d.ts",
+        "default": "./dist/storage.js"
+      },
+      "require": {
+        "types": "./dist/storage.d.cts",
+        "default": "./dist/storage.cjs"
+      }
+    },
+    "./i18n": {
+      "import": {
+        "types": "./dist/i18n.d.ts",
+        "default": "./dist/i18n.js"
+      },
+      "require": {
+        "types": "./dist/i18n.d.cts",
+        "default": "./dist/i18n.cjs"
+      }
+    },
+    "./vite-builder-env": {
+      "types": "./dist/vite-builder-env.d.ts"
    }
  },
  "scripts": {
    "wxt": "tsx src/cli.ts",
    "build": "tsx scripts/build.ts",
    "format": "prettier --write .",
-    "format:check": "prettier --write .",
-    "compile": "tsc --noEmit",
+    "format:check": "prettier --check .",
+    "lint": "run-p -c -s lint:*",
+    "lint:eslint": "echo 'ESLint: TODO'",
+    "lint:package": "publint",
+    "compile": "run-s -c compile:*",
+    "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",
@@ -82,14 +115,15 @@
  "dependencies": {
    "@types/webextension-polyfill": "^0.10.5",
    "@webext-core/fake-browser": "^1.3.1",
-    "@webext-core/isolated-element": "^1.0.4",
-    "@webext-core/match-patterns": "^1.0.2",
+    "@webext-core/isolated-element": "^1.1.1",
+    "@webext-core/match-patterns": "^1.0.3",
    "async-mutex": "^0.4.0",
    "c12": "^1.5.1",
    "cac": "^6.7.14",
    "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",
@@ -108,10 +142,10 @@
    "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",
+    "yaml": "^2.3.4",
    "zip-dir": "^2.0.0"
  },
  "devDependencies": {
@@ -129,6 +163,7 @@
    "npm-run-all": "^4.1.5",
    "p-map": "^7.0.0",
    "prettier": "^3.1.0",
+    "publint": "^0.2.6",
    "simple-git-hooks": "^2.9.0",
    "tsup": "^8.0.1",
    "tsx": "^4.6.2",
@@ -136,8 +171,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"
  },
@@ -16,22 +16,22 @@ const startTime = Date.now();
 const outDir = 'dist';
 await fs.rm(path.join(outDir, '*'), { recursive: true, force: true });

-const preset: tsup.Options = {
+const preset = {
  dts: true,
  silent: true,
  sourcemap: false,
  external: [
-    'vite',
    'virtual:user-unlisted-script',
-    'virtual:user-content-script',
+    'virtual:user-content-script-isolated-world',
+    'virtual:user-content-script-main-world',
    'virtual:user-background',
  ],
-};
+} 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;
    },
@@ -58,6 +58,7 @@ const config: tsup.Options[] = [
      index: 'src/index.ts',
      testing: 'src/testing/index.ts',
      storage: 'src/storage.ts',
+      i18n: 'src/i18n/index.ts',
    },
    format: ['cjs', 'esm'],
    clean: true,
@@ -76,8 +77,10 @@ const config: tsup.Options[] = [
    ...preset,
    entry: {
      'virtual/background-entrypoint': 'src/virtual/background-entrypoint.ts',
-      'virtual/content-script-entrypoint':
-        'src/virtual/content-script-entrypoint.ts',
+      'virtual/content-script-isolated-world-entrypoint':
+        'src/virtual/content-script-isolated-world-entrypoint.ts',
+      'virtual/content-script-main-world-entrypoint':
+        'src/virtual/content-script-main-world-entrypoint.ts',
      'virtual/mock-browser': 'src/virtual/mock-browser.ts',
      'virtual/reload-html': 'src/virtual/reload-html.ts',
      'virtual/unlisted-script-entrypoint':
@@ -86,6 +89,7 @@ const config: tsup.Options[] = [
    format: ['esm'],
    splitting: false,
    dts: false,
+    external: [...preset.external, 'wxt'],
  },
  // CJS-only
  {
@@ -93,7 +97,7 @@ const config: tsup.Options[] = [
    entry: {
      cli: 'src/cli.ts',
    },
-    format: ['cjs'],
+    format: ['esm'],
  },
 ];

@@ -103,6 +107,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;
@@ -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();
+          });
        });
      });
    },
@@ -17,3 +17,65 @@ export interface WxtI18n extends I18n.Static {
 }

 export const browser: AugmentedBrowser = originalBrowser;
+
+// re-export all the types from webextension-polyfill
+// Because webextension-polyfill uses a weird namespace with "import export", there isn't a good way
+// to get these types without re-listing them.
+/** @ignore */
+export type {
+  ActivityLog,
+  Alarms,
+  Bookmarks,
+  Action,
+  BrowserAction,
+  BrowserSettings,
+  BrowsingData,
+  CaptivePortal,
+  Clipboard,
+  Commands,
+  ContentScripts,
+  ContextualIdentities,
+  Cookies,
+  DeclarativeNetRequest,
+  Devtools,
+  Dns,
+  Downloads,
+  Events,
+  Experiments,
+  Extension,
+  ExtensionTypes,
+  Find,
+  GeckoProfiler,
+  History,
+  I18n,
+  Identity,
+  Idle,
+  Management,
+  Manifest,
+  ContextMenus,
+  Menus,
+  NetworkStatus,
+  NormandyAddonStudy,
+  Notifications,
+  Omnibox,
+  PageAction,
+  Permissions,
+  Pkcs11,
+  Privacy,
+  Proxy,
+  Runtime,
+  Scripting,
+  Search,
+  Sessions,
+  SidebarAction,
+  Storage,
+  Tabs,
+  Theme,
+  TopSites,
+  Types,
+  Urlbar,
+  UserScripts,
+  WebNavigation,
+  WebRequest,
+  Windows,
+} from 'webextension-polyfill';
@@ -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);
@@ -1,214 +0,0 @@
-/** @vitest-environment happy-dom */
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { createContentScriptIframe } from '~/client/content-scripts/content-script-iframe';
-import { ContentScriptContext } from '~/client/content-scripts/content-script-context';
-
-const createCtx = () => new ContentScriptContext('test');
-
-const fetch = vi.fn();
-
-describe('createContentScriptIframe', () => {
-  beforeEach(() => {
-    document.body.innerHTML = `
-      <div id="parent">
-        <p id="one">one</p>
-        <p id="two">two</p>
-        <p id="three"></p>
-      </div>
-    `;
-
-    window.fetch = fetch;
-    fetch.mockResolvedValue({ text: () => Promise.resolve('') });
-  });
-
-  describe('mount', () => {
-    describe('append option', () => {
-      it.each([undefined, 'last' as const])(
-        'should append the element as the last child to the anchor when append=%s',
-        async (append) => {
-          const ui = await createContentScriptIframe(createCtx(), {
-            page: '/test.html',
-            type: 'inline',
-            anchor: '#parent',
-            append,
-          });
-          ui.mount();
-
-          expect(
-            document.querySelector('#parent > :nth-child(4)')?.tagName,
-          ).toEqual('DIV');
-        },
-      );
-
-      it('should append the element as the first child to the anchor when append=first', async () => {
-        const ui = await createContentScriptIframe(createCtx(), {
-          page: '/test.html',
-          type: 'inline',
-          anchor: '#parent',
-          append: 'first',
-        });
-        ui.mount();
-
-        expect(
-          document.querySelector('#parent > :nth-child(1)')?.tagName,
-        ).toEqual('DIV');
-      });
-
-      it('should append the element normally when append=first but there are no other children', async () => {
-        const ui = await createContentScriptIframe(createCtx(), {
-          page: '/test.html',
-          type: 'inline',
-          anchor: '#three',
-          append: 'first',
-        });
-        ui.mount();
-
-        expect(
-          document.querySelector('#three > :nth-child(1)')?.tagName,
-        ).toEqual('DIV');
-      });
-
-      it('should replace the anchor with the element when append=replace', async () => {
-        const ui = await createContentScriptIframe(createCtx(), {
-          page: '/test.html',
-          type: 'inline',
-          anchor: '#two',
-          append: 'replace',
-        });
-        ui.mount();
-
-        expect(
-          document.querySelector('#parent > :nth-child(2)')?.tagName,
-        ).toEqual('DIV');
-      });
-
-      it('should append the element after the anchor when append=before', async () => {
-        const ui = await createContentScriptIframe(createCtx(), {
-          page: '/test.html',
-          type: 'inline',
-          anchor: '#two',
-          append: 'before',
-        });
-        ui.mount();
-
-        expect(
-          document.querySelector('#parent > :nth-child(2)')?.tagName,
-        ).toEqual('DIV');
-      });
-
-      it('should append the element after the anchor when append=after', async () => {
-        const ui = await createContentScriptIframe(createCtx(), {
-          page: '/test.html',
-          type: 'inline',
-          anchor: '#two',
-          append: 'after',
-        });
-        ui.mount();
-
-        // Happy DOM doesn't work in this case, so we just make sure the element is added.
-        // expect(
-        //   document.querySelector('#parent > :nth-child(3)')?.tagName,
-        // ).toEqual('DIV');
-        expect(document.querySelector('DIV')).toBeDefined();
-      });
-
-      it('should apply a custom function', async () => {
-        const ui = await createContentScriptIframe(createCtx(), {
-          page: '/test.html',
-          type: 'inline',
-          anchor: '#three',
-          append: (anchor, ui) => anchor.replaceWith(ui),
-        });
-        ui.mount();
-
-        expect(
-          document.querySelector('#parent > :nth-child(3)')?.tagName,
-        ).toEqual('DIV');
-      });
-    });
-
-    it('should default the anchor to the body when unset', async () => {
-      const ui = await createContentScriptIframe(createCtx(), {
-        page: '/test.html',
-        type: 'inline',
-      });
-      ui.mount();
-
-      expect(document.querySelector('body > :nth-child(2)')?.tagName).toEqual(
-        'DIV',
-      );
-    });
-
-    it.each(['#four', () => document.querySelector('#four')])(
-      "should throw an error if the anchor doesn't exist",
-      async (anchor) => {
-        const ui = await createContentScriptIframe(createCtx(), {
-          page: '/test.html',
-          type: 'inline',
-          anchor,
-        });
-
-        expect(ui.mount).toThrow(
-          'Failed to mount content script UI: could not find anchor element',
-        );
-      },
-    );
-  });
-
-  describe('remove', () => {
-    it("should not fail if the ui hasn't been mounted", async () => {
-      const ui = await createContentScriptIframe(createCtx(), {
-        page: '/test.html',
-        type: 'inline',
-      });
-      ui.remove();
-    });
-
-    it('should automatically remove the UI when the context is invalidated', async () => {
-      const ctx = createCtx();
-      const ui = await createContentScriptIframe(ctx, {
-        page: '/test.html',
-        type: 'inline',
-      });
-      ui.mount();
-
-      expect(document.querySelector('.wxt-iframe-wrapper')).toBeDefined();
-
-      ctx.abort();
-      expect(document.querySelector('.wxt-iframe-wrapper')).toBeNull();
-    });
-  });
-
-  describe('type', () => {
-    it.each(['inline', 'overlay', 'modal'] as const)(
-      'should render type=%s',
-      async (type) => {
-        const ui = await createContentScriptIframe(createCtx(), {
-          page: '/test.html',
-          type,
-        });
-        ui.mount();
-
-        expect(document.querySelector('DIV')).toBeDefined();
-      },
-    );
-  });
-
-  describe('anchor', () => {
-    it.each([
-      () => '#two',
-      () => () => '#two',
-      () => document.querySelector('#two'),
-      () => () => document.querySelector('#two'),
-    ])('should render anchor=%s', async (getAnchor) => {
-      const ui = await createContentScriptIframe(createCtx(), {
-        page: '/test.html',
-        type: 'inline',
-        anchor: getAnchor(),
-      });
-      ui.mount();
-
-      expect(document.querySelector('DIV')).toBeDefined();
-    });
-  });
-});
@@ -1,335 +0,0 @@
-/** @vitest-environment happy-dom */
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { createContentScriptUi } from '~/client/content-scripts/content-script-ui';
-import { ContentScriptContext } from '~/client/content-scripts/content-script-context';
-import { createIsolatedElement } from '@webext-core/isolated-element';
-import { mock } from 'vitest-mock-extended';
-import { browser } from '~/browser';
-
-vi.mock('@webext-core/isolated-element', async () => {
-  const { vi } = await import('vitest');
-  return {
-    createIsolatedElement: vi.fn(),
-  };
-});
-const createIsolatedElementMock = vi.mocked(createIsolatedElement);
-
-const testApp = (container: Element) => {
-  const app = document.createElement('div');
-  app.textContent = 'App';
-  container.append(app);
-};
-
-const createCtx = () => new ContentScriptContext('test');
-
-const fetch = vi.fn();
-
-describe('createContentScriptUi', () => {
-  beforeEach(() => {
-    document.body.innerHTML = `
-      <div id="parent">
-        <p id="one">one</p>
-        <p id="two">two</p>
-        <p id="three"></p>
-      </div>
-    `;
-
-    window.fetch = fetch;
-    fetch.mockResolvedValue({ text: () => Promise.resolve('') });
-
-    createIsolatedElementMock.mockImplementation(async (config) => {
-      const parentElement = document.createElement(config.name);
-      const isolatedElement = document.createElement('html');
-      parentElement.append(isolatedElement);
-
-      return {
-        isolatedElement,
-        parentElement: parentElement,
-        shadow: mock<ShadowRoot>({
-          querySelector: (selector: string) => {
-            if (selector === 'html') return isolatedElement;
-          },
-        }),
-      };
-    });
-  });
-
-  describe('css', () => {
-    it('should load the CSS for the current entrypoint when cssInjectionMode=ui', async () => {
-      fetch.mockResolvedValue({ text: () => Promise.resolve('body {}') });
-      const ctx = new ContentScriptContext('test', {
-        matches: [],
-        cssInjectionMode: 'ui',
-      });
-
-      await createContentScriptUi(ctx, {
-        name: 'test',
-        type: 'inline',
-        mount: testApp,
-      });
-
-      expect(fetch).toBeCalledTimes(1);
-      expect(fetch).toBeCalledWith(
-        `chrome-extension://${browser.runtime.id}/content-scripts/${__ENTRYPOINT__}.css`,
-      );
-      expect(createIsolatedElementMock).toBeCalledTimes(1);
-      expect(createIsolatedElementMock).toBeCalledWith(
-        expect.objectContaining({
-          css: {
-            textContent: 'body {}',
-          },
-        }),
-      );
-    });
-
-    it('should still load the UI when fetch fails to load CSS file when cssInjectionMode=ui', async () => {
-      const error = Error('Test fetch error');
-      fetch.mockRejectedValue(error);
-      const ctx = new ContentScriptContext('test', {
-        matches: [],
-        cssInjectionMode: 'ui',
-      });
-
-      await createContentScriptUi(ctx, {
-        name: 'test',
-        type: 'inline',
-        mount: testApp,
-      });
-
-      expect(fetch).toBeCalledTimes(1);
-      expect(fetch).toBeCalledWith(
-        `chrome-extension://${browser.runtime.id}/content-scripts/${__ENTRYPOINT__}.css`,
-      );
-      expect(createIsolatedElementMock).toBeCalledTimes(1);
-      expect(createIsolatedElementMock).toBeCalledWith(
-        expect.objectContaining({
-          css: {
-            textContent: '',
-          },
-        }),
-      );
-    });
-
-    it.each(['manifest', 'manual'] as const)(
-      'should not fetch CSS when cssInjectionMode=%s',
-      async (cssInjectionMode) => {
-        const ctx = new ContentScriptContext('test', {
-          matches: [],
-          cssInjectionMode,
-        });
-
-        await createContentScriptUi(ctx, {
-          name: 'test',
-          type: 'inline',
-          mount: testApp,
-        });
-
-        expect(fetch).not.toBeCalled();
-      },
-    );
-  });
-
-  describe('mount', () => {
-    describe('append option', () => {
-      it.each([undefined, 'last' as const])(
-        'should append the element as the last child to the anchor when append=%s',
-        async (append) => {
-          const ui = await createContentScriptUi(createCtx(), {
-            name: 'test-app',
-            type: 'inline',
-            anchor: '#parent',
-            append,
-            mount: testApp,
-          });
-          ui.mount();
-
-          expect(
-            document.querySelector('#parent > :nth-child(4)')?.tagName,
-          ).toEqual('TEST-APP');
-        },
-      );
-
-      it('should append the element as the first child to the anchor when append=first', async () => {
-        const ui = await createContentScriptUi(createCtx(), {
-          name: 'test-app',
-          type: 'inline',
-          anchor: '#parent',
-          append: 'first',
-          mount: testApp,
-        });
-        ui.mount();
-
-        expect(
-          document.querySelector('#parent > :nth-child(1)')?.tagName,
-        ).toEqual('TEST-APP');
-      });
-
-      it('should append the element normally when append=first but there are no other children', async () => {
-        const ui = await createContentScriptUi(createCtx(), {
-          name: 'test-app',
-          type: 'inline',
-          anchor: '#three',
-          append: 'first',
-          mount: testApp,
-        });
-        ui.mount();
-
-        expect(
-          document.querySelector('#three > :nth-child(1)')?.tagName,
-        ).toEqual('TEST-APP');
-      });
-
-      it('should replace the anchor with the element when append=replace', async () => {
-        const ui = await createContentScriptUi(createCtx(), {
-          name: 'test-app',
-          type: 'inline',
-          anchor: '#two',
-          append: 'replace',
-          mount: testApp,
-        });
-        ui.mount();
-
-        expect(
-          document.querySelector('#parent > :nth-child(2)')?.tagName,
-        ).toEqual('TEST-APP');
-      });
-
-      it('should append the element after the anchor when append=before', async () => {
-        const ui = await createContentScriptUi(createCtx(), {
-          name: 'test-app',
-          type: 'inline',
-          anchor: '#two',
-          append: 'before',
-          mount: testApp,
-        });
-        ui.mount();
-
-        expect(
-          document.querySelector('#parent > :nth-child(2)')?.tagName,
-        ).toEqual('TEST-APP');
-      });
-
-      it('should append the element after the anchor when append=after', async () => {
-        const ui = await createContentScriptUi(createCtx(), {
-          name: 'test-app',
-          type: 'inline',
-          anchor: '#two',
-          append: 'after',
-          mount: testApp,
-        });
-        ui.mount();
-
-        // Happy DOM doesn't work in this case, so we just make sure the element is added.
-        // expect(
-        //   document.querySelector('#parent > :nth-child(3)')?.tagName,
-        // ).toEqual('TEST-APP');
-        expect(document.querySelector('test-app')).toBeDefined();
-      });
-
-      it('should apply a custom function', async () => {
-        const ui = await createContentScriptUi(createCtx(), {
-          name: 'test-app',
-          type: 'inline',
-          anchor: '#three',
-          append: (anchor, ui) => anchor.replaceWith(ui),
-          mount: testApp,
-        });
-        ui.mount();
-
-        expect(
-          document.querySelector('#parent > :nth-child(3)')?.tagName,
-        ).toEqual('TEST-APP');
-      });
-    });
-
-    it('should default the anchor to the body when unset', async () => {
-      const ui = await createContentScriptUi(createCtx(), {
-        name: 'test-app',
-        type: 'inline',
-        mount: testApp,
-      });
-      ui.mount();
-
-      expect(document.querySelector('body > :nth-child(2)')?.tagName).toEqual(
-        'TEST-APP',
-      );
-    });
-
-    it.each(['#four', () => document.querySelector('#four')])(
-      "should throw an error if the anchor doesn't exist",
-      async (anchor) => {
-        const ui = await createContentScriptUi(createCtx(), {
-          name: 'test',
-          type: 'inline',
-          anchor,
-          mount: testApp,
-        });
-
-        expect(ui.mount).toThrow(
-          'Failed to mount content script UI: could not find anchor element',
-        );
-      },
-    );
-  });
-
-  describe('remove', () => {
-    it("should not fail if the ui hasn't been mounted", async () => {
-      const ui = await createContentScriptUi(createCtx(), {
-        name: 'test-app',
-        type: 'inline',
-        mount: testApp,
-      });
-      ui.remove();
-    });
-
-    it('should automatically remove the UI when the context is invalidated', async () => {
-      const ctx = createCtx();
-      const ui = await createContentScriptUi(ctx, {
-        name: 'test-app',
-        type: 'inline',
-        mount: testApp,
-      });
-      ui.mount();
-
-      expect(document.querySelector('test-app')).toBeDefined();
-
-      ctx.abort();
-      expect(document.querySelector('test-app')).toBeNull();
-    });
-  });
-
-  describe('type', () => {
-    it.each(['inline', 'overlay', 'modal'] as const)(
-      'should render type=%s',
-      async (type) => {
-        const ui = await createContentScriptUi(createCtx(), {
-          name: 'test-app',
-          type,
-          mount: testApp,
-        });
-        ui.mount();
-
-        expect(document.querySelector('test-app')).toBeDefined();
-      },
-    );
-  });
-
-  describe('anchor', () => {
-    it.each([
-      () => '#two',
-      () => () => '#two',
-      () => document.querySelector('#two'),
-      () => () => document.querySelector('#two'),
-    ])('should render anchor=%s', async (getAnchor) => {
-      const ui = await createContentScriptUi(createCtx(), {
-        name: 'test-app',
-        type: 'inline',
-        anchor: getAnchor(),
-        mount: testApp,
-      });
-      ui.mount();
-
-      expect(document.querySelector('test-app')).toBeDefined();
-    });
-  });
-});
@@ -1,6 +1,6 @@
 import { ContentScriptDefinition } from '~/types';
 import { browser } from '~/browser';
-import { logger } from '~/client/utils/logger';
+import { logger } from '~/sandbox/utils/logger';
 import { WxtLocationChangeEvent, getUniqueEventName } from './custom-events';
 import { createLocationWatcher } from './location-watcher';

@@ -1,83 +0,0 @@
-import browser from 'webextension-polyfill';
-import {
-  ContentScriptAnchoredOptions,
-  ContentScriptPositioningOptions,
-  applyContentScriptUiPosition,
-  mountContentScriptUiRoot,
-} from '../utils/content-script-ui';
-import { ContentScriptContext } from './content-script-context';
-
-/**
- * Utility for mounting a content script UI inside an iframe. Automatically removed from the DOM
- * when the content script's context is invalidated.
- *
- * See https://wxt.dev/entrypoints/content-scripts.html#iframe for full documentation.
- *
- * @example
- * export default defineContentScript({
- *   matches: ["*://*.google.com/*"],
- *
- *   main(ctx) {
- *     const ui = await createContentScriptIframe(ctx, {
- *       page: "/content-script-overlay.html",
- *       type: "modal",
- *     })
- *     ui.mount();
- *   }
- * })
- */
-export function createContentScriptIframe(
-  ctx: ContentScriptContext,
-  options: ContentScriptIframeOptions,
-): ContentScriptIframe {
-  const wrapper = document.createElement('div');
-  wrapper.classList.add('wxt-iframe-wrapper');
-  const iframe = document.createElement('iframe');
-  iframe.src = browser.runtime.getURL(options.page);
-  wrapper.appendChild(iframe);
-
-  const mount = () => {
-    applyContentScriptUiPosition(wrapper, iframe, options);
-    mountContentScriptUiRoot(wrapper, options);
-  };
-
-  const remove = () => {
-    wrapper.remove();
-  };
-
-  ctx.onInvalidated(remove);
-
-  return {
-    iframe,
-    wrapper,
-    mount,
-    remove,
-  };
-}
-
-export interface ContentScriptIframe {
-  /**
-   * The iframe added to the DOM.
-   */
-  iframe: HTMLIFrameElement;
-  /**
-   * A wrapper div that assists in positioning.
-   */
-  wrapper: HTMLDivElement;
-  /**
-   * Function that mounts or remounts the UI on the page.
-   */
-  mount: () => void;
-  /**
-   * Function that removes the UI from the webpage.
-   */
-  remove: () => void;
-}
-
-export type ContentScriptIframeOptions = ContentScriptPositioningOptions &
-  ContentScriptAnchoredOptions & {
-    /**
-     * The path to the unlisted HTML file to display in the iframe.
-     */
-    page: import('wxt/browser').PublicPath;
-  };
@@ -1,173 +0,0 @@
-import { createIsolatedElement } from '@webext-core/isolated-element';
-import { browser } from '~/browser';
-import { logger } from '~/client/utils/logger';
-import { ContentScriptContext } from './content-script-context';
-import {
-  ContentScriptAnchoredOptions,
-  ContentScriptPositioningOptions,
-  applyContentScriptUiPosition,
-  mountContentScriptUiRoot,
-} 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.
- *
- * See https://wxt.dev/entrypoints/content-scripts.html#ui for full documentation.
- *
- * @example
- * // entrypoints/example-ui.content/index.ts
- * import "./style.css"
- *
- * export default defineContentScript({
- *   matches: ["*://*.google.com/*"],
- *   cssInjectionMode: "ui",
- *
- *   async main(ctx) {
- *     const ui = await createContentScriptUi(ctx, {
- *       name: "example-overlay",
- *       type: "modal",
- *       mount(container) {
- *         const app = document.createElement("div");
- *         app.textContent = "Content Script UI";
- *         container.append(app);
- *       }
- *     })
- *     ui.mount();
- *   }
- * })
- */
-export async function createContentScriptUi<TApp>(
-  ctx: ContentScriptContext,
-  options: ContentScriptUiOptions<TApp>,
-): Promise<ContentScriptUi<TApp>> {
-  const css = [options.css ?? ''];
-  if (ctx.options?.cssInjectionMode === 'ui') {
-    css.push(await loadCss());
-  }
-
-  const {
-    isolatedElement: uiContainer,
-    parentElement: shadowHost,
-    shadow,
-  } = await createIsolatedElement({
-    name: options.name,
-    css: {
-      textContent: css.join('\n').trim(),
-    },
-    mode: 'open',
-  });
-
-  let mounted: TApp;
-
-  const mount = () => {
-    // Mount UI inside shadow root
-    mounted = options.mount(uiContainer);
-
-    // Add shadow root element to DOM
-    mountContentScriptUiRoot(shadowHost, options);
-    applyContentScriptUiPosition(
-      shadowHost,
-      shadow.querySelector('html'),
-      options,
-    );
-  };
-
-  const remove = () => {
-    // Detatch shadow root from DOM
-    shadowHost.remove();
-    // Cleanup mounted state
-    options.onRemove?.(mounted);
-    // Remove children from uiContainer
-    while (uiContainer.lastChild)
-      uiContainer.removeChild(uiContainer.lastChild);
-  };
-
-  ctx.onInvalidated(remove);
-
-  return {
-    shadow,
-    shadowHost,
-    uiContainer,
-    mount,
-    remove,
-    mounted: mounted!,
-  };
-}
-
-/**
- * Load the CSS for the current entrypoint.
- */
-async function loadCss(): Promise<string> {
-  const url = browser.runtime.getURL(`/content-scripts/${__ENTRYPOINT__}.css`);
-  try {
-    const res = await fetch(url);
-    const css = await res.text();
-
-    // Replace :root selectors with :host since we're in a shadow root
-    return css.replaceAll(':root', ':host');
-  } catch (err) {
-    logger.warn(
-      `Failed to load styles @ ${url}. Did you forget to import the stylesheet in your entrypoint?`,
-      err,
-    );
-    return '';
-  }
-}
-
-export interface ContentScriptUi<TApp> {
-  /**
-   * The `HTMLElement` hosting the shadow root used to isolate the UI's styles. This is the element
-   * that get's added to the DOM. This element's style is not isolated from the webpage.
-   */
-  shadowHost: HTMLElement;
-  /**
-   * The container element inside the `ShadowRoot` whose styles are isolated. The UI is mounted
-   * inside this `HTMLElement`.
-   */
-  uiContainer: HTMLElement;
-  /**
-   * The shadow root performing the isolation.
-   */
-  shadow: ShadowRoot;
-  /**
-   * Custom data returned from the `options.mount` function.
-   */
-  mounted: TApp;
-  /**
-   * Function that mounts or remounts the UI on the page.
-   */
-  mount: () => void;
-  /**
-   * Function that removes the UI from the webpage.
-   */
-  remove: () => void;
-}
-
-export type ContentScriptUiOptions<TApp> = ContentScriptPositioningOptions &
-  ContentScriptAnchoredOptions & {
-    /**
-     * The name of the custom component used to host the ShadowRoot. Must be kebab-case.
-     */
-    name: string;
-    /**
-     * Callback executed when mounting the UI. This function should create and append the UI to the
-     * `container` element. It is called every time `ui.mount()` is called
-     *
-     * Optionally return a value that can be accessed at `ui.mounted` or in the `onRemove` callback.
-     */
-    mount: (container: Element) => TApp;
-    /**
-     * Callback called when the UI is removed from the webpage. Use to cleanup your UI, like
-     * unmounting your vue or react apps.
-     */
-    onRemove?: (mounted: TApp) => void;
-    /**
-     * Custom CSS text to apply to the UI. If your content script imports/generates CSS and you've
-     * set `cssInjectionMode: "ui"`, the imported CSS will be included automatically. You do not need
-     * to pass those styles in here. This is for any additional styles not in the imported CSS.
-     *
-     * See https://wxt.dev/entrypoints/content-scripts.html#ui for more info.
-     */
-    css?: string;
-  };
@@ -1,4 +1,2 @@
 export * from './content-script-context';
-export * from './content-script-ui';
-export * from './content-script-iframe';
-export * from './define-content-script';
+export * from './ui';
@@ -0,0 +1,407 @@
+/** @vitest-environment happy-dom */
+import { describe, it, beforeEach, vi, expect } from 'vitest';
+import { createIntegratedUi, createIframeUi, createShadowRootUi } from '..';
+import { ContentScriptContext } from '../../content-script-context';
+
+function appendTestApp(container: HTMLElement) {
+  container.innerHTML = '<app>Hello world</app>';
+}
+
+const fetch = vi.fn();
+
+describe('Content Script UIs', () => {
+  let ctx: ContentScriptContext;
+
+  beforeEach(() => {
+    document.body.innerHTML = `
+      <div id="parent">
+        <p id="one">one</p>
+        <p id="two">two</p>
+        <p id="three"></p>
+      </div>
+    `;
+    window.fetch = fetch;
+    fetch.mockResolvedValue({ text: () => Promise.resolve('') });
+    ctx = new ContentScriptContext('test');
+  });
+
+  describe('type', () => {
+    describe('integrated', () => {
+      it('should add a wrapper and custom UI to the page', () => {
+        const ui = createIntegratedUi(ctx, {
+          position: 'inline',
+          onMount: appendTestApp,
+        });
+        ui.mount();
+
+        expect(
+          document.querySelector('div[data-wxt-integrated]'),
+        ).not.toBeNull();
+        expect(document.querySelector('app')).not.toBeNull();
+      });
+
+      it('should allow customizing the wrapper tag', () => {
+        const ui = createIntegratedUi(ctx, {
+          position: 'inline',
+          tag: 'pre',
+          onMount: appendTestApp,
+        });
+        ui.mount();
+
+        expect(
+          document.querySelector('pre[data-wxt-integrated]'),
+        ).not.toBeNull();
+        expect(document.querySelector('app')).not.toBeNull();
+      });
+    });
+
+    describe('iframe', () => {
+      it('should add a wrapper and iframe to the page', () => {
+        const ui = createIframeUi(ctx, {
+          page: '/page.html',
+          position: 'inline',
+        });
+        ui.mount();
+
+        expect(document.querySelector('div[data-wxt-iframe]')).toBeDefined();
+        expect(document.querySelector('iframe')).toBeDefined();
+      });
+    });
+
+    describe('shadow-root', () => {
+      it('should load a shadow root to the page', async () => {
+        const ui = await createShadowRootUi(ctx, {
+          position: 'inline',
+          name: 'test',
+          onMount(uiContainer) {
+            appendTestApp(uiContainer);
+          },
+        });
+        ui.mount();
+
+        expect(
+          document.querySelector('test[data-wxt-shadow-root]'),
+        ).not.toBeNull();
+        expect(ui.shadow.querySelector('app')).not.toBeNull();
+      });
+
+      it.each([
+        ['open', 'open'],
+        [undefined, 'open'],
+        ['closed', 'closed'],
+      ] as const)(
+        'should respect the shadow root mode (%s -> %s)',
+        async (input, expected) => {
+          const ui = await createShadowRootUi(ctx, {
+            position: 'inline',
+            name: 'test',
+            mode: input,
+            onMount: appendTestApp,
+          });
+
+          expect(ui.shadow.mode).toBe(expected);
+        },
+      );
+    });
+  });
+
+  describe('position', () => {
+    describe('inline', () => {
+      it('should wrap the UI in a simple div', () => {
+        const ui = createIframeUi(ctx, {
+          position: 'inline',
+          page: '/page.html',
+        });
+
+        expect(ui.wrapper.outerHTML).toMatchInlineSnapshot(
+          `"<div data-wxt-iframe=""><iframe src="chrome-extension://test-extension-id/page.html"></iframe></div>"`,
+        );
+      });
+    });
+
+    describe('overlay', () => {
+      it('should wrap the UI in a positioned div when alignment=undefined', () => {
+        const ui = createIframeUi(ctx, {
+          position: 'overlay',
+          page: '/page.html',
+        });
+        ui.mount();
+
+        expect(ui.wrapper.outerHTML).toMatchInlineSnapshot(
+          `"<div data-wxt-iframe="" style="overflow: visible; position: relative; width: 0px; height: 0px; display: block;"><iframe src="chrome-extension://test-extension-id/page.html" style="position: absolute; top: 0px; left: 0px;"></iframe></div>"`,
+        );
+      });
+
+      it('should wrap the UI in a positioned div when alignment=top-left', () => {
+        const ui = createIframeUi(ctx, {
+          position: 'overlay',
+          page: '/page.html',
+          alignment: 'top-left',
+        });
+        ui.mount();
+
+        expect(ui.wrapper.outerHTML).toMatchInlineSnapshot(
+          `"<div data-wxt-iframe="" style="overflow: visible; position: relative; width: 0px; height: 0px; display: block;"><iframe src="chrome-extension://test-extension-id/page.html" style="position: absolute; top: 0px; left: 0px;"></iframe></div>"`,
+        );
+      });
+
+      it('should wrap the UI in a positioned div when alignment=top-right', () => {
+        const ui = createIframeUi(ctx, {
+          position: 'overlay',
+          page: '/page.html',
+          alignment: 'top-right',
+        });
+        ui.mount();
+
+        expect(ui.wrapper.outerHTML).toMatchInlineSnapshot(
+          `"<div data-wxt-iframe="" style="overflow: visible; position: relative; width: 0px; height: 0px; display: block;"><iframe src="chrome-extension://test-extension-id/page.html" style="position: absolute; top: 0px; right: 0px;"></iframe></div>"`,
+        );
+      });
+
+      it('should wrap the UI in a positioned div when alignment=bottom-right', () => {
+        const ui = createIframeUi(ctx, {
+          position: 'overlay',
+          page: '/page.html',
+          alignment: 'bottom-right',
+        });
+        ui.mount();
+
+        expect(ui.wrapper.outerHTML).toMatchInlineSnapshot(
+          `"<div data-wxt-iframe="" style="overflow: visible; position: relative; width: 0px; height: 0px; display: block;"><iframe src="chrome-extension://test-extension-id/page.html" style="position: absolute; bottom: 0px; right: 0px;"></iframe></div>"`,
+        );
+      });
+
+      it('should wrap the UI in a positioned div when alignment=bottom-left', () => {
+        const ui = createIframeUi(ctx, {
+          position: 'overlay',
+          page: '/page.html',
+          alignment: 'bottom-left',
+        });
+        ui.mount();
+
+        expect(ui.wrapper.outerHTML).toMatchInlineSnapshot(
+          `"<div data-wxt-iframe="" style="overflow: visible; position: relative; width: 0px; height: 0px; display: block;"><iframe src="chrome-extension://test-extension-id/page.html" style="position: absolute; bottom: 0px; left: 0px;"></iframe></div>"`,
+        );
+      });
+
+      it('should respect the provided zIndex', () => {
+        const zIndex = 123;
+        const ui = createIframeUi(ctx, {
+          position: 'overlay',
+          page: '/page.html',
+          zIndex,
+        });
+        ui.mount();
+
+        expect(ui.wrapper.style.zIndex).toBe(String(zIndex));
+      });
+    });
+
+    describe('modal', () => {
+      it('should wrap the UI in a div with a fixed position', () => {
+        const ui = createIframeUi(ctx, {
+          position: 'modal',
+          page: '/page.html',
+        });
+        ui.mount();
+
+        expect(ui.wrapper.outerHTML).toMatchInlineSnapshot(
+          `"<div data-wxt-iframe="" style="overflow: visible; position: relative; width: 0px; height: 0px; display: block;"><iframe src="chrome-extension://test-extension-id/page.html" style="position: fixed; top: 0px; bottom: 0px; left: 0px; right: 0px;"></iframe></div>"`,
+        );
+      });
+
+      it('should respect the provided zIndex', () => {
+        const zIndex = 123;
+        const ui = createIframeUi(ctx, {
+          position: 'modal',
+          page: '/page.html',
+          zIndex,
+        });
+        ui.mount();
+
+        expect(ui.wrapper.style.zIndex).toBe(String(zIndex));
+      });
+    });
+  });
+
+  describe('anchor', () => {
+    describe('undefined', () => {
+      it('should append the element to the body', () => {
+        const ui = createIntegratedUi(ctx, {
+          position: 'inline',
+          onMount: appendTestApp,
+        });
+        ui.mount();
+
+        expect(
+          document.querySelector('body > div[data-wxt-integrated]'),
+        ).not.toBeNull();
+      });
+    });
+
+    describe('string', () => {
+      it('should append the element using the specified query selector', () => {
+        const ui = createIntegratedUi(ctx, {
+          position: 'inline',
+          onMount: appendTestApp,
+          anchor: '#parent',
+        });
+        ui.mount();
+
+        expect(
+          document.querySelector('#parent > div[data-wxt-integrated]'),
+        ).not.toBeNull();
+      });
+    });
+
+    describe('Element', () => {
+      it('should append the element using the specified element', () => {
+        const ui = createIntegratedUi(ctx, {
+          position: 'inline',
+          onMount: appendTestApp,
+          anchor: document.getElementById('parent'),
+        });
+        ui.mount();
+
+        expect(
+          document.querySelector('#parent > div[data-wxt-integrated]'),
+        ).not.toBeNull();
+      });
+    });
+
+    describe('function', () => {
+      it('should append the element using the specified function', () => {
+        const ui = createIntegratedUi(ctx, {
+          position: 'inline',
+          onMount: appendTestApp,
+          anchor: () => document.getElementById('parent'),
+        });
+        ui.mount();
+
+        expect(
+          document.querySelector('#parent > div[data-wxt-integrated]'),
+        ).not.toBeNull();
+      });
+    });
+
+    it('should throw an error when the anchor does not exist', () => {
+      const ui = createIntegratedUi(ctx, {
+        position: 'inline',
+        onMount: appendTestApp,
+        anchor: () => document.getElementById('i-do-not-exist'),
+      });
+
+      expect(ui.mount).toThrow();
+    });
+  });
+
+  describe('append', () => {
+    describe.each([undefined, 'last'] as const)('%s', (append) => {
+      it('should append the element as the last child of the anchor', () => {
+        const ui = createIntegratedUi(ctx, {
+          position: 'inline',
+          anchor: '#parent',
+          append,
+          onMount: appendTestApp,
+        });
+        ui.mount();
+
+        expect(
+          document.querySelector(
+            '#parent > div[data-wxt-integrated]:last-child',
+          ),
+        ).not.toBeNull();
+      });
+    });
+
+    describe('first', () => {
+      it('should append the element as the last child of the anchor', () => {
+        const ui = createIntegratedUi(ctx, {
+          position: 'inline',
+          anchor: '#parent',
+          append: 'first',
+          onMount: appendTestApp,
+        });
+        ui.mount();
+
+        expect(
+          document.querySelector(
+            '#parent > div[data-wxt-integrated]:first-child',
+          ),
+        ).not.toBeNull();
+      });
+    });
+
+    describe('replace', () => {
+      it('should replace the the anchor', () => {
+        const ui = createIntegratedUi(ctx, {
+          position: 'inline',
+          anchor: '#parent',
+          append: 'replace',
+          onMount: appendTestApp,
+        });
+        ui.mount();
+
+        expect(
+          document.querySelector('body > div[data-wxt-integrated]'),
+        ).not.toBeNull();
+        expect(document.querySelector('#parent')).toBeNull();
+      });
+    });
+
+    describe('before', () => {
+      it('should append the UI before the anchor', () => {
+        const ui = createIntegratedUi(ctx, {
+          position: 'inline',
+          anchor: '#one',
+          append: 'before',
+          onMount: appendTestApp,
+        });
+        ui.mount();
+
+        expect(
+          document.querySelector(
+            '#parent > div[data-wxt-integrated]:first-child',
+          ),
+        ).not.toBeNull();
+      });
+    });
+
+    describe.todo('after', () => {
+      it('should append the UI after the anchor', () => {
+        const ui = createIntegratedUi(ctx, {
+          position: 'inline',
+          anchor: '#three',
+          append: 'after',
+          onMount: appendTestApp,
+        });
+        ui.mount();
+
+        expect(
+          document.querySelector(
+            '#parent > div[data-wxt-integrated]:last-child',
+          ),
+        ).not.toBeNull();
+      });
+    });
+
+    describe('function', () => {
+      it('should append the UI using a function', () => {
+        const ui = createIntegratedUi(ctx, {
+          position: 'inline',
+          anchor: '#parent',
+          append: (anchor, ui) => {
+            anchor.replaceWith(ui);
+          },
+          onMount: appendTestApp,
+        });
+        ui.mount();
+
+        expect(
+          document.querySelector('body > div[data-wxt-integrated]'),
+        ).not.toBeNull();
+        expect(document.querySelector('#parent')).toBeNull();
+      });
+    });
+  });
+});
@@ -0,0 +1,250 @@
+import { browser } from '~/browser';
+import { ContentScriptContext } from '..';
+import {
+  ContentScriptAnchoredOptions,
+  ContentScriptPositioningOptions,
+  IframeContentScriptUi,
+  IframeContentScriptUiOptions,
+  IntegratedContentScriptUi,
+  IntegratedContentScriptUiOptions,
+  ShadowRootContentScriptUi,
+  ShadowRootContentScriptUiOptions,
+} from './types';
+import { logger } from '~/sandbox/utils/logger';
+import { createIsolatedElement } from '@webext-core/isolated-element';
+export * from './types';
+
+/**
+ * Create a content script UI without any isolation.
+ *
+ * @see https://wxt.dev/guide/content-script-ui.html#integrated
+ */
+export function createIntegratedUi<TMounted>(
+  ctx: ContentScriptContext,
+  options: IntegratedContentScriptUiOptions<TMounted>,
+): IntegratedContentScriptUi<TMounted> {
+  const wrapper = document.createElement(options.tag || 'div');
+  wrapper.setAttribute('data-wxt-integrated', '');
+
+  let mounted: TMounted | undefined = undefined;
+  const mount = () => {
+    applyPosition(wrapper, undefined, options);
+    mountUi(wrapper, options);
+    mounted = options.onMount?.(wrapper);
+  };
+  const remove = () => {
+    options.onRemove?.(mounted);
+    wrapper.remove();
+  };
+
+  ctx.onInvalidated(remove);
+
+  return {
+    mounted,
+    wrapper,
+    mount,
+    remove,
+  };
+}
+
+/**
+ * Create a content script UI using an iframe.
+ *
+ * @see https://wxt.dev/guide/content-script-ui.html#iframe
+ */
+export function createIframeUi<TMounted>(
+  ctx: ContentScriptContext,
+  options: IframeContentScriptUiOptions<TMounted>,
+): IframeContentScriptUi<TMounted> {
+  const wrapper = document.createElement('div');
+  wrapper.setAttribute('data-wxt-iframe', '');
+  const iframe = document.createElement('iframe');
+  iframe.src = browser.runtime.getURL(options.page);
+  wrapper.appendChild(iframe);
+
+  let mounted: TMounted | undefined = undefined;
+  const mount = () => {
+    applyPosition(wrapper, iframe, options);
+    mountUi(wrapper, options);
+    mounted = options.onMount?.(wrapper, iframe);
+  };
+  const remove = () => {
+    options.onRemove?.(mounted);
+    wrapper.remove();
+  };
+
+  ctx.onInvalidated(remove);
+
+  return {
+    mounted,
+    iframe,
+    wrapper,
+    mount,
+    remove,
+  };
+}
+
+/**
+ * Create a content script UI inside a [`ShadowRoot`](https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot).
+ *
+ * > This function is async because it has to load the CSS via a network call.
+ *
+ * @see https://wxt.dev/guide/content-script-ui.html#shadowroot
+ */
+export async function createShadowRootUi<TMounted>(
+  ctx: ContentScriptContext,
+  options: ShadowRootContentScriptUiOptions<TMounted>,
+): Promise<ShadowRootContentScriptUi<TMounted>> {
+  const css = [options.css ?? ''];
+  if (ctx.options?.cssInjectionMode === 'ui') {
+    const entryCss = await loadCss();
+    // Replace :root selectors with :host since we're in a shadow root
+    css.push(entryCss.replaceAll(':root', ':host'));
+  }
+
+  const {
+    isolatedElement: uiContainer,
+    parentElement: shadowHost,
+    shadow,
+  } = await createIsolatedElement({
+    name: options.name,
+    css: {
+      textContent: css.join('\n').trim(),
+    },
+    mode: options.mode ?? 'open',
+    isolateEvents: options.isolateEvents,
+  });
+  shadowHost.setAttribute('data-wxt-shadow-root', '');
+
+  let mounted: TMounted;
+
+  const mount = () => {
+    // Mount UI inside shadow root
+    mounted = options.onMount(uiContainer, shadow, shadowHost);
+
+    // Add shadow root element to DOM
+    mountUi(shadowHost, options);
+    applyPosition(shadowHost, shadow.querySelector('html'), options);
+  };
+
+  const remove = () => {
+    // Detatch shadow root from DOM
+    shadowHost.remove();
+    // Cleanup mounted state
+    options.onRemove?.(mounted);
+    // Remove children from uiContainer
+    while (uiContainer.lastChild)
+      uiContainer.removeChild(uiContainer.lastChild);
+  };
+
+  ctx.onInvalidated(remove);
+
+  return {
+    shadow,
+    shadowHost,
+    uiContainer,
+    mount,
+    remove,
+    mounted: mounted!,
+  };
+}
+
+function applyPosition(
+  root: HTMLElement,
+  positionedElement: HTMLElement | undefined | null,
+  options: ContentScriptPositioningOptions,
+): void {
+  // No positioning for inline UIs
+  if (options.position === 'inline') return;
+
+  if (options.zIndex != null) root.style.zIndex = String(options.zIndex);
+
+  root.style.overflow = 'visible';
+  root.style.position = 'relative';
+  root.style.width = '0';
+  root.style.height = '0';
+  root.style.display = 'block';
+
+  if (positionedElement) {
+    if (options.position === 'overlay') {
+      positionedElement.style.position = 'absolute';
+      if (options.alignment?.startsWith('bottom-'))
+        positionedElement.style.bottom = '0';
+      else positionedElement.style.top = '0';
+
+      if (options.alignment?.endsWith('-right'))
+        positionedElement.style.right = '0';
+      else positionedElement.style.left = '0';
+    } else {
+      positionedElement.style.position = 'fixed';
+      positionedElement.style.top = '0';
+      positionedElement.style.bottom = '0';
+      positionedElement.style.left = '0';
+      positionedElement.style.right = '0';
+    }
+  }
+}
+
+function getAnchor(options: ContentScriptAnchoredOptions): Element | undefined {
+  if (options.anchor == null) return document.body;
+
+  let resolved =
+    typeof options.anchor === 'function' ? options.anchor() : options.anchor;
+  if (typeof resolved === 'string')
+    return document.querySelector<Element>(resolved) ?? undefined;
+  return resolved ?? undefined;
+}
+
+function mountUi(
+  root: HTMLElement,
+  options: ContentScriptAnchoredOptions,
+): void {
+  const anchor = getAnchor(options);
+  if (anchor == null)
+    throw Error(
+      'Failed to mount content script UI: could not find anchor element',
+    );
+
+  switch (options.append) {
+    case undefined:
+    case 'last':
+      anchor.append(root);
+      break;
+    case 'first':
+      if (anchor.firstChild) {
+        anchor.insertBefore(root, anchor.firstChild);
+      } else {
+        anchor.append(root);
+      }
+      break;
+    case 'replace':
+      anchor.replaceWith(root);
+      break;
+    case 'after':
+      anchor.replaceWith(anchor, root);
+      break;
+    case 'before':
+      anchor.replaceWith(root, anchor);
+      break;
+    default:
+      options.append(anchor, root);
+      break;
+  }
+}
+
+/**
+ * Load the CSS for the current entrypoint.
+ */
+async function loadCss(): Promise<string> {
+  const url = browser.runtime.getURL(`/content-scripts/${__ENTRYPOINT__}.css`);
+  try {
+    const res = await fetch(url);
+    return await res.text();
+  } catch (err) {
+    logger.warn(
+      `Failed to load styles @ ${url}. Did you forget to import the stylesheet in your entrypoint?`,
+      err,
+    );
+    return '';
+  }
+}
@@ -0,0 +1,217 @@
+export interface IntegratedContentScriptUi<TMounted>
+  extends ContentScriptUi<TMounted> {
+  /**
+   * A wrapper div that assists in positioning.
+   */
+  wrapper: HTMLElement;
+}
+
+export interface IframeContentScriptUi<TMounted>
+  extends ContentScriptUi<TMounted> {
+  /**
+   * The iframe added to the DOM.
+   */
+  iframe: HTMLIFrameElement;
+  /**
+   * A wrapper div that assists in positioning.
+   */
+  wrapper: HTMLDivElement;
+}
+
+export interface ShadowRootContentScriptUi<TMounted>
+  extends ContentScriptUi<TMounted> {
+  /**
+   * The `HTMLElement` hosting the shadow root used to isolate the UI's styles. This is the element
+   * that get's added to the DOM. This element's style is not isolated from the webpage.
+   */
+  shadowHost: HTMLElement;
+  /**
+   * The container element inside the `ShadowRoot` whose styles are isolated. The UI is mounted
+   * inside this `HTMLElement`.
+   */
+  uiContainer: HTMLElement;
+  /**
+   * The shadow root performing the isolation.
+   */
+  shadow: ShadowRoot;
+}
+
+export interface ContentScriptUi<TMounted> {
+  /**
+   * Function that mounts or remounts the UI on the page.
+   */
+  mount: () => void;
+  /**
+   * Function that removes the UI from the webpage.
+   */
+  remove: () => void;
+  /**>
+   * Custom data returned from the `options.mount` function.
+   */
+  mounted: TMounted | undefined;
+}
+
+export type ContentScriptUiOptions<TMounted> = ContentScriptPositioningOptions &
+  ContentScriptAnchoredOptions & {
+    /**
+     * Callback called before the UI is removed from the webpage. Use to cleanup your UI, like
+     * unmounting your Vue or React apps.
+     */
+    onRemove?: (mounted: TMounted | undefined) => void;
+  };
+
+export type IntegratedContentScriptUiOptions<TMounted> =
+  ContentScriptUiOptions<TMounted> & {
+    /**
+     * Tag used to create the wrapper element.
+     *
+     * @default "div"
+     */
+    tag?: string;
+    /**
+     * Callback executed when mounting the UI. This function should create and append the UI to the
+     * `wrapper` element. It is called every time `ui.mount()` is called.
+     *
+     * Optionally return a value that can be accessed at `ui.mounted` or in the `onRemove` callback.
+     */
+    onMount: (wrapper: HTMLElement) => TMounted;
+  };
+
+export type IframeContentScriptUiOptions<TMounted> =
+  ContentScriptUiOptions<TMounted> & {
+    /**
+     * The path to the HTML page that will be shown in the iframe. This string is passed into
+     * `browser.runtime.getURL`.
+     */
+    page: PublicPath;
+    /**
+     * Callback executed when mounting the UI. Use this function to customize the iframe or wrapper
+     * element's appearance. It is called every time `ui.mount()` is called.
+     *
+     * Optionally return a value that can be accessed at `ui.mounted` or in the `onRemove` callback.
+     */
+    onMount?: (wrapper: HTMLElement, iframe: HTMLIFrameElement) => TMounted;
+  };
+
+export type ShadowRootContentScriptUiOptions<TMounted> =
+  ContentScriptUiOptions<TMounted> & {
+    /**
+     * The name of the custom component used to host the ShadowRoot. Must be kebab-case.
+     */
+    name: string;
+    /**
+     * Custom CSS text to apply to the UI. If your content script imports/generates CSS and you've
+     * set `cssInjectionMode: "ui"`, the imported CSS will be included automatically. You do not need
+     * to pass those styles in here. This is for any additional styles not in the imported CSS.
+     */
+    css?: string;
+    /**
+     * ShadowRoot's mode.
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot/mode
+     * @default "open"
+     */
+    mode?: 'open' | 'closed';
+    /**
+     * 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[];
+    /**
+     * Callback executed when mounting the UI. This function should create and append the UI to the
+     * `uiContainer` element. It is called every time `ui.mount()` is called.
+     *
+     * Optionally return a value that can be accessed at `ui.mounted` or in the `onRemove` callback.
+     */
+    onMount: (
+      uiContainer: HTMLElement,
+      shadow: ShadowRoot,
+      shadowHost: HTMLElement,
+    ) => TMounted;
+  };
+
+export type ContentScriptOverlayAlignment =
+  | 'top-left'
+  | 'top-right'
+  | 'bottom-left'
+  | 'bottom-right';
+
+/**
+ * ![Visualization of different append modes](https://wxt.dev/content-script-ui-append.png)
+ */
+export type ContentScriptAppendMode =
+  | 'last'
+  | 'first'
+  | 'replace'
+  | 'before'
+  | 'after'
+  | ((anchor: Element, ui: Element) => void);
+
+export interface ContentScriptInlinePositioningOptions {
+  position: 'inline';
+}
+
+export interface ContentScriptOverlayPositioningOptions {
+  position: 'overlay';
+  /**
+   * The `z-index` used on the `wrapper` element. Set to a positive number to show your UI over website
+   * content.
+   */
+  zIndex?: number;
+  /**
+   * When using `type: "overlay"`, the mounted element is 0px by 0px in size. Alignment specifies
+   * which corner is aligned with that 0x0 pixel space.
+   *
+   * ![Visualization of alignment options](https://wxt.dev/content-script-ui-alignment.png)
+   *
+   * @default "top-left"
+   */
+  alignment?: ContentScriptOverlayAlignment;
+}
+
+export interface ContentScriptModalPositioningOptions {
+  position: 'modal';
+  /**
+   * The `z-index` used on the `shadowHost`. Set to a positive number to show your UI over website
+   * content.
+   */
+  zIndex?: number;
+}
+
+/**
+ * Choose between `"inline"`, `"overlay"`, or `"modal" `types.
+ *
+ * ![Visualization of different types](https://wxt.dev/content-script-ui-type.png)
+ */
+export type ContentScriptPositioningOptions =
+  | ContentScriptInlinePositioningOptions
+  | ContentScriptOverlayPositioningOptions
+  | ContentScriptModalPositioningOptions;
+
+export interface ContentScriptAnchoredOptions {
+  /**
+   * A CSS selector, element, or function that returns one of the two. Along with `append`, the
+   * `anchor` dictates where in the page the UI will be added.
+   */
+  anchor?:
+    | string
+    | Element
+    | null
+    | undefined
+    | (() => string | Element | null | undefined);
+  /**
+   * In combination with `anchor`, decide how to add the UI to the DOM.
+   *
+   * - `"last"` (default) - Add the UI as the last child of the `anchor` element
+   * - `"first"` - Add the UI as the last child of the `anchor` element
+   * - `"replace"` - Replace the `anchor` element with the UI.
+   * - `"before"` - Add the UI as the sibling before the `anchor` element
+   * - `"after"` - Add the UI as the sibling after the `anchor` element
+   * - `(anchor, ui) => void` - Customizable function that let's you add the UI to the DOM
+   */
+  append?: ContentScriptAppendMode | ((anchor: Element, ui: Element) => void);
+}
@@ -1,5 +1,6 @@
 /**
+ * Any runtime APIs that use the web extension APIs.
+ *
 * @module wxt/client
 */
-export * from './define-background';
 export * from './content-scripts';
@@ -1,145 +0,0 @@
-export type ContentScriptOverlayAlignment =
-  | 'top-left'
-  | 'top-right'
-  | 'bottom-left'
-  | 'bottom-right';
-
-export type ContentScriptAppendMode =
-  | 'last'
-  | 'first'
-  | 'replace'
-  | 'before'
-  | 'after'
-  | ((anchor: Element, ui: Element) => void);
-
-export function mountContentScriptUiRoot(
-  root: HTMLElement,
-  options: ContentScriptAnchoredOptions,
-): void {
-  const anchor = getAnchor(options);
-  if (anchor == null)
-    throw Error(
-      'Failed to mount content script UI: could not find anchor element',
-    );
-
-  switch (options.append) {
-    case undefined:
-    case 'last':
-      anchor.append(root);
-      break;
-    case 'first':
-      if (anchor.firstChild) {
-        anchor.insertBefore(root, anchor.firstChild);
-      } else {
-        anchor.append(root);
-      }
-      break;
-    case 'replace':
-      anchor.replaceWith(root);
-      break;
-    case 'after':
-      anchor.replaceWith(anchor, root);
-      break;
-    case 'before':
-      anchor.replaceWith(root, anchor);
-      break;
-    default:
-      options.append(anchor, root);
-      break;
-  }
-}
-
-export type ContentScriptPositioningOptions =
-  | { type: 'inline' }
-  | {
-      type: 'overlay';
-      /**
-       * The `z-index` used on the `shadowHost`. Set to a positive number to show your UI over website
-       * content.
-       */
-      zIndex?: number;
-      /**
-       * When using `type: "overlay"`, the mounted element is 0px by 0px in size. Alignment specifies
-       * which corner is aligned with that 0x0 pixel space.
-       *
-       * @default "top-left"
-       */
-      alignment?: ContentScriptOverlayAlignment;
-    }
-  | {
-      type: 'modal';
-      /**
-       * The `z-index` used on the `shadowHost`. Set to a positive number to show your UI over website
-       * content.
-       */
-      zIndex?: number;
-    };
-
-export function applyContentScriptUiPosition(
-  root: HTMLElement,
-  positionedElement: HTMLElement | undefined | null,
-  options: ContentScriptPositioningOptions,
-): void {
-  if (options.type !== 'inline') {
-    if (options.zIndex != null) root.style.zIndex = String(options.zIndex);
-
-    root.style.overflow = 'visible';
-    root.style.position = 'relative';
-    root.style.width = '0';
-    root.style.height = '0';
-    root.style.display = 'block';
-
-    if (positionedElement) {
-      if (options.type === 'overlay') {
-        positionedElement.style.position = 'absolute';
-        if (options.alignment?.startsWith('bottom-'))
-          positionedElement.style.bottom = '0';
-        else positionedElement.style.top = '0';
-
-        if (options.alignment?.endsWith('-right'))
-          positionedElement.style.right = '0';
-        else positionedElement.style.left = '0';
-      } else {
-        positionedElement.style.position = 'fixed';
-        positionedElement.style.top = '0';
-        positionedElement.style.bottom = '0';
-        positionedElement.style.left = '0';
-        positionedElement.style.right = '0';
-      }
-    }
-  }
-}
-
-function getAnchor(options: ContentScriptAnchoredOptions): Element | undefined {
-  if (options.anchor == null) return document.body;
-
-  let resolved =
-    typeof options.anchor === 'function' ? options.anchor() : options.anchor;
-  if (typeof resolved === 'string')
-    return document.querySelector<Element>(resolved) ?? undefined;
-  return resolved ?? undefined;
-}
-
-export interface ContentScriptAnchoredOptions {
-  /**
-   * A CSS selector, element, or function that returns one of the two. Along with `append`, the
-   * `anchor` dictates where in the page the UI will be added.
-   */
-  anchor?:
-    | string
-    | Element
-    | null
-    | undefined
-    | (() => string | Element | null | undefined);
-  /**
-   * In combination with `anchor`, decide how to add the UI to the DOM.
-   *
-   * - `"last"` (default) - Add the UI as the last child of the `anchor` element
-   * - `"first"` - Add the UI as the last child of the `anchor` element
-   * - `"replace"` - Replace the `anchor` element with the UI.
-   * - `"before"` - Add the UI as the sibling before the `anchor` element
-   * - `"after"` - Add the UI as the sibling after the `anchor` element
-   * - `(anchor, ui) => void` - Customizable function that let's you add the UI to the DOM
-   */
-  append?: ContentScriptAppendMode | ((anchor: Element, ui: Element) => void);
-}
@@ -5,13 +5,14 @@ import {
  InlineConfig,
  InternalConfig,
  UserConfig,
+  VirtualEntrypointType,
  WxtBuilder,
  WxtBuilderServer,
 } from '~/types';
 import * as wxtPlugins from './plugins';
 import { getEntrypointBundlePath } from '~/core/utils/entrypoints';

-export async function craeteViteBuilder(
+export async function createViteBuilder(
  inlineConfig: InlineConfig,
  userConfig: UserConfig,
  wxtConfig: Omit<InternalConfig, 'builder'>,
@@ -39,6 +40,10 @@ export async function craeteViteBuilder(
    config.build ??= {};
    config.build.outDir = wxtConfig.outDir;
    config.build.emptyOutDir = false;
+    // Disable minification for the dev command
+    if (config.build.minify == null && wxtConfig.command === 'serve') {
+      config.build.minify = false;
+    }

    config.plugins ??= [];
    config.plugins.push(
@@ -46,7 +51,8 @@ export async function craeteViteBuilder(
      wxtPlugins.devHtmlPrerender(wxtConfig),
      wxtPlugins.unimport(wxtConfig),
      wxtPlugins.virtualEntrypoint('background', wxtConfig),
-      wxtPlugins.virtualEntrypoint('content-script', wxtConfig),
+      wxtPlugins.virtualEntrypoint('content-script-isolated-world', wxtConfig),
+      wxtPlugins.virtualEntrypoint('content-script-main-world', wxtConfig),
      wxtPlugins.virtualEntrypoint('unlisted-script', wxtConfig),
      wxtPlugins.devServerGlobals(wxtConfig),
      wxtPlugins.tsconfigPaths(wxtConfig),
@@ -65,13 +71,21 @@ export async function craeteViteBuilder(
   * Return the basic config for building an entrypoint in [lib mode](https://vitejs.dev/guide/build.html#library-mode).
   */
  const getLibModeConfig = (entrypoint: Entrypoint): vite.InlineConfig => {
-    const isVirtual = [
-      'background',
-      'content-script',
-      'unlisted-script',
-    ].includes(entrypoint.type);
-    const entry = isVirtual
-      ? `virtual:wxt-${entrypoint.type}?${entrypoint.inputPath}`
+    let virtualEntrypointType: VirtualEntrypointType | undefined;
+    switch (entrypoint.type) {
+      case 'background':
+      case 'unlisted-script':
+        virtualEntrypointType = entrypoint.type;
+        break;
+      case 'content-script':
+        virtualEntrypointType =
+          entrypoint.options.world === 'MAIN'
+            ? 'content-script-main-world'
+            : 'content-script-isolated-world';
+        break;
+    }
+    const entry = virtualEntrypointType
+      ? `virtual:wxt-${virtualEntrypointType}?${entrypoint.inputPath}`
      : entrypoint.inputPath;

    const plugins: NonNullable<vite.UserConfig['plugins']> = [
@@ -1,4 +1,4 @@
-import * as vite from 'vite';
+import type * as vite from 'vite';
 import { visualizer } from 'rollup-plugin-visualizer';

 let increment = 0;
@@ -1,4 +1,4 @@
-import * as vite from 'vite';
+import type * as vite from 'vite';
 import { Entrypoint, InternalConfig } from '~/types';
 import { getEntrypointBundlePath } from '~/core/utils/entrypoints';

@@ -1,4 +1,4 @@
-import * as vite from 'vite';
+import type * as vite from 'vite';
 import { InternalConfig } from '~/types';
 import { getEntrypointName } from '~/core/utils/entrypoints';
 import { parseHTML } from 'linkedom';
@@ -1,4 +1,4 @@
-import * as vite from 'vite';
+import type * as vite from 'vite';
 import { EntrypointGroup } from '~/types';
 import { getEntrypointGlobals } from '~/core/utils/globals';

@@ -1,5 +1,5 @@
 import { InternalConfig } from '~/types';
-import * as vite from 'vite';
+import type * as vite from 'vite';

 /**
 * Apply the experimental config for disabling the polyfill. It works by aliasing the
@@ -1,4 +1,4 @@
-import * as vite from 'vite';
+import type * as vite from 'vite';
 import { InternalConfig } from '~/types';
 import { getGlobals } from '~/core/utils/globals';

@@ -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';
@@ -1,4 +1,4 @@
-import * as vite from 'vite';
+import type * as vite from 'vite';
 import { Entrypoint, InternalConfig } from '~/types';
 import { dirname, extname, resolve, join } from 'node:path';
 import { getEntrypointBundlePath } from '~/core/utils/entrypoints';
@@ -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)`;
      }
    },
  };
@@ -1,5 +1,5 @@
 import { InternalConfig } from '~/types';
-import * as vite from 'vite';
+import type * as vite from 'vite';

 export function tsconfigPaths(
  config: Omit<InternalConfig, 'builder'>,
@@ -1,7 +1,7 @@
 import { createUnimport } from 'unimport';
 import { InternalConfig } from '~/types';
 import { getUnimportOptions } from '~/core/utils/unimport';
-import * as vite from 'vite';
+import type * as vite from 'vite';
 import { extname } from 'path';

 const ENABLED_EXTENSIONS = new Set([
@@ -1,5 +1,5 @@
 import { Plugin } from 'vite';
-import { Entrypoint, InternalConfig } from '~/types';
+import { InternalConfig, VirtualEntrypointType } from '~/types';
 import fs from 'fs-extra';
 import { resolve } from 'path';
 import { normalizePath } from '~/core/utils/paths';
@@ -8,7 +8,7 @@ import { normalizePath } from '~/core/utils/paths';
 * Wraps a user's entrypoint with a vitual version with additional logic.
 */
 export function virtualEntrypoint(
-  type: Entrypoint['type'],
+  type: VirtualEntrypointType,
  config: Omit<InternalConfig, 'builder'>,
 ): Plugin {
  const virtualId = `virtual:wxt-${type}?`;
@@ -1,28 +0,0 @@
-import path from 'node:path';
-import * 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',
-            ),
-          },
-        },
-      };
-    },
-  };
-}
@@ -1,24 +0,0 @@
-import * 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', 'wxt/client'];
-      return {
-        test: {
-          server: {
-            deps: {
-              inline: [...wxtModules],
-            },
-          },
-        },
-      };
-    },
-  };
-}
@@ -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'],
+        },
+      };
+    },
+  };
+}
@@ -20,6 +20,7 @@ import {
  getInternalConfig,
  detectDevChanges,
  rebuild,
+  findEntrypoints,
 } from '~/core/utils/building';
 import { createExtensionRunner } from '~/core/runners';
 import { consola } from 'consola';
@@ -159,8 +160,10 @@ function createFileReloader(options: {
        .join(pc.dim(', '));

      // Rebuild entrypoints on change
+      const allEntrypoints = await findEntrypoints(config);
      const { output: newOutput } = await rebuild(
        config,
+        allEntrypoints,
        // TODO: this excludes new entrypoints, so they're not built until the dev command is restarted
        changes.rebuildGroups,
        changes.cachedOutput,
@@ -150,14 +150,6 @@ async function cloneProject({
        consola.warn('Failed to move _gitignore to .gitignore:', err),
      );

-    // 3. Add .npmrc for pnpm
-    if (packageManager === 'pnpm') {
-      await fs.writeFile(
-        path.join(directory, '.npmrc'),
-        'shamefully-hoist=true\n',
-      );
-    }
-
    spinner.succeed();
  } catch (err) {
    spinner.fail();
@@ -0,0 +1,965 @@
+import { describe, expect, it } from 'vitest';
+import { generateManifest, stripPathFromMatchPattern } 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',
+          ]);
+        });
+
+        it('should strip the path off the match pattern so the pattern is valid for `web_accessible_resources`', async () => {
+          const cs: ContentScriptEntrypoint = {
+            type: 'content-script',
+            name: 'one',
+            inputPath: 'entrypoints/one.content.ts',
+            outputDir: contentScriptOutDir,
+            options: {
+              matches: ['*://play.google.com/books/*'],
+              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: ['*://play.google.com/*'],
+              resources: ['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: 'Alt+R',
+        },
+      };
+
+      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();
+      });
+    });
+  });
+
+  describe('stripPathFromMatchPattern', () => {
+    it.each([
+      ['<all_urls>', '<all_urls>'],
+      ['*://play.google.com/books/*', '*://play.google.com/*'],
+      ['*://*/*', '*://*/*'],
+      ['https://github.com/wxt-dev/*', 'https://github.com/*'],
+    ])('should convert "%s" to "%s"', (input, expected) => {
+      const actual = stripPathFromMatchPattern(input);
+      expect(actual).toEqual(expected);
+    });
+  });
+});
@@ -1,4 +1,4 @@
-import { defineBackground } from '~/client';
+import { defineBackground } from '~/sandbox';

 export default defineBackground({
  main() {},
@@ -1,4 +1,4 @@
-import { defineContentScript } from '~/client';
+import { defineContentScript } from '~/sandbox';

 export default defineContentScript({
  matches: ['<all_urls>'],
@@ -1,4 +1,4 @@
-import { defineBackground } from '~/client';
+import { defineBackground } from '~/sandbox';

 export const a = {};

@@ -244,15 +244,15 @@ describe('findEntrypoints', () => {
  );

  it("should include a virtual background script so dev reloading works when there isn't a background entrypoint defined by the user", async () => {
-    globMock.mockResolvedValueOnce([]);
+    globMock.mockResolvedValueOnce(['popup.html']);

    const entrypoints = await findEntrypoints({
      ...config,
      command: 'serve',
    });

-    expect(entrypoints).toHaveLength(1);
-    expect(entrypoints[0]).toEqual({
+    expect(entrypoints).toHaveLength(2);
+    expect(entrypoints).toContainEqual({
      type: 'background',
      inputPath: 'virtual:user-background',
      name: 'background',
@@ -261,28 +261,24 @@ describe('findEntrypoints', () => {
    });
  });

-  it.each<[string, Omit<GenericEntrypoint, 'options'>]>([
-    [
-      'injected.ts',
-      {
-        type: 'unlisted-script',
-        name: 'injected',
-        inputPath: resolve(config.entrypointsDir, 'injected.ts'),
-        outputDir: config.outDir,
-      },
-    ],
-    [
-      'injected/index.ts',
-      {
-        type: 'unlisted-script',
-        name: 'injected',
-        inputPath: resolve(config.entrypointsDir, 'injected/index.ts'),
-        outputDir: config.outDir,
-      },
-    ],
+  it.each<string>([
+    'injected.ts',
+    'injected.tsx',
+    'injected.js',
+    'injected.jsx',
+    'injected/index.ts',
+    'injected/index.tsx',
+    'injected/index.js',
+    'injected/index.jsx',
  ])(
    'should find and load unlisted-script entrypoint config from %s',
-    async (path, expected) => {
+    async (path) => {
+      const expected = {
+        type: 'unlisted-script',
+        name: 'injected',
+        inputPath: resolve(config.entrypointsDir, path),
+        outputDir: config.outDir,
+      };
      const options: GenericEntrypoint['options'] = {};
      globMock.mockResolvedValueOnce([path]);
      importEntrypointFileMock.mockResolvedValue(options);
@@ -566,15 +562,35 @@ describe('findEntrypoints', () => {
  });

  it('should not allow multiple entrypoints with the same name', async () => {
-    globMock.mockResolvedValueOnce(['popup.html', 'popup/index.html']);
-    const expectedPaths = [
-      'src/entrypoints/popup.html',
-      'src/entrypoints/popup/index.html',
-    ].map(unnormalizePath);
+    globMock.mockResolvedValueOnce([
+      'options/index.html',
+      'options/index.jsx',
+      'popup.html',
+      'popup/index.html',
+      'popup/index.ts',
+      'ui.html',
+    ]);

    await expect(() => findEntrypoints(config)).rejects.toThrowError(
-      'Multiple entrypoints with the name "popup" detected, but only one is allowed: ' +
-        expectedPaths.join(', '),
+      [
+        'Multiple entrypoints with the same name detected, only one entrypoint for each name is allowed.',
+        '',
+        '- options',
+        `  - ${unnormalizePath('src/entrypoints/options/index.html')}`,
+        `  - ${unnormalizePath('src/entrypoints/options/index.jsx')}`,
+        '- popup',
+        `  - ${unnormalizePath('src/entrypoints/popup.html')}`,
+        `  - ${unnormalizePath('src/entrypoints/popup/index.html')}`,
+        `  - ${unnormalizePath('src/entrypoints/popup/index.ts')}`,
+      ].join('\n'),
+    );
+  });
+
+  it('throw an error if there are no entrypoints', async () => {
+    globMock.mockResolvedValueOnce([]);
+
+    await expect(() => findEntrypoints(config)).rejects.toThrowError(
+      `No entrypoints found in ${unnormalizePath(config.entrypointsDir)}`,
    );
  });

@@ -6,9 +6,11 @@ import {
 } from '~/types';
 import { getPublicFiles } from '~/core/utils/fs';
 import fs from 'fs-extra';
-import { dirname, resolve } from 'path';
+import { dirname, resolve, extname } from 'node:path';
 import type { Ora } from 'ora';
 import pc from 'picocolors';
+import { unnormalizePath } from '~/core/utils/paths';
+import { convertMessagesToManifest, readMessagesFile } from '~/i18n/node';

 export async function buildEntrypoints(
  groups: EntrypointGroup[],
@@ -25,7 +27,13 @@ export async function buildEntrypoints(
    spinner.text = pc.dim(`[${i + 1}/${groups.length}]`) + ` ${groupNames}`;
    steps.push(await config.builder.build(group));
  }
-  const publicAssets = await copyPublicDirectory(config);
+
+  const publicAssets = (
+    await Promise.all([
+      copyPublicDirectory(config),
+      copyLocalesDirectory(config),
+    ])
+  ).flat();

  return { publicAssets, steps };
 }
@@ -51,3 +59,31 @@ async function copyPublicDirectory(

  return publicAssets;
 }
+
+async function copyLocalesDirectory(
+  config: InternalConfig,
+): Promise<BuildOutput['publicAssets']> {
+  const localesExist = await fs.exists(config.localesDir);
+  if (!localesExist || config.manifest.default_locale == null) return [];
+
+  const files = await fs.readdir(config.localesDir);
+
+  return await Promise.all(
+    files.map(async (file) => {
+      const locale = file.replace(extname(file), '');
+      const fileName = unnormalizePath(`_locales/${locale}/messages.json`);
+      const srcPath = resolve(config.localesDir, file);
+      const outPath = resolve(config.outDir, fileName);
+
+      const messages = await readMessagesFile(srcPath);
+      const json = convertMessagesToManifest(messages);
+
+      await fs.ensureDir(dirname(outPath));
+      await fs.writeJson(outPath, json);
+      return {
+        fileName,
+        type: 'asset',
+      };
+    }),
+  );
+}
@@ -31,56 +31,55 @@ import { CSS_EXTENSIONS_PATTERN } from '~/core/utils/paths';
 export async function findEntrypoints(
  config: InternalConfig,
 ): Promise<Entrypoint[]> {
-  const relativePaths = await glob('**/*', {
+  const relativePaths = await glob(Object.keys(PATH_GLOB_TO_TYPE_MAP), {
    cwd: config.entrypointsDir,
  });
  // Ensure consistent output
  relativePaths.sort();

  const pathGlobs = Object.keys(PATH_GLOB_TO_TYPE_MAP);
-
-  let hasBackground = false;
-  // TODO: This parallelization is bad
-  const possibleEntrypoints: Array<Entrypoint | undefined> = await Promise.all(
-    relativePaths.map(async (relativePath) => {
-      const path = resolve(config.entrypointsDir, relativePath);
-      const matchingGlob = pathGlobs.find((glob) =>
-        minimatch(relativePath, glob),
-      );
-
-      if (matchingGlob == null) {
-        config.logger.warn(
-          `${relativePath} does not match any known entrypoint. Known entrypoints:\n${JSON.stringify(
-            PATH_GLOB_TO_TYPE_MAP,
-            null,
-            2,
-          )}`,
-        );
-        return;
-      }
-
+  const entrypointInfos: EntrypointInfo[] = relativePaths.reduce<
+    EntrypointInfo[]
+  >((results, relativePath) => {
+    const inputPath = resolve(config.entrypointsDir, relativePath);
+    const name = getEntrypointName(config.entrypointsDir, inputPath);
+    const matchingGlob = pathGlobs.find((glob) =>
+      minimatch(relativePath, glob),
+    );
+    if (matchingGlob) {
      const type = PATH_GLOB_TO_TYPE_MAP[matchingGlob];
-      if (type === 'ignored') return;
+      results.push({ name, inputPath, type });
+    }
+    return results;
+  }, []);

+  // Validation
+  preventNoEntrypoints(config, entrypointInfos);
+  preventDuplicateEntrypointNames(config, entrypointInfos);
+
+  // Import entrypoints to get their config
+  let hasBackground = false;
+  const entrypoints: Entrypoint[] = await Promise.all(
+    entrypointInfos.map(async (info): Promise<Entrypoint> => {
+      const { type } = info;
      switch (type) {
        case 'popup':
-          return await getPopupEntrypoint(config, path);
+          return await getPopupEntrypoint(config, info);
        case 'options':
-          return await getOptionsEntrypoint(config, path);
+          return await getOptionsEntrypoint(config, info);
        case 'background':
          hasBackground = true;
-          return await getBackgroundEntrypoint(config, path);
+          return await getBackgroundEntrypoint(config, info);
        case 'content-script':
-          return await getContentScriptEntrypoint(config, path);
+          return await getContentScriptEntrypoint(config, info);
        case 'unlisted-page':
-          return await getUnlistedPageEntrypoint(config, path);
+          return await getUnlistedPageEntrypoint(config, info);
        case 'unlisted-script':
-          return await getUnlistedScriptEntrypoint(config, path);
+          return await getUnlistedScriptEntrypoint(config, info);
        case 'content-script-style':
          return {
+            ...info,
            type,
-            name: getEntrypointName(config.entrypointsDir, path),
-            inputPath: path,
            outputDir: resolve(config.outDir, CONTENT_SCRIPT_OUT_DIR),
            options: {
              include: undefined,
@@ -89,9 +88,8 @@ export async function findEntrypoints(
          };
        default:
          return {
+            ...info,
            type,
-            name: getEntrypointName(config.entrypointsDir, path),
-            inputPath: path,
            outputDir: config.outDir,
            options: {
              include: undefined,
@@ -102,30 +100,13 @@ export async function findEntrypoints(
    }),
  );

-  const entrypoints = possibleEntrypoints.filter(
-    (entry) => !!entry,
-  ) as Entrypoint[];
-
-  // Report duplicate entrypoint names
-  const existingNames: Record<string, Entrypoint | undefined> = {};
-  entrypoints.forEach((entrypoint) => {
-    const withSameName = existingNames[entrypoint.name];
-    if (withSameName) {
-      throw Error(
-        `Multiple entrypoints with the name "${
-          entrypoint.name
-        }" detected, but only one is allowed: ${[
-          relative(config.root, withSameName.inputPath),
-          relative(config.root, entrypoint.inputPath),
-        ].join(', ')}`,
-      );
-    }
-    existingNames[entrypoint.name] = entrypoint;
-  });
-
  if (config.command === 'serve' && !hasBackground) {
    entrypoints.push(
-      await getBackgroundEntrypoint(config, VIRTUAL_NOOP_BACKGROUND_MODULE_ID),
+      await getBackgroundEntrypoint(config, {
+        inputPath: VIRTUAL_NOOP_BACKGROUND_MODULE_ID,
+        name: 'background',
+        type: 'background',
+      }),
    );
  }

@@ -151,6 +132,50 @@ export async function findEntrypoints(
  return targetEntrypoints;
 }

+interface EntrypointInfo {
+  name: string;
+  inputPath: string;
+  type: Entrypoint['type'];
+}
+
+function preventDuplicateEntrypointNames(
+  config: InternalConfig,
+  files: EntrypointInfo[],
+) {
+  const namesToPaths = files.reduce<Record<string, string[]>>(
+    (map, { name, inputPath }) => {
+      map[name] ??= [];
+      map[name].push(inputPath);
+      return map;
+    },
+    {},
+  );
+  const errorLines = Object.entries(namesToPaths).reduce<string[]>(
+    (lines, [name, absolutePaths]) => {
+      if (absolutePaths.length > 1) {
+        lines.push(`- ${name}`);
+        absolutePaths.forEach((absolutePath) => {
+          lines.push(`  - ${relative(config.root, absolutePath)}`);
+        });
+      }
+      return lines;
+    },
+    [],
+  );
+  if (errorLines.length > 0) {
+    const errorContent = errorLines.join('\n');
+    throw Error(
+      `Multiple entrypoints with the same name detected, only one entrypoint for each name is allowed.\n\n${errorContent}`,
+    );
+  }
+}
+
+function preventNoEntrypoints(config: InternalConfig, files: EntrypointInfo[]) {
+  if (files.length === 0) {
+    throw Error(`No entrypoints found in ${config.entrypointsDir}`);
+  }
+}
+
 function getHtmlBaseOptions(document: Document): BaseEntrypointOptions {
  const options: BaseEntrypointOptions = {};

@@ -177,9 +202,9 @@ function getHtmlBaseOptions(document: Document): BaseEntrypointOptions {
 */
 async function getPopupEntrypoint(
  config: InternalConfig,
-  path: string,
+  { inputPath, name }: EntrypointInfo,
 ): Promise<PopupEntrypoint> {
-  const content = await fs.readFile(path, 'utf-8');
+  const content = await fs.readFile(inputPath, 'utf-8');
  const { document } = parseHTML(content);

  const options: PopupEntrypoint['options'] = getHtmlBaseOptions(document);
@@ -220,7 +245,7 @@ async function getPopupEntrypoint(
    type: 'popup',
    name: 'popup',
    options,
-    inputPath: path,
+    inputPath,
    outputDir: config.outDir,
  };
 }
@@ -231,9 +256,9 @@ async function getPopupEntrypoint(
 */
 async function getOptionsEntrypoint(
  config: InternalConfig,
-  path: string,
+  { inputPath, name }: EntrypointInfo,
 ): Promise<OptionsEntrypoint> {
-  const content = await fs.readFile(path, 'utf-8');
+  const content = await fs.readFile(inputPath, 'utf-8');
  const { document } = parseHTML(content);

  const options: OptionsEntrypoint['options'] = getHtmlBaseOptions(document);
@@ -263,7 +288,7 @@ async function getOptionsEntrypoint(
    type: 'options',
    name: 'options',
    options,
-    inputPath: path,
+    inputPath,
    outputDir: config.outDir,
  };
 }
@@ -274,15 +299,15 @@ async function getOptionsEntrypoint(
 */
 async function getUnlistedPageEntrypoint(
  config: InternalConfig,
-  path: string,
+  { inputPath, name }: EntrypointInfo,
 ): Promise<GenericEntrypoint> {
-  const content = await fs.readFile(path, 'utf-8');
+  const content = await fs.readFile(inputPath, 'utf-8');
  const { document } = parseHTML(content);

  return {
    type: 'unlisted-page',
-    name: getEntrypointName(config.entrypointsDir, path),
-    inputPath: path,
+    name: getEntrypointName(config.entrypointsDir, inputPath),
+    inputPath,
    outputDir: config.outDir,
    options: getHtmlBaseOptions(document),
  };
@@ -294,11 +319,10 @@ async function getUnlistedPageEntrypoint(
 */
 async function getUnlistedScriptEntrypoint(
  config: InternalConfig,
-  path: string,
+  { inputPath, name }: EntrypointInfo,
 ): Promise<GenericEntrypoint> {
-  const name = getEntrypointName(config.entrypointsDir, path);
  const defaultExport = await importEntrypointFile<UnlistedScriptDefinition>(
-    path,
+    inputPath,
    config,
  );
  if (defaultExport == null) {
@@ -311,7 +335,7 @@ async function getUnlistedScriptEntrypoint(
  return {
    type: 'unlisted-script',
    name,
-    inputPath: path,
+    inputPath,
    outputDir: config.outDir,
    options,
  };
@@ -322,13 +346,12 @@ async function getUnlistedScriptEntrypoint(
 */
 async function getBackgroundEntrypoint(
  config: InternalConfig,
-  path: string,
+  { inputPath, name }: EntrypointInfo,
 ): Promise<BackgroundEntrypoint> {
-  const name = 'background';
  let options: Omit<BackgroundDefinition, 'main'> = {};
-  if (path !== VIRTUAL_NOOP_BACKGROUND_MODULE_ID) {
+  if (inputPath !== VIRTUAL_NOOP_BACKGROUND_MODULE_ID) {
    const defaultExport = await importEntrypointFile<BackgroundDefinition>(
-      path,
+      inputPath,
      config,
    );
    if (defaultExport == null) {
@@ -342,7 +365,7 @@ async function getBackgroundEntrypoint(
  return {
    type: 'background',
    name,
-    inputPath: path,
+    inputPath,
    outputDir: config.outDir,
    options: {
      ...options,
@@ -357,11 +380,10 @@ async function getBackgroundEntrypoint(
 */
 async function getContentScriptEntrypoint(
  config: InternalConfig,
-  path: string,
+  { inputPath, name }: EntrypointInfo,
 ): Promise<ContentScriptEntrypoint> {
-  const name = getEntrypointName(config.entrypointsDir, path);
  const { main: _, ...options } =
-    await importEntrypointFile<ContentScriptDefinition>(path, config);
+    await importEntrypointFile<ContentScriptDefinition>(inputPath, config);
  if (options == null) {
    throw Error(
      `${name}: Default export not found, did you forget to call "export default defineContentScript(...)"?`,
@@ -370,13 +392,13 @@ async function getContentScriptEntrypoint(
  return {
    type: 'content-script',
    name,
-    inputPath: path,
+    inputPath,
    outputDir: resolve(config.outDir, CONTENT_SCRIPT_OUT_DIR),
    options,
  };
 }

-const PATH_GLOB_TO_TYPE_MAP: Record<string, Entrypoint['type'] | 'ignored'> = {
+const PATH_GLOB_TO_TYPE_MAP: Record<string, Entrypoint['type']> = {
  'sandbox.html': 'sandbox',
  'sandbox/index.html': 'sandbox',
  '*.sandbox.html': 'sandbox',
@@ -420,13 +442,10 @@ const PATH_GLOB_TO_TYPE_MAP: Record<string, Entrypoint['type'] | 'ignored'> = {

  '*.html': 'unlisted-page',
  '*/index.html': 'unlisted-page',
-  '*.[jt]s': 'unlisted-script',
-  '*/index.ts': 'unlisted-script',
+  '*.[jt]s?(x)': 'unlisted-script',
+  '*/index.[jt]s?(x)': 'unlisted-script',
  [`*.${CSS_EXTENSIONS_PATTERN}`]: 'unlisted-style',
  [`*/index.${CSS_EXTENSIONS_PATTERN}`]: 'unlisted-style',
-
-  // Don't warn about any files in subdirectories, like CSS or JS entrypoints for HTML files or tests
-  '*/**': 'ignored',
 };

 const CONTENT_SCRIPT_OUT_DIR = 'content-scripts';
@@ -6,9 +6,9 @@ import { getEntrypointBundlePath } from '~/core/utils/entrypoints';
 import { getUnimportOptions } from '~/core/utils/unimport';
 import { getEntrypointGlobals, getGlobals } from '~/core/utils/globals';
 import { normalizePath } from '~/core/utils/paths';
-import path from 'node:path';
-import { Message, parseI18nMessages } from '~/core/utils/i18n';
 import { writeFileIfDifferent, getPublicFiles } from '~/core/utils/fs';
+import glob from 'fast-glob';
+import { Message, PREDEFINED_MESSAGES, readMessagesFile } from '~/i18n/node';

 /**
 * Generate and write all the files inside the `InternalConfig.typesDir` directory.
@@ -113,30 +113,38 @@ declare module "wxt/browser" {
  }

  export interface WxtI18n extends I18n.Static {
-{{ overrides }}
+{{ browserOverrides }}
+  }
+}
+
+declare module "wxt/i18n" {
+  export interface WxtMessageSchema {
+    t: {
+{{ translationTOverrides }}
+    };
+    tp: {
+{{ translationTpOverrides }}
+    };
  }
 }
 `;

  let messages: Message[];
  if (defaultLocale) {
-    const defaultLocalePath = path.resolve(
-      config.publicDir,
-      '_locales',
-      defaultLocale,
-      'messages.json',
-    );
-    const content = JSON.parse(await fs.readFile(defaultLocalePath, 'utf-8'));
-    messages = parseI18nMessages(content);
+    const [defaultLocalePath] = await glob(`${defaultLocale}.*`, {
+      cwd: config.localesDir,
+      absolute: true,
+    });
+    messages = await readMessagesFile(defaultLocalePath);
  } else {
-    messages = parseI18nMessages({});
+    messages = PREDEFINED_MESSAGES;
  }

  const overrides = messages.map((message) => {
    return `    /**
-     * ${message.description ?? 'No message description.'}
+     * ${message.entry.description ?? 'No message description.'}
     *
-     * "${message.message}"
+     * "${message.entry.message}"
     */
    getMessage(
      messageName: "${message.name}",
@@ -146,7 +154,22 @@ declare module "wxt/browser" {
  });
  await writeFileIfDifferent(
    filePath,
-    template.replace('{{ overrides }}', overrides.join('\n')),
+    template
+      .replace('{{ browserOverrides }}', overrides.join('\n'))
+      .replace(
+        '{{ translationTOverrides }}',
+        messages
+          .filter((message) => !message.isPlural)
+          .map((message) => `      "${message.name}": any;`)
+          .join('\n'),
+      )
+      .replace(
+        '{{ translationTpOverrides }}',
+        messages
+          .filter((message) => message.isPlural)
+          .map((message) => `      "${message.name}": any;`)
+          .join('\n'),
+      ),
  );

  return filePath;
@@ -180,7 +203,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))}" />`,
@@ -12,7 +12,7 @@ import {
 import path from 'node:path';
 import { createFsCache } from '~/core/utils/cache';
 import consola, { LogLevels } from 'consola';
-import { craeteViteBuilder } from '~/core/builders/vite';
+import { createViteBuilder } from '~/core/builders/vite';
 import defu from 'defu';
 import { NullablyRequired } from '../types';

@@ -37,6 +37,9 @@ export async function getInternalConfig(
      name: 'wxt',
      cwd: inlineConfig.root ?? process.cwd(),
      rcFile: false,
+      jitiOptions: {
+        esmResolve: true,
+      },
    });
    userConfig = loadedConfig ?? {};
    userConfigMetadata = metadata;
@@ -70,6 +73,7 @@ export async function getInternalConfig(
    mergedConfig.entrypointsDir ?? 'entrypoints',
  );
  const publicDir = path.resolve(srcDir, mergedConfig.publicDir ?? 'public');
+  const localesDir = path.resolve(srcDir, mergedConfig.localesDir ?? 'locales');
  const typesDir = path.resolve(wxtDir, 'types');
  const outBaseDir = path.resolve(root, mergedConfig.outDir ?? '.output');
  const outDir = path.resolve(outBaseDir, `${browser}-mv${manifestVersion}`);
@@ -108,6 +112,7 @@ export async function getInternalConfig(
    outBaseDir,
    outDir,
    publicDir,
+    localesDir,
    root,
    runnerConfig,
    srcDir,
@@ -131,7 +136,7 @@ export async function getInternalConfig(
    server,
  };

-  const builder = await craeteViteBuilder(
+  const builder = await createViteBuilder(
    inlineConfig,
    userConfig,
    finalConfig,
@@ -193,6 +198,7 @@ function mergeInlineConfig(
    manifest,
    mode: inlineConfig.mode ?? userConfig.mode,
    publicDir: inlineConfig.publicDir ?? userConfig.publicDir,
+    localesDir: inlineConfig.localesDir ?? userConfig.localesDir,
    runner,
    srcDir: inlineConfig.srcDir ?? userConfig.srcDir,
    outDir: inlineConfig.outDir ?? userConfig.outDir,
@@ -2,11 +2,12 @@ import createJITI, { TransformOptions as JitiTransformOptions } from 'jiti';
 import { InternalConfig } from '~/types';
 import { createUnimport } from 'unimport';
 import fs from 'fs-extra';
-import { resolve } from 'path';
+import { resolve } from 'node:path';
 import { getUnimportOptions } from '~/core/utils/unimport';
 import { removeProjectImportStatements } from '~/core/utils/strings';
 import { normalizePath } from '~/core/utils/paths';
 import { TransformOptions, transformSync } from 'esbuild';
+import { fileURLToPath } from 'node:url';

 /**
 * Get the value from the default export of a `path`.
@@ -45,30 +46,44 @@ export async function importEntrypointFile<T>(
    ['Text:', text, 'No imports:', textNoImports, 'Code:', code].join('\n'),
  );

-  const jiti = createJITI(__filename, {
-    cache: false,
-    debug: config.debug,
-    esmResolve: true,
-    alias: {
-      'webextension-polyfill': resolve(
-        config.root,
-        'node_modules/wxt/dist/virtual/mock-browser.js',
-      ),
+  const jiti = createJITI(
+    typeof __filename !== 'undefined'
+      ? __filename
+      : fileURLToPath(import.meta.url),
+    {
+      cache: false,
+      debug: config.debug,
+      esmResolve: true,
+      alias: {
+        'webextension-polyfill': resolve(
+          config.root,
+          'node_modules/wxt/dist/virtual/mock-browser.js',
+        ),
+      },
+      // Continue using node to load TS files even if `bun run --bun` is detected. Jiti does not
+      // respect the custom transform function when using it's native bun option.
+      experimentalBun: false,
+      // List of extensions to transform with esbuild
+      extensions: [
+        '.ts',
+        '.cts',
+        '.mts',
+        '.tsx',
+        '.js',
+        '.cjs',
+        '.mjs',
+        '.jsx',
+      ],
+      transform(opts) {
+        const isEntrypoint = opts.filename === normalPath;
+        return transformSync(
+          // Use modified source code for entrypoints
+          isEntrypoint ? code : opts.source,
+          getEsbuildOptions(opts),
+        );
+      },
    },
-    // Continue using node to load TS files even if `bun run --bun` is detected. Jiti does not
-    // respect the custom transform function when using it's native bun option.
-    experimentalBun: false,
-    // List of extensions to transform with esbuild
-    extensions: ['.ts', '.cts', '.mts', '.tsx', '.js', '.cjs', '.mjs', '.jsx'],
-    transform(opts) {
-      const isEntrypoint = opts.filename === normalPath;
-      return transformSync(
-        // Use modified source code for entrypoints
-        isEntrypoint ? code : opts.source,
-        getEsbuildOptions(opts),
-      );
-    },
-  });
+  );

  try {
    const res = await jiti(path);
@@ -38,7 +38,7 @@ export async function internalBuild(
  const entrypoints = await findEntrypoints(config);
  config.logger.debug('Detected entrypoints:', entrypoints);
  const groups = groupEntrypoints(entrypoints);
-  const { output } = await rebuild(config, groups, undefined);
+  const { output } = await rebuild(config, entrypoints, groups, undefined);

  // Post-build
  await printBuildSummary(
@@ -1,9 +1,13 @@
-import type { Manifest } from 'webextension-polyfill';
-import { BuildOutput, EntrypointGroup, InternalConfig } from '~/types';
-import { findEntrypoints } from './find-entrypoints';
+import type { Manifest } from '~/browser';
+import {
+  BuildOutput,
+  Entrypoint,
+  EntrypointGroup,
+  InternalConfig,
+} from '~/types';
 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
@@ -14,9 +18,16 @@ import { generateMainfest, writeManifest } from '~/core/utils/manifest';
 * 2. Build the `entrypointGroups` (and copies public files)
 * 3. Generate the latest manifest for all entrypoints
 * 4. Write the new manifest to the file system
+ *
+ * @param config Internal config containing all the project information.
+ * @param allEntrypoints List of entrypoints used to generate the types inside .wxt directory.
+ * @param entrypointGroups The list of entrypoint groups to build.
+ * @param existingOutput The previous output to combine the rebuild results into. An emptry array if
+ *                       this is the first build.
 */
 export async function rebuild(
  config: InternalConfig,
+  allEntrypoints: Entrypoint[],
  entrypointGroups: EntrypointGroup[],
  existingOutput: Omit<BuildOutput, 'manifest'> = {
    steps: [],
@@ -27,7 +38,6 @@ export async function rebuild(
  const spinner = ora(`Preparing...`).start();

  // Update types directory with new files and types
-  const allEntrypoints = await findEntrypoints(config);
  await generateTypesDir(allEntrypoints, config).catch((err) => {
    config.logger.warn('Failed to update .wxt directory:', err);
    // Throw the error if doing a regular build, don't for dev mode.
@@ -41,7 +51,7 @@ export async function rebuild(
    publicAssets: [...existingOutput.publicAssets, ...newOutput.publicAssets],
  };

-  const newManifest = await generateMainfest(
+  const newManifest = await generateManifest(
    allEntrypoints,
    mergedOutput,
    config,
@@ -1,4 +1,4 @@
-import type { Manifest } from 'webextension-polyfill';
+import type { Manifest } from '~/browser';
 import { ContentScriptEntrypoint, InternalConfig } from '~/types';
 import { resolvePerBrowserOption } from './entrypoints';

@@ -1,52 +0,0 @@
-export interface Message {
-  name: string;
-  message: string;
-  description?: string;
-}
-
-const predefinedMessages = {
-  '@@extension_id': {
-    message: '<browser.runtime.id>',
-    description:
-      "The extension or app ID; you might use this string to construct URLs for resources inside the extension. Even unlocalized extensions can use this message.\nNote: You can't use this message in a manifest file.",
-  },
-  '@@ui_locale': {
-    message: '<browser.i18n.getUiLocale()>',
-    description: '',
-  },
-  '@@bidi_dir': {
-    message: '<ltr|rtl>',
-    description:
-      'The text direction for the current locale, either "ltr" for left-to-right languages such as English or "rtl" for right-to-left languages such as Japanese.',
-  },
-  '@@bidi_reversed_dir': {
-    message: '<rtl|ltr>',
-    description:
-      'If the @@bidi_dir is "ltr", then this is "rtl"; otherwise, it\'s "ltr".',
-  },
-  '@@bidi_start_edge': {
-    message: '<left|right>',
-    description:
-      'If the @@bidi_dir is "ltr", then this is "left"; otherwise, it\'s "right".',
-  },
-  '@@bidi_end_edge': {
-    message: '<right|left>',
-    description:
-      'If the @@bidi_dir is "ltr", then this is "right"; otherwise, it\'s "left".',
-  },
-};
-
-/**
- * Get a list of all messages and their metadata from JSON file contents.
- *
- * @param messagesJson The contents of a `_locales/en/messages.json` file.
- */
-export function parseI18nMessages(messagesJson: object): Message[] {
-  return Object.entries({
-    ...predefinedMessages,
-    ...messagesJson,
-  }).map<Message>(([name, details]) => ({
-    name,
-    ...details,
-  }));
-}
@@ -1,4 +1,4 @@
-import type { Manifest } from 'webextension-polyfill';
+import type { Manifest } from '~/browser';
 import {
  Entrypoint,
  BackgroundEntrypoint,
@@ -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',
+    );
+  }
+  const 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: 'Alt+R',
+        },
+      },
+    };
+  }
  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);
@@ -483,7 +503,10 @@ export function getContentScriptCssWebAccessibleResources(
    } else {
      resources.push({
        resources: [cssFile],
-        matches: script.options.matches,
+        matches: resolvePerBrowserOption(
+          script.options.matches,
+          config.browser,
+        ).map((matchPattern) => stripPathFromMatchPattern(matchPattern)),
      });
    }
  });
@@ -527,3 +550,15 @@ function addHostPermission(
  if (manifest.host_permissions.includes(hostPermission)) return;
  manifest.host_permissions.push(hostPermission);
 }
+
+/**
+ * - "<all_urls>" &rarr; "<all_urls>"
+ * - "*://play.google.com/books/*" &rarr; "*://play.google.com/*"
+ */
+export function stripPathFromMatchPattern(pattern: string) {
+  const protocolSepIndex = pattern.indexOf('://');
+  if (protocolSepIndex === -1) return pattern;
+
+  const startOfPath = pattern.indexOf('/', protocolSepIndex + 3);
+  return pattern.substring(0, startOfPath) + '/*';
+}
@@ -22,8 +22,7 @@ export function removeImportStatements(text: string): string {
 export function removeProjectImportStatements(text: string): string {
  const noImports = removeImportStatements(text);

-  return `import { defineContentScript, defineBackground } from 'wxt/client';
-import { defineUnlistedScript } from 'wxt/sandbox';
+  return `import { defineUnlistedScript, defineContentScript, defineBackground } from 'wxt/sandbox';

 ${noImports}`;
 }
@@ -4,7 +4,7 @@
 import { resolve } from 'path';
 import { faker } from '@faker-js/faker';
 import merge from 'lodash.merge';
-import type { Manifest } from 'webextension-polyfill';
+import type { Manifest } from '~/browser';
 import {
  FsCache,
  InternalConfig,
@@ -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,12 +205,13 @@ export const fakeInternalConfig = fakeObjectCreator<InternalConfig>(() => {
    fsCache: mock<FsCache>(),
    imports: {},
    logger: mock(),
-    manifest: fakeManifest(),
+    manifest: fakeUserManifest(),
    manifestVersion,
    mode,
    outBaseDir: fakeDir(),
    outDir: fakeDir(),
    publicDir: fakeDir(),
+    localesDir: fakeDir(),
    root: fakeDir(),
    runnerConfig: {
      config: {},
@@ -222,3 +241,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),
+}));
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Aaron Klinker	98bc1f2cd1	Bump version to alpha2	2024-01-14 16:27:38 -06:00
Aaron Klinker	f6a066f166	Fix tests	2024-01-14 16:26:54 -06:00
Aaron Klinker	c20478cde2	Bump version to 0.14.2-alpha1	2024-01-14 16:19:54 -06:00
Aaron Klinker	ebd50079a7	Cleanup unsed imports	2024-01-14 16:18:47 -06:00
Aaron Klinker	b17bd87865	Add docs	2024-01-14 16:18:19 -06:00
Aaron Klinker	e8b471e23f	Improve typing and add tests for it	2024-01-14 15:05:52 -06:00
Aaron Klinker	32ffca4168	Add client tests	2024-01-14 14:49:15 -06:00
Aaron Klinker	e9c573d5a1	Implement and generate types for `wxt/i18n`	2024-01-12 23:58:55 -06:00
Aaron Klinker	ae5126d726	Update lockfile	2024-01-12 22:49:13 -06:00
Aaron Klinker	24a77ca9b5	Add i18n module to named export list	2024-01-12 22:49:03 -06:00
Aaron Klinker	174cbbc5eb	Add i18n module to auto-imports	2024-01-12 22:45:58 -06:00
Aaron Klinker	607c70dd56	Build `wxt/i18n`	2024-01-12 22:45:41 -06:00
Aaron Klinker	616d012326	Update demo code for testing	2024-01-12 22:45:18 -06:00
Aaron Klinker	75b6ca7172	Add conversion code and tests	2024-01-12 22:45:04 -06:00
Aaron Klinker	1497b3099c	Move demo files	2024-01-12 22:44:33 -06:00
Aaron Klinker	a329e24818	chore: Fix typo in function name	2024-01-12 13:03:43 -06:00
Aaron	249cf63da8	perf: Only call `findEntrypoint` once per build (#342 )	2024-01-12 13:02:44 -06:00
Aaron Klinker	70a496108a	chore: Update templates to `^0.14.0`	2024-01-12 08:53:32 -06:00
GitHub Actions	214889e052	chore(release): v0.14.1	2024-01-12 14:50:29 +00:00
Aaron Klinker	b6ab7a9567	fix: Use `Alt+R`/`Opt+R` to reload extension during development This closes #339	2024-01-12 08:47:21 -06:00
Aaron Klinker	1ceb9e2e80	Add missing breaking change to changelog	2024-01-11 17:00:43 -06:00
Aaron Klinker	15ea81514f	Update changelog	2024-01-11 13:28:41 -06:00
GitHub Actions	21d4e6dede	chore(release): v0.14.0	2024-01-11 17:17:23 +00:00
Aaron	5343430c0f	feat!: Refactor content script UI functions and add helper for "integrated" UIs (#333 ) BREAKING CHANGES: Several APIs/options have been renamed: - `type: "inline" \| "overlay" \| "modal"` has been changed to `position: "inline" \| "overlay" \| "modal"` - `createContentScriptUi({ ... })` → `createShadowRootUi({ ... })` - `createContentScriptIframe({ ... })` → `createIframeUi({ ... })` - `onRemove` is now called *before* the UI is removed from the DOM, previously it was called after the UI was removed	2024-01-10 20:48:17 -06:00
GitHub Actions	8c834835c4	chore(release): v0.13.5	2024-01-08 20:10:48 +00:00
Aaron	9a2cc18f64	chore: Update bug report template	2024-01-08 13:50:20 -06:00
Aaron Klinker	8683bd4b77	docs: Add section about customizing other browser options during development	2024-01-08 13:42:50 -06:00
Aaron	dca52864bb	fix: Strip path from `web_accessible_resources[0].matches` (#332 )	2024-01-08 13:17:31 -06:00
GitHub Actions	0c5643f648	chore(release): v0.13.4	2024-01-07 16:51:31 +00:00
Aaron Klinker	b7cdf1597c	fix: Disable minification during development This closes #328	2024-01-07 10:48:25 -06:00
Aaron Klinker	2770974261	chore: Use `const` instead of `let`	2024-01-07 10:46:49 -06:00
GitHub Actions	ab6a34afb6	chore(release): v0.13.3	2024-01-05 05:14:03 +00:00
Aaron	b0eb7da9b4	chore: Refactor manifest generation E2E tests to unit tests (#323 )	2024-01-02 17:05:23 -06:00
Aaron	4f649fc872	feat(DX): Add `ctrl+E`/`cmd+E` shortcut to reload extension during development (#322 )	2024-01-02 12:06:22 -06:00
dependabot[bot]	1af64aa02f	chore(deps-dev): bump vitepress from 1.0.0-rc.31 to 1.0.0-rc.34 (#316 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-01-01 14:33:18 -06:00
dependabot[bot]	c35acff259	chore(deps-dev): bump prettier from 3.1.0 to 3.1.1 (#318 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-01-01 14:31:32 -06:00
dependabot[bot]	995d4f8080	chore(deps-dev): bump tsx from 4.6.2 to 4.7.0 (#320 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-01-01 14:31:16 -06:00
GitHub Actions	b7e2aa3d8f	chore(release): v0.13.2	2024-01-01 16:06:12 +00:00
冯不游	e347f4529f	feat: Add `isolateEvents` option to `createContentScripUi` (#313 ) Co-authored-by: Aaron <aaronklinker1@gmail.com>	2024-01-01 10:01:33 -06:00
李志博	3d9683418d	Upload a Chinese dubbing plugin for Youtube. (#314 ) Co-authored-by: Aaron <aaronklinker1@gmail.com>	2024-01-01 09:45:44 -06:00
Aaron	bdce363eed	chore: Re-enable coverage (#312 )	2023-12-29 17:28:35 -06:00
Aaron	e7775f291a	docs: Use example tags to automate relevant example lists (#311 )	2023-12-29 17:25:46 -06:00
Aaron	59f6a28c65	chore: Upgrade template dependencies (#310 )	2023-12-29 12:25:13 -06:00
Aaron	f7534464bc	chore: Update templates to `^0.13.0` (#309 )	2023-12-29 12:14:05 -06:00
Aaron	01445fb1da	docs: Add example for setting up custom panels/panes in devtools (#308 )	2023-12-29 12:08:33 -06:00
Aaron Klinker	1360eb7c01	docs: Update content script entrypoint docs	2023-12-29 02:01:53 -06:00
Aaron Klinker	c99a281169	docs: Update unlisted pages/scripts description	2023-12-29 01:54:39 -06:00
Aaron Klinker	76e63e24c0	docs: Remove duplicate `entrypoints/` path	2023-12-29 01:51:26 -06:00
GitHub Actions	f5ba1173da	chore(release): v0.13.1	2023-12-29 07:39:32 +00:00
Aaron	12079e6ffc	chore: Update `scripts/build.ts` show current build step in progress, not completed count (#306 )	2023-12-29 01:21:18 -06:00
Aaron	ff6740d429	fix: Ship `vite/client` types internally for proper resolution using PNPM (#304 )	2023-12-29 01:21:05 -06:00
Aaron	e6657cb533	fix(storage): Support multiple `:` characters in storage keys (#303 )	2023-12-29 00:40:47 -06:00
Aaron Klinker	2ad099bf7e	docs: General fixes and improvements	2023-12-27 12:32:59 -06:00
Aaron Klinker	6421ab34a4	docs: Reorder guide	2023-12-27 12:32:45 -06:00
Aaron Klinker	8919c4015a	Update changelog	2023-12-27 11:07:57 -06:00
GitHub Actions	712f2ed4ac	chore(release): v0.13.0	2023-12-27 17:05:45 +00:00
Aaron	d1b9e5ded6	feat!: New `wxt/storage` APIs (#300 ) BREAKING CHANGE: `wxt/storage` no longer relies on `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.	2023-12-27 11:00:10 -06:00
GitHub Actions	86182044d1	chore(release): v0.12.5	2023-12-24 14:28:21 +00:00
Aaron	e1f181356c	fix: Correct import in dev-only, noop background (#298 )	2023-12-24 08:24:53 -06:00
GitHub Actions	5f241cf407	chore(release): v0.12.4	2023-12-23 15:53:43 +00:00
Aaron	b4a2cf4cb2	fix: Disable Vite CJS warnings (#296 )	2023-12-23 09:35:43 -06:00
GitHub Actions	aea137a3a1	chore(release): v0.12.3	2023-12-23 04:26:47 +00:00
Aaron	ad0e8e4144	fix: Correctly mock `webextension-polyfill` for Vitest (#294 )	2023-12-22 22:21:09 -06:00
GitHub Actions	7fd5752ef1	chore(release): v0.12.2	2023-12-19 17:48:24 +00:00
Aaron	1a8b7ff635	feat: Support PNPM without hoisting dependencies (#291 )	2023-12-19 11:42:20 -06:00
GitHub Actions	fe3ca0fcbd	chore(release): v0.12.1	2023-12-16 17:24:16 +00:00
Aaron	f49ee9f005	fix: Fix `package.json` lint errors (#290 )	2023-12-16 11:18:16 -06:00
Aaron	961440c0ac	fix: Upgrade `@webext-core/match-patterns` to `1.0.3` (#289 )	2023-12-16 11:07:18 -06:00
Aaron	9b562b0ca8	chore: Upgrade templates to `wxt@^0.12.0` (#285 )	2023-12-13 16:21:52 -06:00
Aaron Klinker	7b2563b2dc	Update changelog with breaking changes	2023-12-13 16:02:24 -06:00
GitHub Actions	63f507ecf5	chore(release): v0.12.0	2023-12-13 21:57:34 +00:00
Aaron	0a88955394	fix: Throw error when no entrypoints are found (#283 )	2023-12-13 15:50:28 -06:00
Aaron Klinker	291d25b675	docs: Fix dead links	2023-12-13 15:50:09 -06:00
Aaron	6f902cc598	docs: Improve content script UI guide (#272 )	2023-12-13 15:43:40 -06:00
Aaron	fde488ac82	feat!: Add support for "main world" content scripts (#284 ) BREAKING CHANGE: `defineContentScript` and `defineBackground` are now exported from `wxt/sandbox` instead of `wxt/client`. If you use auto-imports, no changes are required. If you have disabled auto-imports, you'll need to manually update your import statements.	2023-12-13 15:41:39 -06:00
Aaron	0873c24ad8	chore: Convert WXT CLI to an ESM binary (#279 )	2023-12-12 14:44:04 -06:00
Aaron	7c02497148	fix: Only use type imports for Vite (#278 )	2023-12-12 14:24:42 -06:00
GitHub Actions	25441a3b97	chore(release): v0.11.2	2023-12-12 19:24:47 +00:00
Aaron	f1cf866fe1	fix: Improve duplicate entrypoint name detection and catch the error before loading their config (#276 )	2023-12-12 13:22:09 -06:00
Aaron	d92a126489	fix: Discover `.js`, `.jsx`, and `.tsx` unlisted scripts correctly (#274 )	2023-12-12 12:24:38 -06:00
Aaron Klinker	bcb93afe4e	chore: Add missing navigation item	2023-12-09 23:37:29 -06:00
Aaron	21cf3642cb	docs: Improve content script UI docs (#268 )	2023-12-09 23:36:35 -06:00
Andrew Walsh	2ef28ec0c4	Update content-scripts.md (#266 )	2023-12-09 23:33:59 -06:00
Aaron	59094c9af3	chore: Update sSolid template to vite 5 (#265 )	2023-12-07 23:05:08 -06:00