chore(release): v0.17.0

Related to #456.

.github/actions/setup/action.yml

@@ -4,7 +4,7 @@ runs:
   using: composite
   steps:
     - name: Setup PNPM
-      uses: pnpm/action-setup@v2
+      uses: pnpm/action-setup@v3
       with:
         version: 8
     - name: Setup NodeJS

.github/workflows/release.yml

@@ -5,6 +5,7 @@ on:
 jobs:
   validate:
     uses: './.github/workflows/validate.yml'
+    secrets: inherit
 
   publish:
     runs-on: ubuntu-22.04

.github/workflows/sync-releases.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-22.04
     steps:
       - uses: actions/checkout@v4
-      - uses: pnpm/action-setup@v2
+      - uses: pnpm/action-setup@v3
         with:
           version: 8
       - uses: actions/setup-node@v4

CHANGELOG.md

@@ -1,5 +1,93 @@
 # Changelog
 
+## v0.17.0
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.16.11...v0.17.0)
+
+### 🚀 Enhancements
+
+- **storage:** ⚠️  Improved support for default values on storage items ([#477](https://github.com/wxt-dev/wxt/pull/477))
+
+### 🩹 Fixes
+
+- **storage:** ⚠️  Only run migrations when the extension is updated ([#478](https://github.com/wxt-dev/wxt/pull/478))
+- Improve dev mode for content scripts registered at runtime ([#474](https://github.com/wxt-dev/wxt/pull/474))
+
+### 📖 Documentation
+
+- **storage:** Update docs ([91fc41c](https://github.com/wxt-dev/wxt/commit/91fc41c))
+
+#### ⚠️ Breaking Changes
+
+- **storage:** ⚠️  Improved support for default values on storage items ([#477](https://github.com/wxt-dev/wxt/pull/477))
+- **storage:** ⚠️  Only run migrations when the extension is updated ([#478](https://github.com/wxt-dev/wxt/pull/478))
+
+## v0.16.11
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.16.10...v0.16.11)
+
+### 🩹 Fixes
+
+- Output main JS file for HTML entrypoints to chunks directory ([#473](https://github.com/wxt-dev/wxt/pull/473))
+
+### 🏡 Chore
+
+- **e2e:** Remove log ([4fda203](https://github.com/wxt-dev/wxt/commit/4fda203))
+
+### 🤖 CI
+
+- Fix codecov warning in release workflow ([7c6973f](https://github.com/wxt-dev/wxt/commit/7c6973f))
+- Upgrade `pnpm/action-setup` to v3 ([905bfc7](https://github.com/wxt-dev/wxt/commit/905bfc7))
+
+## v0.16.10
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.16.9...v0.16.10)
+
+### 🚀 Enhancements
+
+- Customize when content scripts are registered, in the manifest or at runtime ([#471](https://github.com/wxt-dev/wxt/pull/471))
+
+### 🩹 Fixes
+
+- Don't assume react when importing JSX entrypoints during build ([#470](https://github.com/wxt-dev/wxt/pull/470))
+- Respect `configFile` option ([#472](https://github.com/wxt-dev/wxt/pull/472))
+
+## v0.16.9
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.16.8...v0.16.9)
+
+### 🚀 Enhancements
+
+- Support setting side panel options in HTML file ([#468](https://github.com/wxt-dev/wxt/pull/468))
+
+### 🩹 Fixes
+
+- Fix order of ShadowRootUI hooks calling ([#459](https://github.com/wxt-dev/wxt/pull/459))
+
+### 📖 Documentation
+
+- Add wrapper div to react's `createShadowRootUi` example ([bc24ea4](https://github.com/wxt-dev/wxt/commit/bc24ea4))
+
+### 🏡 Chore
+
+- Simplify entrypoint types ([#464](https://github.com/wxt-dev/wxt/pull/464))
+
+### ❤️ Contributors
+
+- Okou ([@ookkoouu](https://github.com/ookkoouu))
+
+## v0.16.8
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.16.7...v0.16.8)
+
+### 🩹 Fixes
+
+- Watch files outside project root during development ([#454](https://github.com/wxt-dev/wxt/pull/454))
+
+### 📖 Documentation
+
+- Add loading and error states for "Who's using WXT" section ([447a48f](https://github.com/wxt-dev/wxt/commit/447a48f))
+
 ## v0.16.7
 
 [compare changes](https://github.com/wxt-dev/wxt/compare/v0.16.6...v0.16.7)
@@ -47,8 +135,8 @@
 
 ### ❤️ Contributors
 
-- Lionelhorn 
-- Okou
+- Lionelhorn ([@Lionelhorn](https://github.com/Lionelhorn))
+- Okou ([@ookkoouu](https://github.com/ookkoouu))
 
 ## v0.16.5
 

docs/.vitepress/components/UsingWxtSection.vue

@@ -20,11 +20,12 @@ const chromeExtensionIds = [
   'agjnjboanicjcpenljmaaigopkgdnihi', // PreMiD
 ];
 
-const { data } = useListExtensionDetails(chromeExtensionIds);
+const { data, err, isLoading } = useListExtensionDetails(chromeExtensionIds);
 const sortedExtensions = computed(() => {
   if (!data.value?.length) return [];
 
   return [...data.value]
+    .filter((item) => item != null)
     .map((item) => ({
       ...item,
       // Sort based on the user count weighted by the rating
@@ -49,7 +50,16 @@ function getStoreUrl(extension: ChromeExtension) {
         Battle tested and ready for production. Explore chrome extensions made
         with WXT.
       </p>
-      <ul>
+      <p v-if="isLoading" style="text-align: center; opacity: 50%">
+        Loading...
+      </p>
+      <p
+        v-else-if="err || sortedExtensions.length === 0"
+        style="text-align: center; opacity: 50%"
+      >
+        Failed to load extension details.
+      </p>
+      <ul v-else>
         <li
           v-for="extension of sortedExtensions"
           :key="extension.id"

docs/.vitepress/composables/useListExtensionDetails.ts

@@ -26,6 +26,7 @@ const query = `query ${operationName}($ids:[String!]!) {
 export default function (ids: string[]) {
   const data = ref<ChromeExtension[]>();
   const err = ref<unknown>();
+  const isLoading = ref(true);
 
   fetch('https://queue.wxt.dev/api', {
     method: 'POST',
@@ -36,6 +37,7 @@ export default function (ids: string[]) {
     }),
   })
     .then(async (res) => {
+      isLoading.value = false;
       const {
         data: { chromeExtensions },
       } = await res.json();
@@ -43,6 +45,7 @@ export default function (ids: string[]) {
       err.value = undefined;
     })
     .catch((error) => {
+      isLoading.value = false;
       console.error(error);
       data.value = undefined;
       err.value = error;
@@ -51,5 +54,6 @@ export default function (ids: string[]) {
   return {
     data,
     err,
+    isLoading,
   };
 }

docs/entrypoints/content-scripts.md

@@ -37,6 +37,9 @@ export default defineContentScript({
   // Configure how CSS is injected onto the page
   cssInjectionMode: undefined | "manifest" | "manual" | "ui",
 
+  // Configure how/when content script will be registered
+  registration: undefined | "manifest" | "runtime",
+
   main(ctx) {
     // Executed when content script is loaded
   },

docs/entrypoints/sidepanel.md

@@ -2,6 +2,8 @@
 
 [Chrome Docs](https://developer.chrome.com/docs/extensions/reference/sidePanel/) • [Firefox Docs](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Sidebars)
 
+In Chrome, side panels use the "side_panel" API, while Firefox uses the "sidebar_action" API.
+
 :::warning
 Chrome added support for sidepanels in Manifest V3, they are not available in Manfiest V2.
 :::
@@ -25,7 +27,17 @@ Chrome added support for sidepanels in Manifest V3, they are not available in Ma
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Title</title>
+    <title>Default Side Panel Title</title>
+    <meta
+      name="manifest.default_icon"
+      content="{
+        16: '/icon-16.png',
+        24: '/icon-24.png',
+        ...
+      }"
+    />
+    <meta name="manifest.open_at_install" content="true|false" />
+    <meta name="manifest.browser_style" content="true|false" />
     <!-- Set include/exclude if the page should be removed from some builds -->
     <meta name="manifest.include" content="['chrome', ...]" />
     <meta name="manifest.exclude" content="['chrome', ...]" />

docs/guide/content-script-ui.md

@@ -157,7 +157,7 @@ export default defineContentScript({
 
 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.
+You can control how CSS is injected for an integrated content script UI with the [`cssInjectionMode`](/api/wxt/interfaces/BaseContentScriptEntrypointOptions#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
 
@@ -168,7 +168,7 @@ WXT's [`createShadowRootUi`](/api/wxt/client/functions/createShadowRootUi) abstr
 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`
+2. Set [`cssInjectionMode: "ui"`](/api/wxt/interfaces/BaseContentScriptEntrypointOptions#cssinjectionmode) inside `defineContentScript`
 3. Define your UI with `createShadowRootUi()`
 4. Mount the UI so it is visible to users
 
@@ -253,8 +253,12 @@ export default defineContentScript({
       name: 'example-ui',
       position: 'inline',
       onMount: (container) => {
+        // Container is a body, and React warns when creating a root on the body, so create a wrapper div
+        const app = document.createElement('div');
+        container.append(app);
+
         // Create a root on the UI container and render a component
-        const root = ReactDOM.createRoot(container);
+        const root = ReactDOM.createRoot(app);
         root.render(<App />);
         return root;
       },

docs/guide/storage.md

@@ -1,3 +1,7 @@
+---
+outline: deep
+---
+
 # Storage API
 
 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:
@@ -35,6 +39,8 @@ await storage.watch<number>(
 await storage.getMeta<{ v: number }>('local:installDate');
 ```
 
+For a full list of methods available, see the [API reference](/api/wxt/storage/interfaces/WxtStorage).
+
 ## Watchers
 
 To listen for storage changes, use the `storage.watch` function. It lets you setup a listener for a single key:
@@ -58,7 +64,7 @@ unwatch();
 
 `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:
+[Other than versioning](#versioning), you are responsible for managing a field's metadata:
 
 ```ts
 await Promise.all([
@@ -116,7 +122,9 @@ const unwatch = showChangelogOnUpdate.watch(() => {
 });
 ```
 
-### Versioning and Migrations
+For a full list of properties and methods available, see the [API reference](/api/wxt/storage/interfaces/WxtStorageItem).
+
+### Versioning
 
 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.
 
@@ -252,3 +260,30 @@ export const ignoredWebsites = storage.defineItem<IgnoredWebsiteV2[]>( // [!code
 ```
 
 :::
+
+### Running Migrations
+
+To run migrations, you have two options:
+
+1. Import all versioned storage items into your background script and they will run automatically whenever your extension updates
+2. Manually call `item.migrate()`
+
+The first approach is recommended. To make importing all your storage items easy, you can define all of them in a single file, `utils/storage.ts`, and import that file into your background entrypoint:
+
+```ts
+// utils/storage.ts
+export countStorage = storage.defineItem(...);
+export themeStorage = storage.defineItem(...);
+export someOtherStorage = storage.defineItem(...);
+```
+
+```ts
+// entrypoints/background.ts
+import '@/utils/storage'; // This import runs migrations on updates
+
+export default defineBackground({
+  // ...
+});
+```
+
+> When you call `storage.defineItem`, a `browser.runtime.onInstalled` listener is added. `onInstalled` listeners are only triggered in the background, which is why you must import them into the background.

e2e/tests/analysis.test.ts

@@ -7,7 +7,7 @@ describe('Analysis', () => {
     resetBundleIncrement();
   });
 
-  it('should outptut a stats.html with no part files by default', async () => {
+  it('should output a stats.html with no part files by default', async () => {
     const project = new TestProject();
     project.addFile('entrypoints/popup.html');
     project.addFile('entrypoints/options.html');
@@ -84,7 +84,6 @@ describe('Analysis', () => {
         keepArtifacts: true,
       },
     });
-    console.log(project.root);
 
     expect(await project.fileExists('stats/bundle.html')).toBe(true);
     expect(await project.fileExists('stats/bundle-0.json')).toBe(true);

e2e/tests/output-structure.test.ts

@@ -270,43 +270,43 @@ describe('Output Directory Structure', () => {
 
     expect(await project.serializeFile('.output/chrome-mv3/background.js'))
       .toMatchInlineSnapshot(`
-      ".output/chrome-mv3/background.js
-      ----------------------------------------
-      import { l as logHello } from "./chunks/log-bezs0tt4.js";
-      function defineBackground(arg) {
-        if (typeof arg === "function")
-          return { main: arg };
-        return arg;
-      }
-      const definition = defineBackground({
-        type: "module",
-        main() {
-          logHello("background");
+        ".output/chrome-mv3/background.js
+        ----------------------------------------
+        import { l as logHello } from "./chunks/log-bezs0tt4.js";
+        function defineBackground(arg) {
+          if (typeof arg === "function")
+            return { main: arg };
+          return arg;
         }
-      });
-      chrome;
-      function print(method, ...args) {
-        return;
-      }
-      var logger = {
-        debug: (...args) => print(console.debug, ...args),
-        log: (...args) => print(console.log, ...args),
-        warn: (...args) => print(console.warn, ...args),
-        error: (...args) => print(console.error, ...args)
-      };
-      try {
-        const res = definition.main();
-        if (res instanceof Promise) {
-          console.warn(
-            "The background's main() function return a promise, but it must be synchonous"
-          );
+        const definition = defineBackground({
+          type: "module",
+          main() {
+            logHello("background");
+          }
+        });
+        chrome;
+        function print(method, ...args) {
+          return;
         }
-      } catch (err) {
-        logger.error("The background crashed on startup!");
-        throw err;
-      }
-      "
-    `);
+        var logger = {
+          debug: (...args) => print(console.debug, ...args),
+          log: (...args) => print(console.log, ...args),
+          warn: (...args) => print(console.warn, ...args),
+          error: (...args) => print(console.error, ...args)
+        };
+        try {
+          const res = definition.main();
+          if (res instanceof Promise) {
+            console.warn(
+              "The background's main() function return a promise, but it must be synchronous"
+            );
+          }
+        } catch (err) {
+          logger.error("The background crashed on startup!");
+          throw err;
+        }
+        "
+      `);
   });
 
   it('should generate IIFE background script when type=undefined', async () => {
@@ -381,7 +381,7 @@ describe('Output Directory Structure', () => {
             const res = definition.main();
             if (res instanceof Promise) {
               console.warn(
-                "The background's main() function return a promise, but it must be synchonous"
+                "The background's main() function return a promise, but it must be synchronous"
               );
             }
           } catch (err) {

e2e/tests/user-config.test.ts

@@ -107,4 +107,29 @@ describe('User Config', () => {
     });
     expect(withoutPolyfill).not.toBe(withPolyfill);
   });
+
+  it('should respect changing config files', async () => {
+    const project = new TestProject();
+    project.addFile(
+      'src/entrypoints/background.ts',
+      `export default defineBackground(
+        () => console.log('Hello background'),
+      );`,
+    );
+    project.addFile(
+      'test.config.ts',
+      `import { defineConfig } from 'wxt';
+      
+      export default defineConfig({
+        outDir: ".custom-output",
+        srcDir: "src",
+      });`,
+    );
+
+    await project.build({ configFile: 'test.config.ts' });
+
+    expect(
+      await project.fileExists('.custom-output/chrome-mv3/background.js'),
+    ).toBe(true);
+  });
 });

package.json

@@ -1,7 +1,7 @@
 {
   "name": "wxt",
   "type": "module",
-  "version": "0.16.7",
+  "version": "0.17.0",
   "description": "Next gen framework for developing web extensions",
   "engines": {
     "node": ">=18",

src/__tests__/storage.test.ts

@@ -1,7 +1,14 @@
 import { fakeBrowser } from '@webext-core/fake-browser';
-import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { describe, it, expect, beforeEach, vi, expectTypeOf } from 'vitest';
 import { browser } from '~/browser';
-import { storage } from '~/storage';
+import { WxtStorageItem, storage } from '~/storage';
+
+async function triggerUpdate() {
+  await fakeBrowser.runtime.onInstalled.trigger({
+    reason: 'update',
+    temporary: false,
+  });
+}
 
 describe('Storage Utils', () => {
   beforeEach(() => {
@@ -384,417 +391,466 @@ describe('Storage Utils', () => {
           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();
-          });
-        });
-      });
     },
   );
+
+  describe('defineItem', () => {
+    describe('versioning', () => {
+      it('should migrate values to the latest when a version upgrade is detected', async () => {
+        await fakeBrowser.storage.local.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 }>(`local:count`, {
+          defaultValue: 0,
+          version: 3,
+          migrations: {
+            2: migrateToV2,
+            3: migrateToV3,
+          },
+        });
+        await triggerUpdate();
+
+        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 }>(`local:count`, {
+          defaultValue: 0,
+          version: 3,
+          migrations: {
+            2: migrateToV2,
+            3: migrateToV3,
+          },
+        });
+        await triggerUpdate();
+
+        const actualValue = await item.getValue();
+        const actualMeta = await item.getMeta();
+
+        expect(actualValue).toEqual(0);
+        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.local.set({
+          count: 2,
+        });
+        const migrateToV2 = vi.fn((oldCount) => oldCount * 2);
+
+        const item = storage.defineItem<number, { v: number }>(`local:count`, {
+          defaultValue: 0,
+          version: 2,
+          migrations: {
+            2: migrateToV2,
+          },
+        });
+        await triggerUpdate();
+
+        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.local.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 }>(`local:count`, {
+          defaultValue: 0,
+          version: 3,
+          migrations: {
+            2: migrateToV2,
+            3: migrateToV3,
+          },
+        });
+        await triggerUpdate();
+
+        expect(migrateToV2).not.toBeCalled();
+        expect(migrateToV3).not.toBeCalled();
+      });
+
+      it('should skip missing migration functions', async () => {
+        await fakeBrowser.storage.local.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 }>(`local:count`, {
+          defaultValue: 0,
+          version: 3,
+          migrations: {
+            1: migrateToV1,
+            3: migrateToV3,
+          },
+        });
+        await triggerUpdate();
+
+        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.local.set({
+          count: 0,
+          count$: { v: prevVersion },
+        });
+
+        const item = storage.defineItem(`local:count`, {
+          defaultValue: 0,
+          version: nextVersion,
+        });
+        await triggerUpdate();
+
+        await expect(item.migrate()).rejects.toThrow(
+          'Version downgrade detected (v2 -> v1) for "local:count"',
+        );
+      });
+    });
+
+    describe('getValue', () => {
+      it('should return the value from storage', async () => {
+        const expected = 2;
+        const item = storage.defineItem<number>(`local:count`);
+        await fakeBrowser.storage.local.set({ count: expected });
+
+        const actual = await item.getValue();
+
+        expect(actual).toBe(expected);
+      });
+
+      it('should return null if missing', async () => {
+        const item = storage.defineItem<number>(`local: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(`local: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 }>(`local:count`);
+        await fakeBrowser.storage.local.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 }>(`local: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>(`local: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>(`local: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 }>(
+          `local: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 }>(
+          `local:count`,
+        );
+        await fakeBrowser.storage.local.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(`local:count`);
+        await fakeBrowser.storage.local.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(`local:count`);
+        const expected = { v: 1 };
+        await fakeBrowser.storage.local.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(`local:count`);
+        await fakeBrowser.storage.local.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 }>(`local:count`);
+        await fakeBrowser.storage.local.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 }>(
+          `local:count`,
+        );
+        await fakeBrowser.storage.local.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(`local:key`);
+        const cb = vi.fn();
+
+        item.watch(cb);
+        await storage.setItem(`local:not-the-key`, '123');
+
+        expect(cb).not.toBeCalled();
+      });
+
+      it("should not trigger if the value doesn't change", async () => {
+        const item = storage.defineItem(`local: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(`local: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 use the default value for the newValue when the item is removed', async () => {
+        const defaultValue = 'default';
+        const item = storage.defineItem<string>(`local:key`, {
+          defaultValue,
+        });
+        const cb = vi.fn();
+        const oldValue = '123';
+        await item.setValue(oldValue);
+
+        item.watch(cb);
+        await item.removeValue();
+
+        expect(cb).toBeCalledTimes(1);
+        expect(cb).toBeCalledWith(defaultValue, oldValue);
+      });
+
+      it("should use the default value for the oldItem when the item didn't exist in storage yet", async () => {
+        const defaultValue = 'default';
+        const item = storage.defineItem<string>(`local:key`, {
+          defaultValue,
+        });
+        const cb = vi.fn();
+        const newValue = '123';
+        await item.removeValue();
+
+        item.watch(cb);
+        await item.setValue(newValue);
+
+        expect(cb).toBeCalledTimes(1);
+        expect(cb).toBeCalledWith(newValue, defaultValue);
+      });
+
+      it('should remove the listener when calling the returned function', async () => {
+        const item = storage.defineItem(`local: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(`local:key`);
+        const cb = vi.fn();
+
+        item.watch(cb);
+        storage.unwatch();
+        await item.setValue('123');
+
+        expect(cb).not.toBeCalled();
+      });
+    });
+
+    describe('defaultValue', () => {
+      it('should return the default value when provided', () => {
+        const defaultValue = 123;
+        const item = storage.defineItem(`local:test`, {
+          defaultValue,
+        });
+
+        expect(item.defaultValue).toBe(defaultValue);
+      });
+
+      it('should return null when not provided', () => {
+        const item = storage.defineItem<number>(`local:test`);
+
+        expect(item.defaultValue).toBeNull();
+      });
+    });
+
+    describe('types', () => {
+      it('should define a nullable value when options are not passed', () => {
+        const item = storage.defineItem<number>(`local:test`);
+        expectTypeOf(item).toEqualTypeOf<WxtStorageItem<number | null, {}>>();
+      });
+
+      it('should define a non-null value when options are passed with a nullish default value', () => {
+        const item = storage.defineItem(`local:test`, {
+          defaultValue: 123,
+        });
+        expectTypeOf(item).toEqualTypeOf<WxtStorageItem<number, {}>>();
+      });
+
+      it('should define a nullable value when options are passed with null default value', () => {
+        const item = storage.defineItem<number | null>(`local:test`, {
+          defaultValue: null,
+        });
+        expectTypeOf(item).toEqualTypeOf<WxtStorageItem<number | null, {}>>();
+      });
+    });
+  });
 });

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

@@ -119,19 +119,18 @@ export async function createShadowRootUi<TMounted>(
   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);
+    // Mount UI inside shadow root
+    mounted = options.onMount(uiContainer, shadow, shadowHost);
   };
 
   const remove = () => {
-    // Detatch shadow root from DOM
-    shadowHost.remove();
     // Cleanup mounted state
     options.onRemove?.(mounted);
+    // Detatch shadow root from DOM
+    shadowHost.remove();
     // Remove children from uiContainer
     while (uiContainer.lastChild)
       uiContainer.removeChild(uiContainer.lastChild);

src/core/builders/vite/index.ts

@@ -10,7 +10,10 @@ import {
   WxtBuilderServer,
 } from '~/types';
 import * as wxtPlugins from './plugins';
-import { getEntrypointBundlePath } from '~/core/utils/entrypoints';
+import {
+  getEntrypointBundlePath,
+  isHtmlEntrypoint,
+} from '~/core/utils/entrypoints';
 
 export async function createViteBuilder(
   inlineConfig: InlineConfig,
@@ -133,6 +136,9 @@ export async function createViteBuilder(
    * Return the basic config for building multiple entrypoints in [multi-page mode](https://vitejs.dev/guide/build.html#multi-page-app).
    */
   const getMultiPageConfig = (entrypoints: Entrypoint[]): vite.InlineConfig => {
+    const htmlEntrypoints = new Set(
+      entrypoints.filter(isHtmlEntrypoint).map((e) => e.name),
+    );
     return {
       mode: wxtConfig.mode,
       plugins: [
@@ -148,10 +154,12 @@ export async function createViteBuilder(
           output: {
             // Include a hash to prevent conflicts
             chunkFileNames: 'chunks/[name]-[hash].js',
-            // Place JS entrypoints in main directory without a hash. (popup.html & popup.js are
-            // next to each other). The unique entrypoint name requirement prevents conflicts with
-            // scripts of the same name
-            entryFileNames: '[name].js',
+            entryFileNames: ({ name }) => {
+              // HTML main JS files go in the chunks folder
+              if (htmlEntrypoints.has(name)) return 'chunks/[name]-[hash].js';
+              // Scripts are output in the root folder
+              return '[name].js';
+            },
             // We can't control the "name", so we need a hash to prevent conflicts
             assetFileNames: 'assets/[name]-[hash].[ext]',
           },

src/core/create-server.ts

@@ -7,7 +7,7 @@ import {
 } from '~/types';
 import {
   getEntrypointBundlePath,
-  resolvePerBrowserOption,
+  isHtmlEntrypoint,
 } from '~/core/utils/entrypoints';
 import {
   getContentScriptCssFiles,
@@ -25,6 +25,8 @@ import { Mutex } from 'async-mutex';
 import pc from 'picocolors';
 import { relative } from 'node:path';
 import { registerWxt, wxt } from './wxt';
+import { unnormalizePath } from './utils/paths';
+import { mapWxtOptionsToRegisteredContentScript } from './utils/content-scripts';
 
 /**
  * Creates a dev server and pre-builds all the files that need to exist before loading the extension.
@@ -51,6 +53,14 @@ export async function createServer(
     // Build after starting the dev server so it can be used to transform HTML files
     server.currentOutput = await internalBuild();
 
+    // Add file watchers for files not loaded by the dev server. See
+    // https://github.com/wxt-dev/wxt/issues/428#issuecomment-1944731870
+    try {
+      server.watcher.add(getExternalOutputDependencies(server));
+    } catch (err) {
+      wxt.config.logger.warn('Failed to register additional file paths:', err);
+    }
+
     // Open browser after everything is ready to go.
     await runner.openBrowser();
   };
@@ -91,8 +101,8 @@ export async function createServer(
     transformHtml(url, html, originalUrl) {
       return builderServer.transformHtml(url, html, originalUrl);
     },
-    reloadContentScript(contentScript) {
-      server.ws.send('wxt:reload-content-script', contentScript);
+    reloadContentScript(payload) {
+      server.ws.send('wxt:reload-content-script', payload);
     },
     reloadPage(path) {
       server.ws.send('wxt:reload-page', path);
@@ -228,23 +238,12 @@ function reloadContentScripts(steps: BuildStepOutput[], server: WxtDevServer) {
       const css = getContentScriptCssFiles([entry], cssMap);
 
       server.reloadContentScript({
-        allFrames: resolvePerBrowserOption(
-          entry.options.allFrames,
-          wxt.config.browser,
+        registration: entry.options.registration,
+        contentScript: mapWxtOptionsToRegisteredContentScript(
+          entry.options,
+          js,
+          css,
         ),
-        excludeMatches: resolvePerBrowserOption(
-          entry.options.excludeMatches,
-          wxt.config.browser,
-        ),
-        matches: resolvePerBrowserOption(
-          entry.options.matches,
-          wxt.config.browser,
-        ),
-        runAt: resolvePerBrowserOption(entry.options.runAt, wxt.config.browser),
-        // @ts-expect-error: Chrome accepts this, not typed in webextension-polyfill (https://developer.chrome.com/docs/extensions/reference/scripting/#type-RegisteredContentScript)
-        world: resolvePerBrowserOption(entry.options.world, wxt.config.browser),
-        js,
-        css,
       });
     });
   } else {
@@ -257,9 +256,7 @@ function reloadHtmlPages(
   server: WxtDevServer,
 ): { reloadedNames: string[] } {
   // groups might contain other files like background/content scripts, and we only care about the HTMl pages
-  const htmlEntries = groups
-    .flat()
-    .filter((entry) => entry.inputPath.endsWith('.html'));
+  const htmlEntries = groups.flat().filter(isHtmlEntrypoint);
 
   htmlEntries.forEach((entry) => {
     const path = getEntrypointBundlePath(entry, wxt.config.outDir, '.html');
@@ -278,3 +275,30 @@ function getFilenameList(names: string[]): string {
     })
     .join(pc.dim(', '));
 }
+
+/**
+ * Based on the current build output, return a list of files that are:
+ * 1. Not in node_modules
+ * 2. Not inside project root
+ */
+function getExternalOutputDependencies(server: WxtDevServer) {
+  return (
+    server.currentOutput?.steps
+      .flatMap((step, i) => {
+        if (Array.isArray(step.entrypoints) && i === 0) {
+          // Dev server is already watching all HTML/esm files
+          return [];
+        }
+
+        return step.chunks.flatMap((chunk) => {
+          if (chunk.type === 'asset') return [];
+          return chunk.moduleIds;
+        });
+      })
+      .filter(
+        (file) => !file.includes('node_modules') && !file.startsWith('\x00'),
+      )
+      .map(unnormalizePath)
+      .filter((file) => !file.startsWith(wxt.config.root)) ?? []
+  );
+}

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

@@ -4,10 +4,12 @@ import {
   fakeArray,
   fakeBackgroundEntrypoint,
   fakeBuildOutput,
+  fakeContentScriptEntrypoint,
   fakeEntrypoint,
   fakeManifestCommand,
   fakeOptionsEntrypoint,
   fakePopupEntrypoint,
+  fakeSidepanelEntrypoint,
   setFakeWxt,
 } from '../testing/fake-objects';
 import { Manifest } from 'webextension-polyfill';
@@ -756,6 +758,136 @@ describe('Manifest Utils', () => {
           ]);
         });
       });
+
+      describe('registration', () => {
+        it('should throw an error when registration=runtime for MV2', async () => {
+          const cs: ContentScriptEntrypoint = fakeContentScriptEntrypoint({
+            options: {
+              registration: 'runtime',
+            },
+          });
+
+          const entrypoints = [cs];
+          const buildOutput: Omit<BuildOutput, 'manifest'> = {
+            publicAssets: [],
+            steps: [{ entrypoints: cs, chunks: [] }],
+          };
+          setFakeWxt({
+            config: {
+              manifestVersion: 2,
+            },
+          });
+
+          await expect(
+            generateManifest(entrypoints, buildOutput),
+          ).rejects.toThrowError();
+        });
+
+        it('should add host_permissions instead of content_scripts when registration=runtime', async () => {
+          const cs: ContentScriptEntrypoint = {
+            type: 'content-script',
+            name: 'one',
+            inputPath: 'entrypoints/one.content.ts',
+            outputDir: contentScriptOutDir,
+            options: {
+              matches: ['*://google.com/*'],
+              registration: 'runtime',
+            },
+            skipped: false,
+          };
+          const styles: OutputAsset = {
+            type: 'asset',
+            fileName: 'content-scripts/one.css',
+          };
+
+          const entrypoints = [cs];
+          const buildOutput: Omit<BuildOutput, 'manifest'> = {
+            publicAssets: [],
+            steps: [{ entrypoints: cs, chunks: [styles] }],
+          };
+          setFakeWxt({
+            config: {
+              manifestVersion: 3,
+              outDir,
+              command: 'build',
+            },
+          });
+
+          const { manifest: actual } = await generateManifest(
+            entrypoints,
+            buildOutput,
+          );
+
+          expect(actual.content_scripts).toEqual([]);
+          expect(actual.host_permissions).toEqual(['*://google.com/*']);
+        });
+      });
+    });
+
+    describe('sidepanel', () => {
+      it.each(['chrome', 'safari', 'edge'])(
+        'should include a side_panel ignoring all options for %s',
+        async (browser) => {
+          const sidepanel = fakeSidepanelEntrypoint({
+            outputDir: outDir,
+          });
+          const buildOutput = fakeBuildOutput();
+
+          setFakeWxt({
+            config: {
+              manifestVersion: 3,
+              browser,
+              outDir,
+            },
+          });
+          const expected = {
+            side_panel: {
+              default_path: 'sidepanel.html',
+            },
+          };
+
+          const { manifest: actual } = await generateManifest(
+            [sidepanel],
+            buildOutput,
+          );
+
+          expect(actual).toMatchObject(expected);
+        },
+      );
+
+      it.each(['firefox'])(
+        'should include a sidebar_action for %s',
+        async (browser) => {
+          const sidepanel = fakeSidepanelEntrypoint({
+            outputDir: outDir,
+          });
+          const buildOutput = fakeBuildOutput();
+
+          setFakeWxt({
+            config: {
+              manifestVersion: 3,
+              browser,
+              outDir,
+            },
+          });
+          const expected = {
+            sidebar_action: {
+              default_panel: 'sidepanel.html',
+              open_at_install: sidepanel.options.openAtInstall,
+              default_title: sidepanel.options.defaultTitle,
+              default_icon: sidepanel.options.defaultIcon,
+              browser_style: sidepanel.options.browserStyle,
+            },
+          };
+
+          const { manifest: actual } = await generateManifest(
+            [sidepanel],
+            buildOutput,
+          );
+
+          expect(actual).toMatchObject(expected);
+        },
+      );
     });
 
     describe('web_accessible_resources', () => {

src/core/utils/building/__tests__/find-entrypoints.test.ts

@@ -1,10 +1,13 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import {
   BackgroundEntrypoint,
+  BackgroundEntrypointOptions,
+  BaseEntrypointOptions,
   ContentScriptEntrypoint,
   GenericEntrypoint,
   OptionsEntrypoint,
   PopupEntrypoint,
+  SidepanelEntrypoint,
 } from '~/types';
 import { resolve } from 'path';
 import { findEntrypoints } from '../find-entrypoints';
@@ -242,7 +245,7 @@ describe('findEntrypoints', () => {
   ])(
     'should find and load background entrypoint config from %s',
     async (path, expected) => {
-      const options: BackgroundEntrypoint['options'] = {
+      const options: BackgroundEntrypointOptions = {
         type: 'module',
       };
       globMock.mockResolvedValueOnce([path]);
@@ -256,13 +259,87 @@ describe('findEntrypoints', () => {
     },
   );
 
+  it.each<[string, string, SidepanelEntrypoint]>([
+    [
+      'sidepanel.html',
+      `
+        <html>
+          <head>
+            <title>Default Title</title>
+            <meta name="manifest.default_icon" content="{ '16': '/icon/16.png' }" />
+            <meta name="manifest.open_at_install" content="true" />
+          </head>
+        </html>
+      `,
+      {
+        type: 'sidepanel',
+        name: 'sidepanel',
+        inputPath: resolve(config.entrypointsDir, 'sidepanel.html'),
+        outputDir: config.outDir,
+        options: {
+          defaultTitle: 'Default Title',
+          defaultIcon: { '16': '/icon/16.png' },
+          openAtInstall: true,
+        },
+        skipped: false,
+      },
+    ],
+    [
+      'sidepanel/index.html',
+      `<html></html>`,
+      {
+        type: 'sidepanel',
+        name: 'sidepanel',
+        inputPath: resolve(config.entrypointsDir, 'sidepanel/index.html'),
+        options: {},
+        outputDir: config.outDir,
+        skipped: false,
+      },
+    ],
+    [
+      'named.sidepanel.html',
+      `<html></html>`,
+      {
+        type: 'sidepanel',
+        name: 'named',
+        inputPath: resolve(config.entrypointsDir, 'named.sidepanel.html'),
+        options: {},
+        outputDir: config.outDir,
+        skipped: false,
+      },
+    ],
+    [
+      'named.sidepanel/index.html',
+      `<html></html>`,
+      {
+        type: 'sidepanel',
+        name: 'named',
+        inputPath: resolve(config.entrypointsDir, 'named.sidepanel/index.html'),
+        outputDir: config.outDir,
+        options: {},
+        skipped: false,
+      },
+    ],
+  ])(
+    'should find and load sidepanel entrypoint config from %s',
+    async (path, content, expected) => {
+      globMock.mockResolvedValueOnce([path]);
+      readFileMock.mockResolvedValueOnce(content);
+
+      const entrypoints = await findEntrypoints();
+
+      expect(entrypoints).toHaveLength(1);
+      expect(entrypoints[0]).toEqual(expected);
+    },
+  );
+
   it('should remove type=module from MV2 background scripts', async () => {
     setFakeWxt({
       config: {
         manifestVersion: 2,
       },
     });
-    const options: BackgroundEntrypoint['options'] = {
+    const options: BackgroundEntrypointOptions = {
       type: 'module',
     };
     globMock.mockResolvedValueOnce(['background.ts']);
@@ -279,7 +356,7 @@ describe('findEntrypoints', () => {
         manifestVersion: 3,
       },
     });
-    const options: BackgroundEntrypoint['options'] = {
+    const options: BackgroundEntrypointOptions = {
       type: 'module',
     };
     globMock.mockResolvedValueOnce(['background.ts']);
@@ -331,7 +408,7 @@ describe('findEntrypoints', () => {
         outputDir: config.outDir,
         skipped: false,
       };
-      const options: GenericEntrypoint['options'] = {};
+      const options: BaseEntrypointOptions = {};
       globMock.mockResolvedValueOnce([path]);
       importEntrypointFileMock.mockResolvedValue(options);
 
@@ -462,52 +539,6 @@ describe('findEntrypoints', () => {
       },
     ],
 
-    // sidepanel
-    [
-      'sidepanel.html',
-      {
-        type: 'sidepanel',
-        name: 'sidepanel',
-        inputPath: resolve(config.entrypointsDir, 'sidepanel.html'),
-        outputDir: config.outDir,
-        options: {},
-        skipped: false,
-      },
-    ],
-    [
-      'sidepanel/index.html',
-      {
-        type: 'sidepanel',
-        name: 'sidepanel',
-        inputPath: resolve(config.entrypointsDir, 'sidepanel/index.html'),
-        outputDir: config.outDir,
-        options: {},
-        skipped: false,
-      },
-    ],
-    [
-      'named.sidepanel.html',
-      {
-        type: 'sidepanel',
-        name: 'named',
-        inputPath: resolve(config.entrypointsDir, 'named.sidepanel.html'),
-        outputDir: config.outDir,
-        options: {},
-        skipped: false,
-      },
-    ],
-    [
-      'named.sidepanel/index.html',
-      {
-        type: 'sidepanel',
-        name: 'named',
-        inputPath: resolve(config.entrypointsDir, 'named.sidepanel/index.html'),
-        outputDir: config.outDir,
-        options: {},
-        skipped: false,
-      },
-    ],
-
     // devtools
     [
       'devtools.html',

src/core/utils/building/find-entrypoints.ts

@@ -10,6 +10,10 @@ import {
   OptionsEntrypoint,
   PopupEntrypoint,
   UnlistedScriptDefinition,
+  PopupEntrypointOptions,
+  OptionsEntrypointOptions,
+  SidepanelEntrypoint,
+  SidepanelEntrypointOptions,
 } from '~/types';
 import fs from 'fs-extra';
 import { minimatch } from 'minimatch';
@@ -19,7 +23,7 @@ import { importEntrypointFile } from '~/core/utils/building';
 import glob from 'fast-glob';
 import {
   getEntrypointName,
-  resolvePerBrowserOption,
+  resolvePerBrowserOptions,
 } from '~/core/utils/entrypoints';
 import { VIRTUAL_NOOP_BACKGROUND_MODULE_ID } from '~/core/utils/constants';
 import { CSS_EXTENSIONS_PATTERN } from '~/core/utils/paths';
@@ -71,6 +75,8 @@ export async function findEntrypoints(): Promise<Entrypoint[]> {
       switch (type) {
         case 'popup':
           return await getPopupEntrypoint(info);
+        case 'sidepanel':
+          return await getSidepanelEntrypoint(info);
         case 'options':
           return await getOptionsEntrypoint(info);
         case 'background':
@@ -199,153 +205,81 @@ function preventNoEntrypoints(files: EntrypointInfo[]) {
   }
 }
 
-function getHtmlBaseOptions(document: Document): BaseEntrypointOptions {
-  const options: BaseEntrypointOptions = {};
-
-  const includeContent = document
-    .querySelector("meta[name='manifest.include']")
-    ?.getAttribute('content');
-  if (includeContent) {
-    options.include = JSON5.parse(includeContent);
-  }
-
-  const excludeContent = document
-    .querySelector("meta[name='manifest.exclude']")
-    ?.getAttribute('content');
-  if (excludeContent) {
-    options.exclude = JSON5.parse(excludeContent);
-  }
-
-  return options;
-}
-
-/**
- * @param path Absolute path to the popup HTML file.
- * @param content String contents of the file at the path.
- */
-async function getPopupEntrypoint({
-  inputPath,
-  name,
-  skipped,
-}: EntrypointInfo): Promise<PopupEntrypoint> {
-  const content = await fs.readFile(inputPath, 'utf-8');
-  const { document } = parseHTML(content);
-
-  const options: PopupEntrypoint['options'] = getHtmlBaseOptions(document);
-
-  const title = document.querySelector('title');
-  if (title != null) options.defaultTitle = title.textContent ?? undefined;
-
-  const defaultIconContent = document
-    .querySelector("meta[name='manifest.default_icon']")
-    ?.getAttribute('content');
-  if (defaultIconContent) {
-    try {
-      options.defaultIcon = JSON5.parse(defaultIconContent);
-    } catch (err) {
-      wxt.logger.fatal(
-        `Failed to parse default_icon meta tag content as JSON5. content=${defaultIconContent}`,
-        err,
-      );
-    }
-  }
-
-  const mv2TypeContent = document
-    .querySelector("meta[name='manifest.type']")
-    ?.getAttribute('content');
-  if (mv2TypeContent) {
-    options.mv2Key =
-      mv2TypeContent === 'page_action' ? 'page_action' : 'browser_action';
-  }
-
-  const browserStyleContent = document
-    .querySelector("meta[name='manifest.browser_style']")
-    ?.getAttribute('content');
-  if (browserStyleContent) {
-    options.browserStyle = browserStyleContent === 'true';
-  }
+async function getPopupEntrypoint(
+  info: EntrypointInfo,
+): Promise<PopupEntrypoint> {
+  const options = await getHtmlEntrypointOptions<PopupEntrypointOptions>(
+    info,
+    {
+      browserStyle: 'browse_style',
+      exclude: 'exclude',
+      include: 'include',
+      defaultIcon: 'default_icon',
+      defaultTitle: 'default_title',
+      mv2Key: 'type',
+    },
+    {
+      defaultTitle: (document) =>
+        document.querySelector('title')?.textContent || undefined,
+    },
+    {
+      defaultTitle: (content) => content,
+      mv2Key: (content) =>
+        content === 'page_action' ? 'page_action' : 'browser_action',
+    },
+  );
 
   return {
     type: 'popup',
     name: 'popup',
-    options,
-    inputPath,
+    options: resolvePerBrowserOptions(options, wxt.config.browser),
+    inputPath: info.inputPath,
     outputDir: wxt.config.outDir,
-    skipped,
+    skipped: info.skipped,
   };
 }
 
-/**
- * @param path Absolute path to the options HTML file.
- * @param content String contents of the file at the path.
- */
-async function getOptionsEntrypoint({
-  inputPath,
-  name,
-  skipped,
-}: EntrypointInfo): Promise<OptionsEntrypoint> {
-  const content = await fs.readFile(inputPath, 'utf-8');
-  const { document } = parseHTML(content);
-
-  const options: OptionsEntrypoint['options'] = getHtmlBaseOptions(document);
-
-  const openInTabContent = document
-    .querySelector("meta[name='manifest.open_in_tab']")
-    ?.getAttribute('content');
-  if (openInTabContent) {
-    options.openInTab = openInTabContent === 'true';
-  }
-
-  const chromeStyleContent = document
-    .querySelector("meta[name='manifest.chrome_style']")
-    ?.getAttribute('content');
-  if (chromeStyleContent) {
-    options.chromeStyle = chromeStyleContent === 'true';
-  }
-
-  const browserStyleContent = document
-    .querySelector("meta[name='manifest.browser_style']")
-    ?.getAttribute('content');
-  if (browserStyleContent) {
-    options.browserStyle = browserStyleContent === 'true';
-  }
-
+async function getOptionsEntrypoint(
+  info: EntrypointInfo,
+): Promise<OptionsEntrypoint> {
+  const options = await getHtmlEntrypointOptions<OptionsEntrypointOptions>(
+    info,
+    {
+      browserStyle: 'browse_style',
+      chromeStyle: 'chrome_style',
+      exclude: 'exclude',
+      include: 'include',
+      openInTab: 'open_in_tab',
+    },
+  );
   return {
     type: 'options',
     name: 'options',
-    options,
-    inputPath,
+    options: resolvePerBrowserOptions(options, wxt.config.browser),
+    inputPath: info.inputPath,
     outputDir: wxt.config.outDir,
-    skipped,
+    skipped: info.skipped,
   };
 }
 
-/**
- * @param path Absolute path to the HTML file.
- * @param content String contents of the file at the path.
- */
-async function getUnlistedPageEntrypoint({
-  inputPath,
-  name,
-  skipped,
-}: EntrypointInfo): Promise<GenericEntrypoint> {
-  const content = await fs.readFile(inputPath, 'utf-8');
-  const { document } = parseHTML(content);
+async function getUnlistedPageEntrypoint(
+  info: EntrypointInfo,
+): Promise<GenericEntrypoint> {
+  const options = await getHtmlEntrypointOptions<BaseEntrypointOptions>(info, {
+    exclude: 'exclude',
+    include: 'include',
+  });
 
   return {
     type: 'unlisted-page',
-    name: getEntrypointName(wxt.config.entrypointsDir, inputPath),
-    inputPath,
+    name: info.name,
+    inputPath: info.inputPath,
     outputDir: wxt.config.outDir,
-    options: getHtmlBaseOptions(document),
-    skipped,
+    options,
+    skipped: info.skipped,
   };
 }
 
-/**
- * @param path Absolute path to the script's file.
- * @param content String contents of the file at the path.
- */
 async function getUnlistedScriptEntrypoint({
   inputPath,
   name,
@@ -358,21 +292,17 @@ async function getUnlistedScriptEntrypoint({
       `${name}: Default export not found, did you forget to call "export default defineUnlistedScript(...)"?`,
     );
   }
-  const { main: _, ...moduleOptions } = defaultExport;
-  const options: Omit<UnlistedScriptDefinition, 'main'> = moduleOptions;
+  const { main: _, ...options } = defaultExport;
   return {
     type: 'unlisted-script',
     name,
     inputPath,
     outputDir: wxt.config.outDir,
-    options,
+    options: resolvePerBrowserOptions(options, wxt.config.browser),
     skipped,
   };
 }
 
-/**
- * @param path Absolute path to the background's TS file.
- */
 async function getBackgroundEntrypoint({
   inputPath,
   name,
@@ -400,21 +330,11 @@ async function getBackgroundEntrypoint({
     name,
     inputPath,
     outputDir: wxt.config.outDir,
-    options: {
-      ...options,
-      type: resolvePerBrowserOption(options.type, wxt.config.browser),
-      persistent: resolvePerBrowserOption(
-        options.persistent,
-        wxt.config.browser,
-      ),
-    },
+    options: resolvePerBrowserOptions(options, wxt.config.browser),
     skipped,
   };
 }
 
-/**
- * @param path Absolute path to the content script's TS file.
- */
 async function getContentScriptEntrypoint({
   inputPath,
   name,
@@ -432,11 +352,87 @@ async function getContentScriptEntrypoint({
     name,
     inputPath,
     outputDir: resolve(wxt.config.outDir, CONTENT_SCRIPT_OUT_DIR),
-    options,
+    options: resolvePerBrowserOptions(options, wxt.config.browser),
     skipped,
   };
 }
 
+async function getSidepanelEntrypoint(
+  info: EntrypointInfo,
+): Promise<SidepanelEntrypoint> {
+  const options = await getHtmlEntrypointOptions<SidepanelEntrypointOptions>(
+    info,
+    {
+      browserStyle: 'browse_style',
+      exclude: 'exclude',
+      include: 'include',
+      defaultIcon: 'default_icon',
+      defaultTitle: 'default_title',
+      openAtInstall: 'open_at_install',
+    },
+    {
+      defaultTitle: (document) =>
+        document.querySelector('title')?.textContent || undefined,
+    },
+    {
+      defaultTitle: (content) => content,
+    },
+  );
+
+  return {
+    type: 'sidepanel',
+    name: info.name,
+    options: resolvePerBrowserOptions(options, wxt.config.browser),
+    inputPath: info.inputPath,
+    outputDir: wxt.config.outDir,
+    skipped: info.skipped,
+  };
+}
+
+/**
+ * Parse the HTML tags to extract options from them.
+ */
+async function getHtmlEntrypointOptions<T extends BaseEntrypointOptions>(
+  info: EntrypointInfo,
+  keyMap: Record<keyof T, string>,
+  queries?: Partial<{
+    [key in keyof T]: (
+      document: Document,
+      manifestKey: string,
+    ) => string | undefined;
+  }>,
+  parsers?: Partial<{ [key in keyof T]: (content: string) => T[key] }>,
+): Promise<T> {
+  const content = await fs.readFile(info.inputPath, 'utf-8');
+  const { document } = parseHTML(content);
+
+  const options = {} as T;
+
+  const defaultQuery = (manifestKey: string) =>
+    document
+      .querySelector(`meta[name='manifest.${manifestKey}']`)
+      ?.getAttribute('content');
+
+  Object.entries(keyMap).forEach(([_key, manifestKey]) => {
+    const key = _key as keyof T;
+    const content = queries?.[key]
+      ? queries[key]!(document, manifestKey)
+      : defaultQuery(manifestKey);
+    if (content) {
+      try {
+        options[key] = (parsers?.[key] ?? JSON5.parse)(content);
+      } catch (err) {
+        wxt.logger.fatal(
+          `Failed to parse meta tag content. Usually this means you have invalid JSON5 content (content=${content})`,
+          err,
+        );
+      }
+    }
+  });
+
+  return options;
+}
+
 const PATH_GLOB_TO_TYPE_MAP: Record<string, Entrypoint['type']> = {
   'sandbox.html': 'sandbox',
   'sandbox/index.html': 'sandbox',

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

@@ -6,7 +6,10 @@ import {
 } from '~/types';
 import fs from 'fs-extra';
 import { relative, resolve } from 'path';
-import { getEntrypointBundlePath } from '~/core/utils/entrypoints';
+import {
+  getEntrypointBundlePath,
+  isHtmlEntrypoint,
+} from '~/core/utils/entrypoints';
 import { getEntrypointGlobals, getGlobals } from '~/core/utils/globals';
 import { normalizePath } from '~/core/utils/paths';
 import path from 'node:path';
@@ -82,7 +85,7 @@ async function writePathsDeclarationFile(
       getEntrypointBundlePath(
         entry,
         wxt.config.outDir,
-        entry.inputPath.endsWith('.html') ? '.html' : '.js',
+        isHtmlEntrypoint(entry) ? '.html' : '.js',
       ),
     )
     .concat(await getPublicFiles())

src/core/utils/building/import-entrypoint.ts

@@ -105,6 +105,13 @@ function getEsbuildOptions(opts: JitiTransformOptions): TransformOptions {
   return {
     format: 'cjs',
     loader: isJsx ? 'tsx' : 'ts',
-    jsx: isJsx ? 'automatic' : undefined,
+    ...(isJsx
+      ? {
+          // `h` and `Fragment` are undefined, but that's OK because JSX is never evaluated while
+          // grabbing the entrypoint's options.
+          jsxFactory: 'h',
+          jsxFragment: 'Fragment',
+        }
+      : undefined),
   };
 }

src/core/utils/building/resolve-config.ts

@@ -37,6 +37,7 @@ export async function resolveConfig(
   let userConfigMetadata: ResolvedConfig['userConfigMetadata'] | undefined;
   if (inlineConfig.configFile !== false) {
     const { config: loadedConfig, ...metadata } = await loadConfig<UserConfig>({
+      configFile: inlineConfig.configFile,
       name: 'wxt',
       cwd: inlineConfig.root ?? process.cwd(),
       rcFile: false,

src/core/utils/content-scripts.ts

@@ -1,7 +1,5 @@
-import type { Manifest } from '~/browser';
+import type { Manifest, Scripting } from '~/browser';
 import { ContentScriptEntrypoint } from '~/types';
-import { resolvePerBrowserOption } from './entrypoints';
-import { wxt } from '../wxt';
 
 /**
  * Returns a unique and consistent string hash based on a content scripts options.
@@ -11,7 +9,11 @@ import { wxt } from '../wxt';
 export function hashContentScriptOptions(
   options: ContentScriptEntrypoint['options'],
 ): string {
-  const simplifiedOptions = mapWxtOptionsToContentScript(options);
+  const simplifiedOptions = mapWxtOptionsToContentScript(
+    options,
+    undefined,
+    undefined,
+  );
 
   // Remove undefined fields and use defaults to generate hash
   Object.keys(simplifiedOptions).forEach((key) => {
@@ -45,33 +47,39 @@ export function hashContentScriptOptions(
 
 export function mapWxtOptionsToContentScript(
   options: ContentScriptEntrypoint['options'],
-): Omit<Manifest.ContentScript, 'js' | 'css'> {
+  js: string[] | undefined,
+  css: string[] | undefined,
+): Manifest.ContentScript {
   return {
-    matches: resolvePerBrowserOption(options.matches, wxt.config.browser),
-    all_frames: resolvePerBrowserOption(options.allFrames, wxt.config.browser),
-    match_about_blank: resolvePerBrowserOption(
-      options.matchAboutBlank,
-      wxt.config.browser,
-    ),
-    exclude_globs: resolvePerBrowserOption(
-      options.excludeGlobs,
-      wxt.config.browser,
-    ),
-    exclude_matches: resolvePerBrowserOption(
-      options.excludeMatches,
-      wxt.config.browser,
-    ),
-    include_globs: resolvePerBrowserOption(
-      options.includeGlobs,
-      wxt.config.browser,
-    ),
-    run_at: resolvePerBrowserOption(options.runAt, wxt.config.browser),
+    matches: options.matches,
+    all_frames: options.allFrames,
+    match_about_blank: options.matchAboutBlank,
+    exclude_globs: options.excludeGlobs,
+    exclude_matches: options.excludeMatches,
+    include_globs: options.includeGlobs,
+    run_at: options.runAt,
+    css,
+    js,
 
     // @ts-expect-error: untyped chrome options
-    match_origin_as_fallback: resolvePerBrowserOption(
-      options.matchOriginAsFallback,
-      wxt.config.browser,
-    ),
+    match_origin_as_fallback: options.matchOriginAsFallback,
+    world: options.world,
+  };
+}
+
+export function mapWxtOptionsToRegisteredContentScript(
+  options: ContentScriptEntrypoint['options'],
+  js: string[] | undefined,
+  css: string[] | undefined,
+): Omit<Scripting.RegisteredContentScript, 'id'> {
+  return {
+    allFrames: options.allFrames,
+    excludeMatches: options.excludeMatches,
+    matches: options.matches,
+    runAt: options.runAt,
+    js,
+    css,
+    // @ts-expect-error: Chrome accepts this, not typed in webextension-polyfill (https://developer.chrome.com/docs/extensions/reference/scripting/#type-RegisteredContentScript)
     world: options.world,
   };
 }

src/core/utils/entrypoints.ts

@@ -1,4 +1,9 @@
-import { Entrypoint, PerBrowserOption, TargetBrowser } from '~/types';
+import {
+  Entrypoint,
+  PerBrowserOption,
+  ResolvedPerBrowserOptions,
+  TargetBrowser,
+} from '~/types';
 import path, { relative, resolve } from 'node:path';
 import { normalizePath } from './paths';
 
@@ -46,3 +51,31 @@ export function resolvePerBrowserOption<T>(
     return (option as any)[browser];
   return option;
 }
+
+/**
+ * Given an entrypoint option, resolve it's value based on a target browser.
+ *
+ * defaultIcon is special, it's the only key that's a record, which can confuse this function. So
+ * it's been manually excluded from resolution.
+ */
+export function resolvePerBrowserOptions<
+  T extends Record<string, any>,
+  TKeys extends keyof T,
+>(options: T, browser: TargetBrowser): ResolvedPerBrowserOptions<T, TKeys> {
+  // @ts-expect-error: Object.entries is untyped.
+  return Object.fromEntries(
+    Object.entries(options).map(([key, value]) => [
+      key,
+      key === 'defaultIcon' ? value : resolvePerBrowserOption(value, browser),
+    ]),
+  );
+}
+
+/**
+ * Returns true when the entrypoint is an HTML entrypoint.
+ *
+ * Naively just checking the file extension of the input path.
+ */
+export function isHtmlEntrypoint(entrypoint: Entrypoint): boolean {
+  return entrypoint.inputPath.endsWith('.html');
+}

src/core/utils/manifest.ts

@@ -6,13 +6,11 @@ import {
   ContentScriptEntrypoint,
   OptionsEntrypoint,
   PopupEntrypoint,
+  SidepanelEntrypoint,
 } from '~/types';
 import fs from 'fs-extra';
 import { resolve } from 'path';
-import {
-  getEntrypointBundlePath,
-  resolvePerBrowserOption,
-} from './entrypoints';
+import { getEntrypointBundlePath } from './entrypoints';
 import { ContentSecurityPolicy } from './content-security-policy';
 import {
   hashContentScriptOptions,
@@ -185,7 +183,9 @@ function addEntrypoints(
     | undefined;
   const popup = entriesByType['popup']?.[0] as PopupEntrypoint | undefined;
   const sandboxes = entriesByType['sandbox'];
-  const sidepanels = entriesByType['sidepanel'];
+  const sidepanels = entriesByType['sidepanel'] as
+    | SidepanelEntrypoint[]
+    | undefined;
 
   if (background) {
     const script = getEntrypointBundlePath(
@@ -331,9 +331,11 @@ function addEntrypoints(
 
     if (wxt.config.browser === 'firefox') {
       manifest.sidebar_action = {
-        // TODO: Add options to side panel
-        // ...defaultSidepanel.options,
         default_panel: page,
+        browser_style: defaultSidepanel.options.browserStyle,
+        default_icon: defaultSidepanel.options.defaultIcon,
+        default_title: defaultSidepanel.options.defaultTitle,
+        open_at_install: defaultSidepanel.options.openAtInstall,
       };
     } else if (wxt.config.manifestVersion === 3) {
       // @ts-expect-error: Untyped
@@ -353,40 +355,54 @@ function addEntrypoints(
     // Don't add content scripts to the manifest in dev mode for MV3 - they're managed and reloaded
     // at runtime
     if (wxt.config.command === 'serve' && wxt.config.manifestVersion === 3) {
-      const hostPermissions = new Set<string>(manifest.host_permissions ?? []);
       contentScripts.forEach((script) => {
-        const matches = resolvePerBrowserOption(
-          script.options.matches,
-          wxt.config.browser,
-        );
-        matches.forEach((matchPattern) => {
-          hostPermissions.add(matchPattern);
+        script.options.matches.forEach((matchPattern) => {
+          addHostPermission(manifest, matchPattern);
         });
       });
-      hostPermissions.forEach((permission) =>
-        addHostPermission(manifest, permission),
-      );
     } else {
-      const hashToEntrypointsMap = contentScripts.reduce((map, script) => {
-        const hash = hashContentScriptOptions(script.options);
-        if (map.has(hash)) map.get(hash)?.push(script);
-        else map.set(hash, [script]);
-        return map;
-      }, new Map<string, ContentScriptEntrypoint[]>());
-
-      const newContentScripts = Array.from(hashToEntrypointsMap.entries()).map(
-        ([, scripts]) => ({
-          ...mapWxtOptionsToContentScript(scripts[0].options),
-          css: getContentScriptCssFiles(scripts, cssMap),
-          js: scripts.map((entry) =>
+      // Manifest scripts
+      const hashToEntrypointsMap = contentScripts
+        .filter((cs) => cs.options.registration !== 'runtime')
+        .reduce((map, script) => {
+          const hash = hashContentScriptOptions(script.options);
+          if (map.has(hash)) map.get(hash)?.push(script);
+          else map.set(hash, [script]);
+          return map;
+        }, new Map<string, ContentScriptEntrypoint[]>());
+      const manifestContentScripts = Array.from(
+        hashToEntrypointsMap.values(),
+      ).map((scripts) =>
+        mapWxtOptionsToContentScript(
+          scripts[0].options,
+          scripts.map((entry) =>
             getEntrypointBundlePath(entry, wxt.config.outDir, '.js'),
           ),
-        }),
+          getContentScriptCssFiles(scripts, cssMap),
+        ),
       );
-      if (newContentScripts.length >= 0) {
+      if (manifestContentScripts.length >= 0) {
         manifest.content_scripts ??= [];
-        manifest.content_scripts.push(...newContentScripts);
+        manifest.content_scripts.push(...manifestContentScripts);
       }
+
+      // Runtime content scripts
+      const runtimeContentScripts = contentScripts.filter(
+        (cs) => cs.options.registration === 'runtime',
+      );
+      if (
+        runtimeContentScripts.length > 0 &&
+        wxt.config.manifestVersion === 2
+      ) {
+        throw Error(
+          'Cannot use `registration: "runtime"` with MV2 content scripts, it is a MV3-only feature.',
+        );
+      }
+      runtimeContentScripts.forEach((script) => {
+        script.options.matches.forEach((matchPattern) => {
+          addHostPermission(manifest, matchPattern);
+        });
+      });
     }
 
     const contentScriptCssResources = getContentScriptCssWebAccessibleResources(
@@ -519,10 +535,9 @@ export function getContentScriptCssWebAccessibleResources(
 
     resources.push({
       resources: [cssFile],
-      matches: resolvePerBrowserOption(
-        script.options.matches,
-        wxt.config.browser,
-      ).map((matchPattern) => stripPathFromMatchPattern(matchPattern)),
+      matches: script.options.matches.map((matchPattern) =>
+        stripPathFromMatchPattern(matchPattern),
+      ),
     });
   });
 

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

@@ -21,6 +21,7 @@ import {
   BuildStepOutput,
   UserManifest,
   Wxt,
+  SidepanelEntrypoint,
 } from '~/types';
 import { mock } from 'vitest-mock-extended';
 import { vi } from 'vitest';
@@ -148,6 +149,30 @@ export const fakePopupEntrypoint = fakeObjectCreator<PopupEntrypoint>(() => ({
   skipped: faker.datatype.boolean(),
 }));
 
+export const fakeSidepanelEntrypoint = fakeObjectCreator<SidepanelEntrypoint>(
+  () => ({
+    type: 'sidepanel',
+    inputPath: 'entrypoints/sidepanel.html',
+    name: 'sidepanel',
+    outputDir: fakeDir('.output'),
+    options: {
+      defaultTitle: faker.helpers.arrayElement([
+        faker.person.fullName(),
+        undefined,
+      ]),
+      defaultIcon: faker.helpers.arrayElement([
+        {
+          '16': 'icon/16.png',
+          '24': 'icon/24.png',
+          '64': 'icon/64.png',
+        },
+      ]),
+      openAtInstall: faker.helpers.arrayElement([true, false, undefined]),
+    },
+    skipped: faker.datatype.boolean(),
+  }),
+);
+
 export const fakeGenericEntrypoint = fakeObjectCreator<GenericEntrypoint>(
   () => ({
     type: faker.helpers.arrayElement([
@@ -155,7 +180,6 @@ export const fakeGenericEntrypoint = fakeObjectCreator<GenericEntrypoint>(
       'bookmarks',
       'history',
       'newtab',
-      'sidepanel',
       'devtools',
       'unlisted-page',
       'unlisted-script',

src/storage.ts

@@ -7,6 +7,7 @@
  */
 import { Storage, browser } from '~/browser';
 import { dequal } from 'dequal/lite';
+import { logger } from './sandbox/utils/logger';
 
 export const storage = createStorage();
 
@@ -247,7 +248,7 @@ function createStorage(): WxtStorage {
         driver.unwatch();
       });
     },
-    defineItem: (key, opts) => {
+    defineItem: (key: string, opts?: WxtStorageItemOptions<any>) => {
       const { driver, driverKey } = resolveKey(key);
 
       const { version: targetVersion = 1, migrations = {} } = opts ?? {};
@@ -256,7 +257,7 @@ function createStorage(): WxtStorage {
           'Storage item version cannot be less than 1. Initial versions should be set to 1, not 0.',
         );
       }
-      const runMigrations = async () => {
+      const migrate = async () => {
         const [value, meta] = await Promise.all([
           // TODO: Optimize with getItems
           getItem(driver, driverKey, undefined),
@@ -267,10 +268,13 @@ function createStorage(): WxtStorage {
         const currentVersion = meta.v ?? 1;
         if (currentVersion > targetVersion) {
           throw Error(
-            `[wxt/storage] Migration ignored for "${key}", version downgrade detected (${currentVersion} -> ${targetVersion})`,
+            `Version downgrade detected (v${currentVersion} -> v${targetVersion}) for "${key}"`,
           );
         }
 
+        logger.debug(
+          `Running storage migration for ${key}: v${currentVersion} -> v${targetVersion}`,
+        );
         const migrationsToRun = Array.from(
           { length: targetVersion - currentVersion },
           (_, i) => currentVersion + i + 1,
@@ -286,18 +290,37 @@ function createStorage(): WxtStorage {
           setItem(driver, driverKey, migratedValue),
           setMeta(driver, driverKey, { v: targetVersion }),
         ]);
+        logger.debug(
+          `Storage migration completed for ${key} v${targetVersion}`,
+          { migratedValue },
+        );
       };
-      let _migrationsCompleted = runMigrations();
+      browser.runtime.onInstalled.addListener(async ({ reason }) => {
+        if (reason !== 'update') return;
+        try {
+          await migrate();
+        } catch (err) {
+          logger.error(`Migration failed for ${key}`, err);
+        }
+      });
+
+      const getDefaultValue = () => opts?.defaultValue ?? null;
 
       return {
-        _migrationsCompleted,
+        get defaultValue() {
+          return getDefaultValue();
+        },
         getValue: () => getItem(driver, driverKey, opts),
         getMeta: () => getMeta(driver, driverKey),
         setValue: (value) => setItem(driver, driverKey, value),
         setMeta: (properties) => setMeta(driver, driverKey, properties),
         removeValue: (opts) => removeItem(driver, driverKey, opts),
         removeMeta: (properties) => removeMeta(driver, driverKey, properties),
-        watch: (cb) => watch(driver, driverKey, cb),
+        watch: (cb) =>
+          watch(driver, driverKey, (newValue, oldValue) =>
+            cb(newValue ?? getDefaultValue(), oldValue ?? getDefaultValue()),
+          ),
+        migrate,
       };
     },
   };
@@ -482,20 +505,23 @@ export interface WxtStorage {
   /**
    * Watch for changes to a specific key in storage.
    */
-  watch<T>(key: string, cb: WatchCallback<T>): Unwatch;
+  watch<T>(key: string, cb: WatchCallback<T | null>): Unwatch;
   /**
    * Remove all watch listeners.
    */
   unwatch(): void;
+
   /**
-   * Define a constant with utilities for reading/writing to a single value in storage.
+   * Define a storage item with a default value, type, or versioning.
    *
-   * @example
-   * export const installDate = storage.defineItem<number>("local:installDate");
+   * Read full docs: https://wxt.dev/guide/storage.html#defining-storage-items
    */
   defineItem<TValue, TMetadata extends Record<string, unknown> = {}>(
     key: string,
-    options?: WxtStorageItemOptions<TValue>,
+  ): WxtStorageItem<TValue | null, TMetadata>;
+  defineItem<TValue, TMetadata extends Record<string, unknown> = {}>(
+    key: string,
+    options: WxtStorageItemOptions<TValue>,
   ): WxtStorageItem<TValue, TMetadata>;
 }
 
@@ -508,7 +534,7 @@ interface WxtStorageDriver {
   removeItems(keys: string[]): Promise<void>;
   snapshot(): Promise<Record<string, unknown>>;
   restoreSnapshot(data: Record<string, unknown>): Promise<void>;
-  watch<T>(key: string, cb: WatchCallback<T>): Unwatch;
+  watch<T>(key: string, cb: WatchCallback<T | null>): Unwatch;
   unwatch(): void;
 }
 
@@ -516,6 +542,7 @@ export interface WxtStorageItem<
   TValue,
   TMetadata extends Record<string, unknown>,
 > {
+  defaultValue: TValue;
   /**
    * Get the latest value from storage.
    */
@@ -527,7 +554,7 @@ export interface WxtStorageItem<
   /**
    * Set the value in storage.
    */
-  setValue(value: TValue | null): Promise<void>;
+  setValue(value: TValue): Promise<void>;
   /**
    * Set metadata properties.
    */
@@ -544,6 +571,13 @@ export interface WxtStorageItem<
    * Listen for changes to the value in storage.
    */
   watch(cb: WatchCallback<TValue>): Unwatch;
+  /**
+   * If there are migrations defined on the storage item, migrate to the latest version.
+   *
+   * **This function is ran automatically whenever the extension updates**, so you don't have to call it
+   * manually.
+   */
+  migrate(): Promise<void>;
 }
 
 export interface GetItemOptions<T> {
@@ -570,7 +604,8 @@ export interface SnapshotOptions {
   excludeKeys?: string[];
 }
 
-export interface WxtStorageItemOptions<T> extends GetItemOptions<T> {
+export interface WxtStorageItemOptions<T> {
+  defaultValue: T;
   /**
    * Provide a version number for the storage item to enable migrations. When changing the version
    * in the future, migration functions will be ran on application startup.
@@ -592,7 +627,7 @@ export type NullablePartial<T> = {
 /**
  * Callback called when a value in storage is changed.
  */
-export type WatchCallback<T> = (newValue: T | null, oldValue: T | null) => void;
+export type WatchCallback<T> = (newValue: T, oldValue: T) => void;
 /**
  * Call to remove a watch listener
  */

src/types/index.ts

@@ -396,17 +396,20 @@ export interface WxtDevServer
   /**
    * Tell the extension to restart a content script.
    *
-   * @param contentScript The manifest definition for a content script
+   * @param payload Information about the content script to reload.
    */
-  reloadContentScript: (
-    contentScript: Omit<Scripting.RegisteredContentScript, 'id'>,
-  ) => void;
+  reloadContentScript: (payload: ReloadContentScriptPayload) => void;
   /**
    * Grab the latest runner config and restart the browser.
    */
   restartBrowser: () => void;
 }
 
+export interface ReloadContentScriptPayload {
+  registration?: BaseContentScriptEntrypointOptions['registration'];
+  contentScript: Omit<Scripting.RegisteredContentScript, 'id'>;
+}
+
 export type TargetBrowser = string;
 export type TargetManifestVersion = 2 | 3;
 
@@ -424,131 +427,37 @@ export interface Logger {
 }
 
 export interface BaseEntrypointOptions {
+  /**
+   * List of target browsers to include this entrypoint in. Defaults to being included in all
+   * builds. Cannot be used with `exclude`. You must choose one of the two options.
+   *
+   * @default undefined
+   */
   include?: TargetBrowser[];
+  /**
+   * List of target browsers to exclude this entrypoint from. Cannot be used with `include`. You
+   * must choose one of the two options.
+   *
+   * @default undefined
+   */
   exclude?: TargetBrowser[];
 }
 
-export interface BaseEntrypoint {
+export interface BackgroundEntrypointOptions extends BaseEntrypointOptions {
+  persistent?: PerBrowserOption<boolean>;
   /**
-   * The entrypoint's name. This is the filename or dirname without the type suffix.
+   * Set to `"module"` to output the background entrypoint as ESM. ESM outputs can share chunks and
+   * reduce the overall size of the bundled extension.
    *
-   * Examples:
-   * - `popup.html` &rarr; `popup`
-   * - `options/index.html` &rarr; `options`
-   * - `named.sandbox.html` &rarr; `named`
-   * - `named.sandbox/index.html` &rarr; `named`
-   * - `sandbox.html` &rarr; `sandbox`
-   * - `sandbox/index.html` &rarr; `sandbox`
-   * - `overlay.content.ts` &rarr; `overlay`
-   * - `overlay.content/index.ts` &rarr; `overlay`
+   * When `undefined`, the background is bundled individually into an IIFE format.
    *
-   * The name is used when generating an output file:
-   * `<entrypoint.outputDir>/<entrypoint.name>.<ext>`
+   * @default undefined
    */
-  name: string;
-  /**
-   * Absolute path to the entrypoint's input file.
-   */
-  inputPath: string;
-  /**
-   * Absolute path to the entrypoint's output directory. Can be the`InternalConfg.outDir` or a
-   * subdirectory of it.
-   */
-  outputDir: string;
-  options: BaseEntrypointOptions;
-  skipped: boolean;
+  type?: PerBrowserOption<'module'>;
 }
 
-export interface GenericEntrypoint extends BaseEntrypoint {
-  type:
-    | 'sandbox'
-    | 'bookmarks'
-    | 'history'
-    | 'newtab'
-    | 'sidepanel'
-    | 'devtools'
-    | 'unlisted-page'
-    | 'unlisted-script'
-    | 'unlisted-style'
-    | 'content-script-style';
-}
-
-export interface BackgroundEntrypoint extends BaseEntrypoint {
-  type: 'background';
-  options: {
-    persistent?: boolean;
-    type?: 'module';
-  } & BaseEntrypointOptions;
-}
-
-export interface ContentScriptEntrypoint extends BaseEntrypoint {
-  type: 'content-script';
-  options: Omit<ContentScriptDefinition, 'main'> & BaseEntrypointOptions;
-}
-
-export interface PopupEntrypoint extends BaseEntrypoint {
-  type: 'popup';
-  options: {
-    /**
-     * Defaults to "browser_action" to be equivalent to MV3's "action" key
-     */
-    mv2Key?: 'browser_action' | 'page_action';
-    defaultIcon?: Record<string, string>;
-    defaultTitle?: string;
-    browserStyle?: boolean;
-  } & BaseEntrypointOptions;
-}
-
-export interface OptionsEntrypoint extends BaseEntrypoint {
-  type: 'options';
-  options: {
-    openInTab?: boolean;
-    browserStyle?: boolean;
-    chromeStyle?: boolean;
-  } & BaseEntrypointOptions;
-}
-
-export type Entrypoint =
-  | GenericEntrypoint
-  | BackgroundEntrypoint
-  | ContentScriptEntrypoint
-  | PopupEntrypoint
-  | OptionsEntrypoint;
-
-export type EntrypointGroup = Entrypoint | Entrypoint[];
-
-export type OnContentScriptStopped = (cb: () => void) => void;
-
-export type ContentScriptDefinition =
-  | ContentScriptIsolatedWorldDefinition
-  | ContentScriptMainWorldDefinition;
-
-export interface ContentScriptIsolatedWorldDefinition
-  extends ContentScriptBaseDefinition {
-  /**
-   * See https://developer.chrome.com/docs/extensions/develop/concepts/content-scripts#isolated_world
-   * @default "ISOLATED"
-   */
-  world?: 'ISOLATED';
-  /**
-   * Main function executed when the content script is loaded.
-   */
-  main(ctx: ContentScriptContext): void | Promise<void>;
-}
-
-export interface ContentScriptMainWorldDefinition
-  extends ContentScriptBaseDefinition {
-  /**
-   * See https://developer.chrome.com/docs/extensions/develop/concepts/content-scripts#isolated_world
-   */
-  world: 'MAIN';
-  /**
-   * Main function executed when the content script is loaded.
-   */
-  main(): void | Promise<void>;
-}
-
-export interface ContentScriptBaseDefinition extends ExcludableEntrypoint {
+export interface BaseContentScriptEntrypointOptions
+  extends BaseEntrypointOptions {
   matches: PerBrowserOption<Manifest.ContentScript['matches']>;
   /**
    * See https://developer.chrome.com/docs/extensions/mv3/content_scripts/
@@ -596,44 +505,207 @@ export interface ContentScriptBaseDefinition extends ExcludableEntrypoint {
    *   onto the page. Use `browser.runtime.getURL("content-scripts/<name>.css")` to get the file's
    *   URL
    * - `"ui"` - Exclude the CSS from the manifest. CSS will be automatically added to your UI when
-   *   calling `createContentScriptUi`
+   *   calling `createShadowRootUi`
    *
    * @default "manifest"
    */
   cssInjectionMode?: PerBrowserOption<'manifest' | 'manual' | 'ui'>;
+  /**
+   * Specify how the content script is registered.
+   *
+   * - `"manifest"`: The content script will be added to the `content_scripts` entry in the
+   *   manifest. This is the normal and most well known way of registering a content script.
+   * - `"runtime"`: The content script's `matches` is added to `host_permissions` and you are
+   *   responsible for using the scripting API to register the content script dynamically at
+   *   runtime.
+   *
+   * @default "manifest"
+   */
+  registration?: PerBrowserOption<'manifest' | 'runtime'>;
 }
 
-export interface BackgroundDefinition extends ExcludableEntrypoint {
-  type?: PerBrowserOption<'module'>;
-  persistent?: PerBrowserOption<boolean>;
+export interface MainWorldContentScriptEntrypointOptions
+  extends BaseContentScriptEntrypointOptions {
+  /**
+   * See https://developer.chrome.com/docs/extensions/develop/concepts/content-scripts#isolated_world
+   */
+  world: 'MAIN';
+}
+
+export interface IsolatedWorldContentScriptEntrypointOptions
+  extends BaseContentScriptEntrypointOptions {
+  /**
+   * See https://developer.chrome.com/docs/extensions/develop/concepts/content-scripts#isolated_world
+   * @default "ISOLATED"
+   */
+  world?: 'ISOLATED';
+}
+
+export interface PopupEntrypointOptions extends BaseEntrypointOptions {
+  /**
+   * Defaults to "browser_action" to be equivalent to MV3's "action" key
+   */
+  mv2Key?: PerBrowserOption<'browser_action' | 'page_action'>;
+  defaultIcon?: Record<string, string>;
+  defaultTitle?: PerBrowserOption<string>;
+  browserStyle?: PerBrowserOption<boolean>;
+}
+
+export interface OptionsEntrypointOptions extends BaseEntrypointOptions {
+  openInTab?: PerBrowserOption<boolean>;
+  browserStyle?: PerBrowserOption<boolean>;
+  chromeStyle?: PerBrowserOption<boolean>;
+}
+
+export interface SidepanelEntrypointOptions extends BaseEntrypointOptions {
+  /**
+   * Firefox only. See https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/sidebar_action#syntax
+   * @default false
+   */
+  openAtInstall?: PerBrowserOption<boolean>;
+  /**
+   * @deprecated See https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/sidebar_action#syntax
+   */
+  browserStyle?: PerBrowserOption<boolean>;
+  defaultIcon?: string | Record<string, string>;
+  defaultTitle?: PerBrowserOption<string>;
+}
+
+export interface BaseEntrypoint {
+  /**
+   * The entrypoint's name. This is the filename or dirname without the type suffix.
+   *
+   * Examples:
+   * - `popup.html` &rarr; `popup`
+   * - `options/index.html` &rarr; `options`
+   * - `named.sandbox.html` &rarr; `named`
+   * - `named.sandbox/index.html` &rarr; `named`
+   * - `sandbox.html` &rarr; `sandbox`
+   * - `sandbox/index.html` &rarr; `sandbox`
+   * - `overlay.content.ts` &rarr; `overlay`
+   * - `overlay.content/index.ts` &rarr; `overlay`
+   *
+   * The name is used when generating an output file:
+   * `<entrypoint.outputDir>/<entrypoint.name>.<ext>`
+   */
+  name: string;
+  /**
+   * Absolute path to the entrypoint's input file.
+   */
+  inputPath: string;
+  /**
+   * Absolute path to the entrypoint's output directory. Can be the`InternalConfg.outDir` or a
+   * subdirectory of it.
+   */
+  outputDir: string;
+  skipped: boolean;
+}
+
+export interface GenericEntrypoint extends BaseEntrypoint {
+  type:
+    | 'sandbox'
+    | 'bookmarks'
+    | 'history'
+    | 'newtab'
+    | 'devtools'
+    | 'unlisted-page'
+    | 'unlisted-script'
+    | 'unlisted-style'
+    | 'content-script-style';
+  options: ResolvedPerBrowserOptions<BaseEntrypointOptions>;
+}
+
+export interface BackgroundEntrypoint extends BaseEntrypoint {
+  type: 'background';
+  options: ResolvedPerBrowserOptions<BackgroundEntrypointOptions>;
+}
+
+export interface ContentScriptEntrypoint extends BaseEntrypoint {
+  type: 'content-script';
+  options: ResolvedPerBrowserOptions<
+    | MainWorldContentScriptEntrypointOptions
+    | IsolatedWorldContentScriptEntrypointOptions
+  >;
+}
+
+export interface PopupEntrypoint extends BaseEntrypoint {
+  type: 'popup';
+  options: ResolvedPerBrowserOptions<PopupEntrypointOptions, 'defaultIcon'>;
+}
+
+export interface OptionsEntrypoint extends BaseEntrypoint {
+  type: 'options';
+  options: ResolvedPerBrowserOptions<OptionsEntrypointOptions>;
+}
+
+export interface SidepanelEntrypoint extends BaseEntrypoint {
+  type: 'sidepanel';
+  options: ResolvedPerBrowserOptions<SidepanelEntrypointOptions, 'defaultIcon'>;
+}
+
+export type Entrypoint =
+  | GenericEntrypoint
+  | BackgroundEntrypoint
+  | ContentScriptEntrypoint
+  | PopupEntrypoint
+  | OptionsEntrypoint
+  | SidepanelEntrypoint;
+
+export type EntrypointGroup = Entrypoint | Entrypoint[];
+
+export type OnContentScriptStopped = (cb: () => void) => void;
+
+export interface IsolatedWorldContentScriptDefinition
+  extends IsolatedWorldContentScriptEntrypointOptions {
+  /**
+   * Main function executed when the content script is loaded.
+   */
+  main(ctx: ContentScriptContext): void | Promise<void>;
+}
+
+export interface MainWorldContentScriptDefinition
+  extends MainWorldContentScriptEntrypointOptions {
+  /**
+   * Main function executed when the content script is loaded.
+   */
+  main(): void | Promise<void>;
+}
+
+export type ContentScriptDefinition =
+  | IsolatedWorldContentScriptDefinition
+  | MainWorldContentScriptDefinition;
+
+export interface BackgroundDefinition extends BackgroundEntrypointOptions {
+  /**
+   * Main function executed when the background script is started. Cannot be async.
+   */
   main(): void;
 }
 
-export interface UnlistedScriptDefinition extends ExcludableEntrypoint {
+export interface UnlistedScriptDefinition extends BaseEntrypointOptions {
   /**
    * Main function executed when the unlisted script is ran.
    */
   main(): void | Promise<void>;
 }
 
-export type PerBrowserOption<T> = T | { [browser: TargetBrowser]: T };
+/**
+ * Either a single value or a map of different browsers to the value for that browser.
+ */
+export type PerBrowserOption<T> = T | PerBrowserMap<T>;
+export type PerBrowserMap<T> = { [browser: TargetBrowser]: T };
 
-export interface ExcludableEntrypoint {
-  /**
-   * List of target browsers to include this entrypoint in. Defaults to being included in all
-   * builds. Cannot be used with `exclude`. You must choose one of the two options.
-   *
-   * @default undefined
-   */
-  include?: TargetBrowser[];
-  /**
-   * List of target browsers to exclude this entrypoint from. Cannot be used with `include`. You
-   * must choose one of the two options.
-   *
-   * @default undefined
-   */
-  exclude?: TargetBrowser[];
-}
+/**
+ * Convert `{ key: PerBrowserOption<T> }` to just `{ key: T }`, stripping away the
+ * `PerBrowserOption` type for all fields inside the object.
+ *
+ * A optional second list of keys can be passed if a field isn't compatible with `PerBrowserOption`, like `defaultIcon`.
+ */
+export type ResolvedPerBrowserOptions<T, TOmitted extends keyof T = never> = {
+  [key in keyof Omit<T, TOmitted>]: T[key] extends PerBrowserOption<infer U>
+    ? U
+    : T[key];
+} & { [key in TOmitted]: T[key] };
 
 /**
  * Manifest customization available in the `wxt.config.ts` file. You cannot configure entrypoints
@@ -649,8 +721,6 @@ export type UserManifest = Partial<
     | 'options_page'
     | 'options_ui'
     | 'sandbox'
-    | 'sidepanel'
-    | 'sidebar_action'
   >
 >;
 

src/virtual/background-entrypoint.ts

@@ -39,7 +39,7 @@ try {
   // @ts-expect-error: res shouldn't be a promise, but we're checking it anyways
   if (res instanceof Promise) {
     console.warn(
-      "The background's main() function return a promise, but it must be synchonous",
+      "The background's main() function return a promise, but it must be synchronous",
     );
   }
 } catch (err) {

src/virtual/utils/reload-content-scripts.ts

@@ -7,17 +7,34 @@ interface ContentScript {
   js?: string[];
   css?: string[];
 }
+interface ReloadContentScriptPayload {
+  registration?: 'manifest' | 'runtime';
+  contentScript: ContentScript;
+}
 
-export function reloadContentScript(contentScript: ContentScript) {
+export function reloadContentScript(payload: ReloadContentScriptPayload) {
   const manifest = browser.runtime.getManifest();
   if (manifest.manifest_version == 2) {
-    void reloadContentScriptMv2(contentScript);
+    void reloadContentScriptMv2(payload);
   } else {
-    void reloadContentScriptMv3(contentScript);
+    void reloadContentScriptMv3(payload);
   }
 }
 
-export async function reloadContentScriptMv3(contentScript: ContentScript) {
+export async function reloadContentScriptMv3({
+  registration,
+  contentScript,
+}: ReloadContentScriptPayload) {
+  if (registration === 'runtime') {
+    await reloadRuntimeContentScriptMv3(contentScript);
+  } else {
+    await reloadRuntimeContentScriptMv3(contentScript);
+  }
+}
+
+export async function reloadManifestContentScriptMv3(
+  contentScript: ContentScript,
+) {
   const id = `wxt:${contentScript.js![0]}`;
   logger.log('Reloading content script:', contentScript);
   const registered = await browser.scripting.getRegisteredContentScripts();
@@ -33,6 +50,35 @@ export async function reloadContentScriptMv3(contentScript: ContentScript) {
     await browser.scripting.registerContentScripts([{ ...contentScript, id }]);
   }
 
+  await reloadTabsForContentScript(contentScript);
+}
+
+export async function reloadRuntimeContentScriptMv3(
+  contentScript: ContentScript,
+) {
+  logger.log('Reloading content script:', contentScript);
+  const registered = await browser.scripting.getRegisteredContentScripts();
+  logger.debug('Existing scripts:', registered);
+
+  const matches = registered.filter((cs) => {
+    const hasJs = contentScript.js?.find((js) => cs.js?.includes(js));
+    const hasCss = contentScript.css?.find((css) => cs.css?.includes(css));
+    return hasJs || hasCss;
+  });
+
+  if (matches.length === 0) {
+    logger.log(
+      'Content script is not registered yet, nothing to reload',
+      contentScript,
+    );
+    return;
+  }
+
+  await browser.scripting.updateContentScripts(matches);
+  await reloadTabsForContentScript(contentScript);
+}
+
+async function reloadTabsForContentScript(contentScript: ContentScript) {
   const allTabs = await browser.tabs.query({});
   const matchPatterns = contentScript.matches.map(
     (match) => new MatchPattern(match),
@@ -45,6 +91,8 @@ export async function reloadContentScriptMv3(contentScript: ContentScript) {
   await Promise.all(matchingTabs.map((tab) => browser.tabs.reload(tab.id)));
 }
 
-export async function reloadContentScriptMv2(contentScript: ContentScript) {
+export async function reloadContentScriptMv2(
+  _payload: ReloadContentScriptPayload,
+) {
   throw Error('TODO: reloadContentScriptMv2');
 }