chore(release): v0.14.7

This closes #324

.github/workflows/validate.yml

@@ -30,10 +30,10 @@ jobs:
     steps:
       - uses: actions/checkout@v3
       - uses: ./.github/actions/setup
-      - run: pnpm build:all
-        working-directory: demo
       - run: pnpm tsc --noEmit
         working-directory: demo
+      - run: pnpm build:all
+        working-directory: demo
       - run: pnpm wxt zip
         working-directory: demo
       - run: pnpm vitest run

CHANGELOG.md

@@ -1,5 +1,137 @@
 # Changelog
 
+## v0.14.7
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.14.6...v0.14.7)
+
+### 🩹 Fixes
+
+- Improve error messages when importing and building entrypoints ([3b63a51](https://github.com/wxt-dev/wxt/commit/3b63a51))
+- **storage:** Throw better error message when importing outside a extension environment ([35865ad](https://github.com/wxt-dev/wxt/commit/35865ad))
+- Upgrade `web-ext-run` ([62ecb6f](https://github.com/wxt-dev/wxt/commit/62ecb6f))
+
+### 📖 Documentation
+
+- Add `matches` to content script examples ([dab8efa](https://github.com/wxt-dev/wxt/commit/dab8efa))
+- Fix incorrect sample code ([#372](https://github.com/wxt-dev/wxt/pull/372))
+- Document defined constants for the build target ([68874e6](https://github.com/wxt-dev/wxt/commit/68874e6))
+- Add missing `await` to `createShadowRootUi` examples ([fc45c37](https://github.com/wxt-dev/wxt/commit/fc45c37))
+
+### ❤️ Contributors
+
+- 東奈比 ([@dongnaebi](http://github.com/dongnaebi))
+
+## v0.14.6
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.14.5...v0.14.6)
+
+### 🚀 Enhancements
+
+- Restart dev mode when saving config ([#365](https://github.com/wxt-dev/wxt/pull/365))
+- Add basic validation for entrypoint options ([#368](https://github.com/wxt-dev/wxt/pull/368))
+
+### 🩹 Fixes
+
+- Add subdependency bin directory so `wxt build --analyze` works with PNPM ([#363](https://github.com/wxt-dev/wxt/pull/363))
+- Sort build output files naturally ([#364](https://github.com/wxt-dev/wxt/pull/364))
+
+### 🤖 CI
+
+- Check for type errors in demo before building ([4b005b4](https://github.com/wxt-dev/wxt/commit/4b005b4))
+
+## v0.14.5
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.14.4...v0.14.5)
+
+### 🚀 Enhancements
+
+- Add `dev.reloadCommand` config ([#362](https://github.com/wxt-dev/wxt/pull/362))
+
+### 🩹 Fixes
+
+- Disable reload dev command when 4 commands are already registered ([#361](https://github.com/wxt-dev/wxt/pull/361))
+
+## v0.14.4
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.14.3...v0.14.4)
+
+### 🩹 Fixes
+
+- Allow requiring built-in node modules from ESM CLI ([#356](https://github.com/wxt-dev/wxt/pull/356))
+
+### 🏡 Chore
+
+- Add unit tests for passing flags via the CLI ([#354](https://github.com/wxt-dev/wxt/pull/354))
+
+## v0.14.3
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.14.2...v0.14.3)
+
+### 🩹 Fixes
+
+- Make `getArrayFromFlags` result can be undefined ([#352](https://github.com/wxt-dev/wxt/pull/352))
+
+### ❤️ Contributors
+
+- Yuns ([@yunsii](http://github.com/yunsii))
+
+## v0.14.2
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.14.1...v0.14.2)
+
+### 🚀 Enhancements
+
+- Add `filterEntrypoints` option to speed up development ([#344](https://github.com/wxt-dev/wxt/pull/344))
+
+### 🔥 Performance
+
+- Only call `findEntrypoint` once per build ([#342](https://github.com/wxt-dev/wxt/pull/342))
+
+### 🩹 Fixes
+
+- Improve error message and document use of imported variables outside an entrypoint's `main` function ([#346](https://github.com/wxt-dev/wxt/pull/346))
+- Allow `browser.runtime.getURL` to include hashes and query params for HTML paths ([#350](https://github.com/wxt-dev/wxt/pull/350))
+
+### 📖 Documentation
+
+- Fix typos and outdated ui function usage ([#347](https://github.com/wxt-dev/wxt/pull/347))
+
+### 🏡 Chore
+
+- Update templates to `^0.14.0` ([70a4961](https://github.com/wxt-dev/wxt/commit/70a4961))
+- Fix typo in function name ([a329e24](https://github.com/wxt-dev/wxt/commit/a329e24))
+
+### ❤️ Contributors
+
+- Yuns ([@yunsii](http://github.com/yunsii))
+- Armin
+
+## v0.14.1
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.14.0...v0.14.1)
+
+### 🩹 Fixes
+
+- Use `Alt+R`/`Opt+R` to reload extension during development ([b6ab7a9](https://github.com/wxt-dev/wxt/commit/b6ab7a9))
+
+## v0.14.0
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.13.5...v0.14.0)
+
+### 🚀 Enhancements
+
+- ⚠️  Refactor content script UI functions and add helper for "integrated" UIs ([#333](https://github.com/wxt-dev/wxt/pull/333))
+
+#### ⚠️ Breaking Changes
+
+`createContentScriptUi` and `createContentScriptIframe`, and some of their options, have been renamed:
+
+- `createContentScriptUi({ ... })` → `createShadowRootUi({ ... })`
+- `createContentScriptIframe({ ... })` → `createIframeUi({ ... })`
+- `type: "inline" | "overlay" | "modal"` has been changed to `position: "inline" | "overlay" | "modal"`
+- `onRemove` is now called ***before*** the UI is removed from the DOM, previously it was called after the UI was removed
+- `mount` option has been renamed to `onMount`, to better match the related option, `onRemove`.
+
 ## v0.13.5
 
 [compare changes](https://github.com/wxt-dev/wxt/compare/v0.13.4...v0.13.5)

demo/src/entrypoints/background.ts

@@ -15,6 +15,10 @@ export default defineBackground(() => {
   browser.runtime.getURL('/');
   browser.runtime.getURL('/background.js');
   browser.runtime.getURL('/icon/128.png');
+  browser.runtime.getURL('/example.html#hash');
+  browser.runtime.getURL('/example.html?query=param');
+  // @ts-expect-error: should only allow hashes/query params on HTML files
+  browser.runtime.getURL('/icon-128.png?query=param');
 
   // @ts-expect-error: should only accept known message names
   browser.i18n.getMessage('test');

demo/src/entrypoints/iframe.content.ts

@@ -2,9 +2,9 @@ export default defineContentScript({
   matches: ['*://*.google.com/*'],
 
   main(ctx) {
-    const ui = createContentScriptIframe(ctx, {
+    const ui = createIframeUi(ctx, {
       page: '/iframe-src.html',
-      type: 'overlay',
+      position: 'overlay',
       anchor: 'form[action="/search"]',
     });
     ui.mount();

demo/src/entrypoints/ui.content/index.ts

@@ -6,12 +6,12 @@ export default defineContentScript({
   cssInjectionMode: 'ui',
 
   async main(ctx) {
-    const ui = await createContentScriptUi(ctx, {
+    const ui = await createShadowRootUi(ctx, {
       name: 'demo-ui',
-      type: 'inline',
+      position: 'inline',
       append: 'before',
       anchor: 'form[role=search]',
-      mount: (container) => {
+      onMount: (container) => {
         const app = document.createElement('div');
         app.textContent = 'Custom content script UI';
         container.append(app);

docs/guide/auto-imports.md

@@ -14,7 +14,9 @@ Some WXT APIs can be used without importing them:
 - [`defineContentScript`](/api/wxt/sandbox/functions/defineContentScript) from `wxt/sandbox`
 - [`defineBackground`](/api/wxt/sandbox/functions/defineBackground) from `wxt/sandbox`
 - [`defineUnlistedScript`](/api/wxt/sandbox/functions/defineUnlistedScript) from `wxt/sandbox`
-- [`createContentScriptUi`](/api/wxt/client/functions/createContentScriptUi) from `wxt/client`
+- [`createIntegratedUi`](/api/wxt/client/functions/createIntegratedUi) from `wxt/client`
+- [`createShadowRootUi`](/api/wxt/client/functions/createShadowRootUi) from `wxt/client`
+- [`createIframeUi`](/api/wxt/client/functions/createIframeUi) from `wxt/client`
 - [`fakeBrowser`](/api/wxt/testing/variables/fakeBrowser) from `wxt/testing`
 
 And more!

docs/guide/content-script-ui.md

@@ -6,35 +6,37 @@ There are three ways to mount a UI inside a content script:
 
 Each has their own set of advantages and disadvantages.
 
-| Method     | Isolated Styles |   Isolated Events   | HMR | Use page's context |
-| ---------- | :-------------: | :-----------------: | :-: | :----------------: |
-| Integrated |       ❌        |         ❌          | ❌  |         ✅         |
-| ShadowRoot |       ✅        | ✅ (off by default) | ❌  |         ✅         |
-| IFrame     |       ✅        |         ✅          | ✅  |         ❌         |
+| Method      | Isolated Styles |   Isolated Events   | HMR | Use page's context |
+| ----------- | :-------------: | :-----------------: | :-: | :----------------: |
+| Integrated  |       ❌        |         ❌          | ❌  |         ✅         |
+| Shadow Root |       ✅        | ✅ (off by default) | ❌  |         ✅         |
+| IFrame      |       ✅        |         ✅          | ✅  |         ❌         |
 
 ## Integrated
 
 Integrated content script UIs are injected alongside the content of a page. This means that they are affected by CSS on that page.
 
-You can control how CSS is injected for an integrated content script UI with the [`cssInjectionMode`](/api/wxt/interfaces/ContentScriptBaseDefinition#cssinjectionmode) property.
-
 :::code-group
 
 ```ts [Vanilla]
 // entrypoints/example-ui.content.ts
 export default defineContentScript({
+  matches: ['<all_urls>'],
+
   main(ctx) {
-    // Create the UI container
-    const container = document.createElement('div');
-
-    // Add UI container to the page
-    const anchor = document.querySelector('#anchor');
-    anchore.append(container);
-
-    // Remove UI container when invalidated
-    ctx.onInvalidated(() => {
-      container.remove();
+    const ui = createIntegratedUi(ctx, {
+      position: 'inline',
+      anchor: '#anchor',
+      onMount: (container) => {
+        // Append children to the container
+        const app = document.createElement('p');
+        app.textContent = '...';
+        container.append(app);
+      },
     });
+
+    // Call mount to add the UI to the DOM
+    ui.mount();
   },
 });
 ```
@@ -42,25 +44,29 @@ export default defineContentScript({
 ```ts [Vue]
 // entrypoints/example-ui.content/index.ts
 import { createApp } from 'vue';
+import App from './App.vue';
 
 export default defineContentScript({
+  matches: ['<all_urls>'],
+
   main(ctx) {
-    // Create the UI container
-    const container = document.createElement('div');
-
-    // Create the app and mount it to the UI container
-    const app = createApp(...);
-    app.mount(container);
-
-    // Add UI container to the page
-    const anchor = document.querySelector('#anchor');
-    anchore.append(container);
-
-    // Unmount the app and remove UI container when invalidated
-    ctx.onInvalidated(() => {
-      app.unmount();
-      container.remove();
+    const ui = createIntegratedUi(ctx, {
+      position: 'inline',
+      anchor: '#anchor',
+      onMount: (container) => {
+        // Create the app and mount it to the UI container
+        const app = createApp(App);
+        app.mount(container);
+        return app;
+      },
+      onRemove: (app) => {
+        // Unmount the app when the UI is removed
+        app.unmount();
+      },
     });
+
+    // Call mount to add the UI to the DOM
+    ui.mount();
   },
 });
 ```
@@ -68,52 +74,59 @@ export default defineContentScript({
 ```tsx [React]
 // entrypoints/example-ui.content/index.tsx
 import ReactDOM from 'react-dom/client';
+import App from './App.tsx';
 
 export default defineContentScript({
+  matches: ['<all_urls>'],
+
   main(ctx) {
-    // Create the UI container
-    const container = document.createElement('div');
-
-    // Create a root on the UI container and render a component
-    const root = ReactDOM.createRoot(container);
-    root.render(...);
-
-    // Add UI container to the page
-    const anchor = document.querySelector('#anchor');
-    anchore.append(container);
-
-    // Unmount the root and remove UI container when invalidated
-    ctx.onInvalidated(() => {
-      root.unmount();
-      container.remove();
+    const ui = createIntegratedUi(ctx, {
+      position: 'inline',
+      anchor: '#anchor',
+      onMount: (container) => {
+        // Create a root on the UI container and render a component
+        const root = ReactDOM.createRoot(container);
+        root.render(<App />);
+        return root;
+      },
+      onRemove: (root) => {
+        // Unmount the root when the UI is removed
+        root.unmount();
+      },
     });
+
+    // Call mount to add the UI to the DOM
+    ui.mount();
   },
 });
 ```
 
-```ts [Svelete]
+```ts [Svelte]
 // entrypoints/example-ui.content/index.ts
 import App from './App.svelte';
 
 export default defineContentScript({
+  matches: ['<all_urls>'],
+
   main(ctx) {
-    // Create the UI container
-    const container = document.createElement('div');
-
-    // Create the Svelte app inside the UI container
-    const app = new App({
-      target: ui,
+    const ui = createIntegratedUi(ctx, {
+      position: 'inline',
+      anchor: '#anchor',
+      onMount: (container) => {
+        // Create the Svelte app inside the UI container
+        const app = new App({
+          target: container,
+        });
+        return app;
+      },
+      onRemove: (app) => {
+        // Destroy the app when the UI is removed
+        app.$destroy();
+      },
     });
 
-    // Add UI container to the page
-    const anchor = document.querySelector('#anchor');
-    anchore.append(container);
-
-    // Destroy the app and remove UI container when invalidated
-    ctx.onInvalidated(() => {
-      app.$destroy();
-      container.remove();
-    });
+    // Call mount to add the UI to the DOM
+    ui.mount();
   },
 });
 ```
@@ -123,56 +136,65 @@ export default defineContentScript({
 import { render } from 'solid-js/web';
 
 export default defineContentScript({
+  matches: ['<all_urls>'],
+
   main(ctx) {
-    // Create the UI container
-    const container = document.createElement('div');
-
-    // Render your app to the UI container
-    const unmount = render(() => ..., container)
-
-    // Add UI container to the page
-    const anchor = document.querySelector('#anchor');
-    anchore.append(container);
-
-    // Unmount the app and remove UI container when invalidated
-    ctx.onInvalidated(() => {
-      unmount();
-      container.remove();
+    const ui = createIntegratedUi(ctx, {
+      position: 'inline',
+      anchor: '#anchor',
+      onMount: (container) => {
+        // Render your app to the UI container
+        const unmount = render(() => <div>...</div>, container);
+      },
+      onRemove: (unmount) => {
+        // Unmount the app when the UI is removed
+        unmount();
+      },
     });
+
+    // Call mount to add the UI to the DOM
+    ui.mount();
   },
 });
 ```
 
 :::
 
-## ShadowRoot
+See the [API Reference](/api/wxt/client/functions/createIntegratedUi) for the complete list of options.
+
+You can control how CSS is injected for an integrated content script UI with the [`cssInjectionMode`](/api/wxt/interfaces/ContentScriptBaseDefinition#cssinjectionmode) property. Usually, you'll want to leave it as `"manifest"`, the default, so the UI inherits its style from the website's CSS.
+
+## Shadow Root
 
 Often in web extensions, you don't want your content script's CSS affecting the page, or vise-versa. The [`ShadowRoot`](https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot) API is ideal for this.
 
-WXT provides a helper function, [`createContentScriptUi`](/api/wxt/client/functions/createContentScriptUi), that abstracts all the `ShadowRoot` setup away, making it easy to create UIs with isolated CSS. It also supports an optional `isolateEvents` parameter to further isolate user interactions.
+WXT's [`createShadowRootUi`](/api/wxt/client/functions/createShadowRootUi) abstracts all the `ShadowRoot` setup away, making it easy to create UIs with isolated CSS. It also supports an optional `isolateEvents` parameter to further isolate user interactions.
 
-To use `createContentScriptUi`, follow these steps:
+To use `createShadowRootUi`, follow these steps:
 
 1. Import your CSS file at the top of your content script
 2. Set [`cssInjectionMode: "ui"`](/api/wxt/interfaces/ContentScriptBaseDefinition#cssinjectionmode) inside `defineContentScript`
-3. Define your UI with `createContentScriptUi()`
+3. Define your UI with `createShadowRootUi()`
 4. Mount the UI so it is visible to users
 
-```ts
+:::code-group
+
+```ts [Vanilla]
 // 1. Import the style
 import './style.css';
 
 export default defineContentScript({
+  matches: ['<all_urls>'],
   // 2. Set cssInjectionMode
   cssInjectionMode: 'ui',
 
   async main(ctx) {
     // 3. Define your UI
-    const ui = await createContentScriptUi(ctx, {
+    const ui = await createShadowRootUi(ctx, {
       name: 'example-ui',
       anchor: '#anchor',
-      type: 'inline',
-      mount(container) {
+      position: 'inline',
+      onMount(container) {
         // Define how your UI will be mounted inside the container
         const app = document.createElement('p');
         app.textContent = 'Hello world!';
@@ -186,91 +208,156 @@ export default defineContentScript({
 });
 ```
 
-> `createContentScriptUi` will automatically remove the UI from the page when the content script is invalidated.
-
-See the [API Reference](/api/wxt/client/functions/createContentScriptUi) for the complete list of options.
-
-:::info TailwindCSS
-`createContentScriptUi` supports TailwindCSS out of the box! When importing the styles, just import the main CSS file containing the `@tailwind` directives, and everything will just work :+1:.
-:::
-
-When using a frontend framework for your UI, you'll need to unmount the app when the UI is removed. This is accomplished by returning an app reference from the `mount` option and by passing in a custom `onRemoved` option:
-
-:::code-group
-
 ```ts [Vue]
+// 1. Import the style
+import './style.css';
 import { createApp } from 'vue';
+import App from './App.vue';
 
-const ui = createContentScriptUi(ctx, {
-  // ...
-  mount(container) {
-    const app = createApp(App);
-    app.mount(container);
-    return app;
-  },
-  onRemove(app) {
-    app.unmount();
+export default defineContentScript({
+  matches: ['<all_urls>'],
+  // 2. Set cssInjectionMode
+  cssInjectionMode: 'ui',
+
+  async main(ctx) {
+    // 3. Define your UI
+    const ui = await createShadowRootUi(ctx, {
+      name: 'example-ui',
+      anchor: '#anchor',
+      position: 'inline',
+      onMount: (container) => {
+        // Define how your UI will be mounted inside the container
+        const app = createApp(App);
+        app.mount(container);
+        return app;
+      },
+      onRemove: (app) => {
+        // Unmount the app when the UI is removed
+        app.unmount();
+      },
+    });
+
+    // 4. Mount the UI
+    ui.mount();
   },
 });
 ```
 
 ```tsx [React]
+// 1. Import the style
+import './style.css';
 import ReactDOM from 'react-dom/client';
+import App from './App.tsx';
 
-const ui = createContentScriptUi(ctx, {
-  // ...
-  mount(container) {
-    const root = ReactDOM.createRoot(container);
-    root.render(...);
-    return root;
-  },
-  onRemove(root) {
-    root.unmount();
+export default defineContentScript({
+  matches: ['<all_urls>'],
+  // 2. Set cssInjectionMode
+  cssInjectionMode: 'ui',
+
+  async main(ctx) {
+    // 3. Define your UI
+    const ui = await createShadowRootUi(ctx, {
+      name: 'example-ui',
+      position: 'inline',
+      anchor: '#anchor',
+      onMount: (container) => {
+        // Create a root on the UI container and render a component
+        const root = ReactDOM.createRoot(container);
+        root.render(<App />);
+        return root;
+      },
+      onRemove: (root) => {
+        // Unmount the root when the UI is removed
+        root.unmount();
+      },
+    });
+
+    // 4. Mount the UI
+    ui.mount();
   },
 });
 ```
 
 ```ts [Svelte]
+// 1. Import the style
+import './style.css';
 import App from './App.svelte';
 
-const ui = createContentScriptUi(ctx, {
-  // ...
-  mount(container) {
-    return new App({ target: container });
-  },
-  onRemove(app) {
-    app.$destry();
+export default defineContentScript({
+  matches: ['<all_urls>'],
+  // 2. Set cssInjectionMode
+  cssInjectionMode: 'ui',
+
+  async main(ctx) {
+    // 3. Define your UI
+    const ui = await createShadowRootUi(ctx, {
+      name: 'example-ui',
+      position: 'inline',
+      anchor: '#anchor',
+      onMount: (container) => {
+        // Create the Svelte app inside the UI container
+        const app = new App({
+          target: container,
+        });
+        return app;
+      },
+      onRemove: (app) => {
+        // Destroy the app when the UI is removed
+        app.$destroy();
+      },
+    });
+
+    // 4. Mount the UI
+    ui.mount();
   },
 });
 ```
 
 ```tsx [Solid]
+// 1. Import the style
+import './style.css';
 import { render } from 'solid-js/web';
 
-const ui = createContentScriptUi(ctx, {
-  // ...
-  mount(container) {
-    return render(() => ..., container);
-  },
-  onRemove(unmount) {
-    unmount();
+export default defineContentScript({
+  matches: ['<all_urls>'],
+  // 2. Set cssInjectionMode
+  cssInjectionMode: 'ui',
+
+  async main(ctx) {
+    // 3. Define your UI
+    const ui = await createShadowRootUi(ctx, {
+      name: 'example-ui',
+      position: 'inline',
+      anchor: '#anchor',
+      onMount: (container) => {
+        // Render your app to the UI container
+        const unmount = render(() => <div>...</div>, container);
+      },
+      onRemove: (unmount) => {
+        // Unmount the app when the UI is removed
+        unmount();
+      },
+    });
+
+    // 4. Mount the UI
+    ui.mount();
   },
 });
 ```
 
 :::
 
-:::warning
-The `mount(container)` and `onRemove(app)` options passed into `createContentScriptUi` **_are different from_** the `ui.mount()` and `ui.remove()` functions available on the returned UI object.
+See the [API Reference](/api/wxt/client/functions/createShadowRootUi) for the complete list of options.
 
-You don't need to pass anything into `ui.mount()` and `ui.remove()` because **_you already defined how and where the UI will be mounted_** in the options passed into `createContentScriptUi`.
+:::info TailwindCSS
+`createShadowRootUi` supports TailwindCSS out of the box! When importing the styles, just import the main CSS file containing the `@tailwind` directives, and everything will just work :+1:.
 :::
 
 ## IFrame
 
 If you don't need to run your UI in the same frame as the content script, you can use an IFrame to host your UI instead. Since an IFrame just hosts an HTML page, **_HMR is supported_**.
 
-WXT provides a helper function, [`createContentScriptIframe`](/api/wxt/client/functions/createContentScriptUi), which simplifies setting up the IFrame.
+WXT provides a helper function, [`createIframeUi`](/api/wxt/client/functions/createIframeUi), which simplifies setting up the IFrame.
 
 1. Create an HTML page that will be loaded into your IFrame
    ```html
@@ -305,22 +392,24 @@ WXT provides a helper function, [`createContentScriptIframe`](/api/wxt/client/fu
 
    ```ts
    export default defineContentScript({
-     // ...
+     matches: ['<all_urls>'],
+
      async main(ctx) {
        // Define the UI
-       const ui = await createContentScriptIframe(ctx, {
+       const ui = await createIframeUi(ctx, {
          page: '/example-iframe.html',
          anchor: '#anchor',
-         type: 'inline',
+         position: 'inline',
+         onMount: (wrapper, iframe) => {
+           // Add styles to the iframe like width
+           iframe.width = 123;
+         },
        });
 
-       // Add styles to the iframe like width
-       ui.iframe.width = 123;
-
        // Show UI to user
        ui.mount();
      },
    });
    ```
 
-See the [API Reference](/api/wxt/client/functions/createContentScriptUi) for the complete list of options.
+See the [API Reference](/api/wxt/client/functions/createIframeUi) for the complete list of options.

docs/guide/entrypoints.md

@@ -86,3 +86,56 @@ export default defineContentScript({
 :::info
 For a full list of entrypoints and each of their options, see the [`/entrypoints` folder](/entrypoints/background) documentation.
 :::
+
+### Side Effects
+
+You cannot use imported variables outside the `main` function is JS entrypoints. This includes options, as shown below:
+
+```ts
+// entrypoints/content.ts
+import { GOOGLE_MATCHES } from '~/utils/match-patterns';
+
+export default defineContentScript({
+  matches: GOOGLE_MATCHES,
+  main() {
+    // ...
+  },
+});
+```
+
+```
+$ wxt build
+wxt build
+
+WXT 0.14.1
+ℹ Building chrome-mv3 for production with Vite 5.0.5
+✖ Command failed after 360 ms
+
+[8:55:54 AM]  ERROR  entrypoints/content.ts: Cannot use imported variable "GOOGLE_MATCHES" before main function. See https://wxt.dev/guide/entrypoints.html#side-effects
+```
+
+This throws an error because WXT needs to import each entrypoint during the build process to extract its definition (containing the `match`, `run_at`, `include`/`exclude`, etc.) to render the `manifest.json` correctly. Before loading an entrypoint, a transformation is applied to remove all imports. This prevents imported modules (local or NPM) with side-effects from running during the build process, potentially throwing an error.
+
+:::details Why?
+
+When importing your entrypoint to get its definition, the file is imported in a **_node environement_**, and doesn't have access to the `window`, `chrome`, or `browser` globals a web extension ususally has access to. If WXT doesn't remove all the imports from the file, the imported modules could try and access one of these variables, throwing an error.
+
+:::
+
+:::warning
+See [`wxt-dev/wxt#336`](https://github.com/wxt-dev/wxt/issues/336) to track the status of this bug.
+:::
+
+Usually, this error occurs when you try to extract options into a shared file or try to run code outside the `main` function. To fix the example from above, use litteral values when defining an entrypoint instead of importing them:
+
+```ts
+import { GOOGLE_MATCHES } from '~/utils/match-patterns'; // [!code --]
+
+export default defineContentScript({
+  matches: GOOGLE_MATCHES, // [!code --]
+  matches: ['*//*.google.com/*'], // [!code ++]
+  main() {
+    // ...
+  },
+});
+```

docs/guide/multiple-browsers.md

@@ -17,11 +17,9 @@ Separate build targets are written to their own output directories:
 
 To build for a specific browser, pass the `-b --browser` flag from the CLI:
 
-```
-
+```sh
 wxt --browser firefox
 wxt build --browser firefox
-
 ```
 
 By default, it will build for `chrome`. When excluding the [manifest version flags](#target-manifest-version), it will default to the commonly accepted manifest version for that browser.
@@ -112,3 +110,24 @@ export default defineContentScript({
 :::warning
 Only `defineBackground` and `defineContentScript` support per-browser options right now.
 :::
+
+## Runtime
+
+To determine the browser or manifest version at runtime, you can use any of the below variables:
+
+- `__BROWSER__`: A string, the target browser, usually equal to the `--browser` flag
+- `__MANIFEST_VERSION__`: A number, either `2` or `3`, depending on the manifest version targetted
+- `__IS_CHROME__`: A boolean equivalent to `__BROWSER__ === "chrome"`
+- `__IS_FIREFOX__`: A boolean equivalent to `__BROWSER__ === "firefox"`
+- `__IS_EDGE__`: A boolean equivalent to `__BROWSER__ === "edge"`
+- `__IS_SAFARI__`: A boolean equivalent to `__BROWSER__ === "safari"`
+- `__IS_OPERA__`: A boolean equivalent to `__BROWSER__ === "opera"`
+- `__COMMAND__`: A string, `"serve"` when running `wxt` for development or `"build"` in all other cases.
+
+:::info
+These variables are constants defined at build time based on the build target. They do not actually detect which browser the code is running in.
+
+For example, if you build for `--browser chrome` and publish it on Edge, `__BROWSER__` will be `"chrome"`, not `"edge"`. You have to build a separate ZIP for `--browser edge` before `__BROWSER__` will be `"edge"`.
+
+If you need to know the actual browser your code is being ran on, you should use a [user agent parser](https://www.npmjs.com/package/ua-parser-js).
+:::

e2e/tests/auto-imports.test.ts

@@ -20,8 +20,9 @@ describe('Auto Imports', () => {
             const InvalidMatchPattern: typeof import('wxt/sandbox')['InvalidMatchPattern']
             const MatchPattern: typeof import('wxt/sandbox')['MatchPattern']
             const browser: typeof import('wxt/browser')['browser']
-            const createContentScriptIframe: typeof import('wxt/client')['createContentScriptIframe']
-            const createContentScriptUi: typeof import('wxt/client')['createContentScriptUi']
+            const createIframeUi: typeof import('wxt/client')['createIframeUi']
+            const createIntegratedUi: typeof import('wxt/client')['createIntegratedUi']
+            const createShadowRootUi: typeof import('wxt/client')['createShadowRootUi']
             const defineBackground: typeof import('wxt/sandbox')['defineBackground']
             const defineConfig: typeof import('wxt')['defineConfig']
             const defineContentScript: typeof import('wxt/sandbox')['defineContentScript']

e2e/tests/typescript-project.test.ts

@@ -49,8 +49,10 @@ describe('TypeScript Project', () => {
           | "/options.html"
           | "/popup.html"
           | "/sandbox.html"
+        type HtmlPublicPath = Extract<PublicPath, \`\${string}.html\`>
         export interface WxtRuntime extends Runtime.Static {
           getURL(path: PublicPath): string;
+          getURL(path: \`\${HtmlPublicPath}\${string}\`): string;
         }
       }
       "

package.json

@@ -1,7 +1,7 @@
 {
   "name": "wxt",
   "type": "module",
-  "version": "0.13.5",
+  "version": "0.14.7",
   "description": "Next gen framework for developing web extensions",
   "engines": {
     "node": ">=18",
@@ -125,7 +125,9 @@
     "jiti": "^1.21.0",
     "json5": "^2.2.3",
     "linkedom": "^0.16.1",
+    "manage-path": "^2.0.0",
     "minimatch": "^9.0.3",
+    "natural-compare": "^1.4.0",
     "normalize-path": "^3.0.0",
     "ora": "^7.0.1",
     "picocolors": "^1.0.0",
@@ -133,7 +135,7 @@
     "rollup-plugin-visualizer": "^5.9.2",
     "unimport": "^3.4.0",
     "vite": "^5.0.0",
-    "web-ext-run": "^0.1.0",
+    "web-ext-run": "^0.1.2",
     "webextension-polyfill": "^0.10.0",
     "zip-dir": "^2.0.0"
   },
@@ -141,6 +143,7 @@
     "@faker-js/faker": "^8.3.1",
     "@types/fs-extra": "^11.0.4",
     "@types/lodash.merge": "^4.6.9",
+    "@types/natural-compare": "^1.4.3",
     "@types/node": "^20.10.3",
     "@types/normalize-path": "^3.0.2",
     "@types/prompts": "^2.4.9",

pnpm-lock.yaml

@@ -74,9 +74,15 @@ importers:
       linkedom:
         specifier: ^0.16.1
         version: 0.16.1
+      manage-path:
+        specifier: ^2.0.0
+        version: 2.0.0
       minimatch:
         specifier: ^9.0.3
         version: 9.0.3
+      natural-compare:
+        specifier: ^1.4.0
+        version: 1.4.0
       normalize-path:
         specifier: ^3.0.0
         version: 3.0.0
@@ -99,8 +105,8 @@ importers:
         specifier: ^5.0.0
         version: 5.0.5(@types/node@20.10.3)(sass@1.69.5)
       web-ext-run:
-        specifier: ^0.1.0
-        version: 0.1.0
+        specifier: ^0.1.2
+        version: 0.1.2
       webextension-polyfill:
         specifier: ^0.10.0
         version: 0.10.0
@@ -117,6 +123,9 @@ importers:
       '@types/lodash.merge':
         specifier: ^4.6.9
         version: 4.6.9
+      '@types/natural-compare':
+        specifier: ^1.4.3
+        version: 1.4.3
       '@types/node':
         specifier: ^20.10.3
         version: 20.10.3
@@ -403,8 +412,8 @@ packages:
       '@babel/types': 7.23.5
     dev: true
 
-  /@babel/runtime@7.22.11:
-    resolution: {integrity: sha512-ee7jVNlWN09+KftVOu9n7S8gQzD/Z6hN/I8VBRXW4P1+Xe7kJGXMwu8vds4aGIMHZnNbdpSWCfZZtinytpcAvA==}
+  /@babel/runtime@7.23.9:
+    resolution: {integrity: sha512-0CX6F+BI2s9dkUqr08KFrAIZgNFj75rdBU/DjCyYLIaV/quFjkk6T+EJ2LkZHyZTbEV4L5p97mNkUsHl2wLFAw==}
     engines: {node: '>=6.9.0'}
     dependencies:
       regenerator-runtime: 0.14.0
@@ -433,8 +442,8 @@ packages:
     engines: {node: '>= 0.10.4'}
     dev: false
 
-  /@devicefarmer/adbkit@3.2.5:
-    resolution: {integrity: sha512-+J479WWZW3GU3t40flicDfiDrFz6vpiy2RcBQPEhFcs/3La9pOtr4Bgz2Q02E4luUG2RAL068rqIkKNUTy3tZw==}
+  /@devicefarmer/adbkit@3.2.6:
+    resolution: {integrity: sha512-8lO1hSeTgtxcOHhp4tTWq/JaOysp5KNbbyFoxNEBnwkCDZu/Bji3ZfOaG++Riv9jN6c9bgdLBOZqJTC5VJPRKQ==}
     engines: {node: '>= 0.10.4'}
     hasBin: true
     dependencies:
@@ -1106,6 +1115,10 @@ packages:
     resolution: {integrity: sha512-Klz949h02Gz2uZCMGwDUSDS1YBlTdDDgbWHi+81l29tQALUtvz4rAYi5uoVhE5Lagoq6DeqAUlbrHvW/mXDgdQ==}
     dev: false
 
+  /@types/natural-compare@1.4.3:
+    resolution: {integrity: sha512-XCAxy+Gg6+S6VagwzcknnvCKujj/bVv1q+GFuCrFEelqaZPqJoC+FeXLwc2dp+oLP7qDZQ4ZfQiTJQ9sIUmlLw==}
+    dev: true
+
   /@types/node@20.10.3:
     resolution: {integrity: sha512-XJavIpZqiXID5Yxnxv3RUDKTN5b81ddNC3ecsA0SoFXz/QU8OGBwZGMomiq0zw+uuqbL/krztv/DINAQ/EV4gg==}
     dependencies:
@@ -2367,8 +2380,8 @@ packages:
     dependencies:
       to-regex-range: 5.0.1
 
-  /firefox-profile@4.3.2:
-    resolution: {integrity: sha512-/C+Eqa0YgIsQT2p66p7Ygzqe7NlE/GNTbhw2SBCm5V3OsWDPITNdTPEcH2Q2fe7eMpYYNPKdUcuVioZBZiR6kA==}
+  /firefox-profile@4.5.0:
+    resolution: {integrity: sha512-goE2XxbmYVSafvCjcy64/AK3xOr14HCUCD4+TpYWEIMy4nrJfNAacLGzwqKwZhCW0hHI2TYMGH+G/YBvOE8L6g==}
     hasBin: true
     dependencies:
       adm-zip: 0.5.10
@@ -2409,6 +2422,15 @@ packages:
       universalify: 2.0.0
     dev: false
 
+  /fs-extra@11.2.0:
+    resolution: {integrity: sha512-PmDi3uwK5nFuXh7XDTlVnS17xJS7vW36is2+w3xcv8SVxiB4NyATf4ctkVY5bkSjX0Y4nbvZCq1/EjtEyr9ktw==}
+    engines: {node: '>=14.14'}
+    dependencies:
+      graceful-fs: 4.2.11
+      jsonfile: 6.1.0
+      universalify: 2.0.0
+    dev: false
+
   /fs-extra@9.0.1:
     resolution: {integrity: sha512-h2iAoN838FqAFJY2/qVpzFXy+EBxfVE220PalAqQLDVsFOHLJrZvut5puAbCdNv6WJk+B8ihI+k0c7JK5erwqQ==}
     engines: {node: '>=10'}
@@ -2454,8 +2476,8 @@ packages:
     resolution: {integrity: sha512-xckBUXyTIqT97tq2x2AMb+g163b5JFysYk0x4qxNFwbfQkmNZoiRHb6sPzI9/QV33WeuvVYBUIiD4NzNIyqaRQ==}
     dev: true
 
-  /fx-runner@1.3.0:
-    resolution: {integrity: sha512-5b37H4GCyhF+Nf8xk9mylXoDq4wb7pbGAXxlCXp/631UTeeZomWSYcEGXumY4wk8g2QAqjPMGdWW+RbNt8PUcA==}
+  /fx-runner@1.4.0:
+    resolution: {integrity: sha512-rci1g6U0rdTg6bAaBboP7XdRu01dzTAaKXxFf+PUqGuCv6Xu7o8NZdY1D5MvKGIjb6EdS1g3VlXOgksir1uGkg==}
     hasBin: true
     dependencies:
       commander: 2.9.0
@@ -3352,6 +3374,10 @@ packages:
     resolution: {integrity: sha512-s8UhlNe7vPKomQhC1qFelMokr/Sc3AgNbso3n74mVPA5LTZwkB9NlXf4XPamLxJE8h0gh73rM94xvwRT2CVInw==}
     dev: false
 
+  /manage-path@2.0.0:
+    resolution: {integrity: sha512-NJhyB+PJYTpxhxZJ3lecIGgh4kwIY2RAh44XvAz9UlqthlQwtPBf62uBVR8XaD8CRuSjQ6TnZH2lNJkbLPZM2A==}
+    dev: false
+
   /mark.js@8.11.1:
     resolution: {integrity: sha512-1I+1qpDt4idfgLQG+BNWmrqku+7/2bi5nLf4YwF8y8zXvmfiTBY3PV3ZibfrjBueCByROpuBjLLFCajqkgYoLQ==}
     dev: true
@@ -3533,6 +3559,10 @@ packages:
     engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1}
     hasBin: true
 
+  /natural-compare@1.4.0:
+    resolution: {integrity: sha512-OWND8ei3VtNC9h7V60qff3SVobHr996CTwgxubgyQYEpg290h9J0buyECNNJexkFm5sOajh5G116RYA1c8ZMSw==}
+    dev: false
+
   /ncp@2.0.0:
     resolution: {integrity: sha512-zIdGUrPRFTUELUvr3Gmc7KZ2Sw/h1PiVM0Af/oHB6zgnV1ikqSfRk+TOufi79aHYCW3NiOXmr1BP5nWbzojLaA==}
     hasBin: true
@@ -3751,8 +3781,8 @@ packages:
       json-parse-better-errors: 1.0.2
     dev: true
 
-  /parse-json@7.1.0:
-    resolution: {integrity: sha512-ihtdrgbqdONYD156Ap6qTcaGcGdkdAxodO1wLqQ/j7HP1u2sFYppINiq4jyC8F+Nm+4fVufylCV00QmkTHkSUg==}
+  /parse-json@7.1.1:
+    resolution: {integrity: sha512-SgOTCX/EZXtZxBE5eJ97P4yGM5n37BwRU+YMsH4vNzFqJV/oWFXXCmwFlgWUM4PrakybVOueJJ6pwHqSVhTFDw==}
     engines: {node: '>=16'}
     dependencies:
       '@babel/code-frame': 7.22.5
@@ -5165,24 +5195,24 @@ packages:
       graceful-fs: 4.2.11
     dev: false
 
-  /web-ext-run@0.1.0:
-    resolution: {integrity: sha512-42ezvTBirf1v2hw0q4FqYvAzh39bCn3cMQojTLlaE5Y8DWebVkRGdd0jdSJRzPkB5jZa0CHfnqe8gx6oUllqyw==}
-    engines: {node: '>=16.0.0', npm: '>=8.0.0'}
+  /web-ext-run@0.1.2:
+    resolution: {integrity: sha512-VygO7lg10keonbku5Lbi21zEz1k91odkW+c6YB5DGb+mITcRMVM2zr/tJ+Suh6wxNUOOFNbinoqDlSUWdxt6YQ==}
+    engines: {node: '>=18.0.0', npm: '>=8.0.0'}
     dependencies:
-      '@babel/runtime': 7.22.11
-      '@devicefarmer/adbkit': 3.2.5
+      '@babel/runtime': 7.23.9
+      '@devicefarmer/adbkit': 3.2.6
       bunyan: 1.8.15
       chrome-launcher: 0.15.1
       debounce: 1.2.1
       es6-error: 4.1.1
-      firefox-profile: 4.3.2
-      fs-extra: 11.1.1
-      fx-runner: 1.3.0
+      firefox-profile: 4.5.0
+      fs-extra: 11.2.0
+      fx-runner: 1.4.0
       mkdirp: 1.0.4
       multimatch: 6.0.0
       mz: 2.7.0
       node-notifier: 10.0.1
-      parse-json: 7.1.0
+      parse-json: 7.1.1
       promise-toolbox: 0.21.0
       source-map-support: 0.5.21
       strip-bom: 5.0.0
@@ -5190,7 +5220,7 @@ packages:
       tmp: 0.2.1
       update-notifier: 6.0.2
       watchpack: 2.4.0
-      ws: 8.13.0
+      ws: 8.16.0
       zip-dir: 2.0.0
     transitivePeerDependencies:
       - bufferutil
@@ -5343,8 +5373,8 @@ packages:
       typedarray-to-buffer: 3.1.5
     dev: false
 
-  /ws@8.13.0:
-    resolution: {integrity: sha512-x9vcZYTrFPC7aSIbj7sRCYo7L/Xb8Iy+pW0ng0wt2vCJv7M9HOMy0UoN3rr+IFC7hb7vXoqS+P9ktyLLLhO+LA==}
+  /ws@8.16.0:
+    resolution: {integrity: sha512-HS0c//TP7Ina87TfiPUz1rQzMhHrl/SG2guqRcTOIUYD2q8uhUdNHZYJUaQ8aTGPzCh+c6oawMKW35nFl1dxyQ==}
     engines: {node: '>=10.0.0'}
     peerDependencies:
       bufferutil: ^4.0.1

scripts/build.ts

@@ -97,6 +97,11 @@ const config: tsup.Options[] = [
       cli: 'src/cli.ts',
     },
     format: ['esm'],
+    banner: {
+      // Fixes dynamic require of nodejs modules. See https://github.com/wxt-dev/wxt/issues/355
+      // https://github.com/evanw/esbuild/issues/1921#issuecomment-1152991694
+      js: "import { createRequire } from 'module';const require = createRequire(import.meta.url);",
+    },
   },
 ];
 

src/__tests__/cli.test.ts

@@ -0,0 +1,376 @@
+import { describe, it, vi, beforeEach, expect } from 'vitest';
+import { build } from '../core/build';
+import { createServer } from '../core/create-server';
+import { zip } from '../core/zip';
+import { prepare } from '../core/prepare';
+import { clean } from '../core/clean';
+import { initialize } from '../core/initialize';
+import { mock } from 'vitest-mock-extended';
+import consola from 'consola';
+
+vi.mock('../core/build');
+const buildMock = vi.mocked(build);
+
+vi.mock('../core/create-server');
+const createServerMock = vi.mocked(createServer);
+
+vi.mock('../core/zip');
+const zipMock = vi.mocked(zip);
+
+vi.mock('../core/prepare');
+const prepareMock = vi.mocked(prepare);
+
+vi.mock('../core/clean');
+const cleanMock = vi.mocked(clean);
+
+vi.mock('../core/initialize');
+const initializeMock = vi.mocked(initialize);
+
+consola.wrapConsole();
+
+const ogArgv = process.argv;
+
+function mockArgv(...args: string[]) {
+  process.argv = ['/bin/node', 'bin/wxt.mjs', ...args];
+}
+
+describe('CLI', () => {
+  beforeEach(() => {
+    vi.resetModules();
+    process.argv = ogArgv;
+    createServerMock.mockResolvedValue(mock());
+  });
+
+  describe('dev', () => {
+    it('should not pass any config when no flags are passed', async () => {
+      mockArgv();
+      await import('../cli');
+
+      expect(createServerMock).toBeCalledWith({});
+    });
+
+    it('should respect passing a custom root', async () => {
+      mockArgv('path/to/root');
+      await import('../cli');
+
+      expect(createServerMock).toBeCalledWith({
+        root: 'path/to/root',
+      });
+    });
+
+    it('should respect a custom config file', async () => {
+      mockArgv('-c', './path/to/config.ts');
+      await import('../cli');
+
+      expect(createServerMock).toBeCalledWith({
+        configFile: './path/to/config.ts',
+      });
+    });
+
+    it('should respect passing a custom mode', async () => {
+      mockArgv('-m', 'development');
+      await import('../cli');
+
+      expect(createServerMock).toBeCalledWith({
+        mode: 'development',
+      });
+    });
+
+    it('should respect passing a custom browser', async () => {
+      mockArgv('-b', 'firefox');
+      await import('../cli');
+
+      expect(createServerMock).toBeCalledWith({
+        browser: 'firefox',
+      });
+    });
+
+    it('should pass correct filtered entrypoints', async () => {
+      mockArgv('-e', 'popup', '-e', 'options');
+      await import('../cli');
+
+      expect(createServerMock).toBeCalledWith({
+        filterEntrypoints: ['popup', 'options'],
+      });
+    });
+
+    it('should respect passing --mv2', async () => {
+      mockArgv('--mv2');
+      await import('../cli');
+
+      expect(createServerMock).toBeCalledWith({
+        manifestVersion: 2,
+      });
+    });
+
+    it('should respect passing --mv3', async () => {
+      mockArgv('--mv3');
+      await import('../cli');
+
+      expect(createServerMock).toBeCalledWith({
+        manifestVersion: 3,
+      });
+    });
+
+    it('should respect passing --debug', async () => {
+      mockArgv('--debug');
+      await import('../cli');
+
+      expect(createServerMock).toBeCalledWith({
+        debug: true,
+      });
+    });
+  });
+
+  describe('build', () => {
+    it('should not pass any config when no flags are passed', async () => {
+      mockArgv('build');
+      await import('../cli');
+
+      expect(buildMock).toBeCalledWith({});
+    });
+
+    it('should respect passing a custom root', async () => {
+      mockArgv('build', 'path/to/root');
+      await import('../cli');
+
+      expect(buildMock).toBeCalledWith({
+        root: 'path/to/root',
+      });
+    });
+
+    it('should respect a custom config file', async () => {
+      mockArgv('build', '-c', './path/to/config.ts');
+      await import('../cli');
+
+      expect(buildMock).toBeCalledWith({
+        configFile: './path/to/config.ts',
+      });
+    });
+
+    it('should respect passing a custom mode', async () => {
+      mockArgv('build', '-m', 'development');
+      await import('../cli');
+
+      expect(buildMock).toBeCalledWith({
+        mode: 'development',
+      });
+    });
+
+    it('should respect passing a custom browser', async () => {
+      mockArgv('build', '-b', 'firefox');
+      await import('../cli');
+
+      expect(buildMock).toBeCalledWith({
+        browser: 'firefox',
+      });
+    });
+
+    it('should pass correct filtered entrypoints', async () => {
+      mockArgv('build', '-e', 'popup', '-e', 'options');
+      await import('../cli');
+
+      expect(buildMock).toBeCalledWith({
+        filterEntrypoints: ['popup', 'options'],
+      });
+    });
+
+    it('should respect passing --mv2', async () => {
+      mockArgv('build', '--mv2');
+      await import('../cli');
+
+      expect(buildMock).toBeCalledWith({
+        manifestVersion: 2,
+      });
+    });
+
+    it('should respect passing --mv3', async () => {
+      mockArgv('build', '--mv3');
+      await import('../cli');
+
+      expect(buildMock).toBeCalledWith({
+        manifestVersion: 3,
+      });
+    });
+
+    it('should include analysis in the build', async () => {
+      mockArgv('build', '--analyze');
+      await import('../cli');
+
+      expect(buildMock).toBeCalledWith({
+        analysis: {
+          enabled: true,
+        },
+      });
+    });
+
+    it('should respect passing --debug', async () => {
+      mockArgv('build', '--debug');
+      await import('../cli');
+
+      expect(buildMock).toBeCalledWith({
+        debug: true,
+      });
+    });
+  });
+
+  describe('zip', () => {
+    it('should not pass any config when no flags are passed', async () => {
+      mockArgv('zip');
+      await import('../cli');
+
+      expect(zipMock).toBeCalledWith({});
+    });
+
+    it('should respect passing a custom root', async () => {
+      mockArgv('zip', 'path/to/root');
+      await import('../cli');
+
+      expect(zipMock).toBeCalledWith({
+        root: 'path/to/root',
+      });
+    });
+
+    it('should respect a custom config file', async () => {
+      mockArgv('zip', '-c', './path/to/config.ts');
+      await import('../cli');
+
+      expect(zipMock).toBeCalledWith({
+        configFile: './path/to/config.ts',
+      });
+    });
+
+    it('should respect passing a custom mode', async () => {
+      mockArgv('zip', '-m', 'development');
+      await import('../cli');
+
+      expect(zipMock).toBeCalledWith({
+        mode: 'development',
+      });
+    });
+
+    it('should respect passing a custom browser', async () => {
+      mockArgv('zip', '-b', 'firefox');
+      await import('../cli');
+
+      expect(zipMock).toBeCalledWith({
+        browser: 'firefox',
+      });
+    });
+
+    it('should respect passing --mv2', async () => {
+      mockArgv('zip', '--mv2');
+      await import('../cli');
+
+      expect(zipMock).toBeCalledWith({
+        manifestVersion: 2,
+      });
+    });
+
+    it('should respect passing --mv3', async () => {
+      mockArgv('zip', '--mv3');
+      await import('../cli');
+
+      expect(zipMock).toBeCalledWith({
+        manifestVersion: 3,
+      });
+    });
+
+    it('should respect passing --debug', async () => {
+      mockArgv('zip', '--debug');
+      await import('../cli');
+
+      expect(zipMock).toBeCalledWith({
+        debug: true,
+      });
+    });
+  });
+
+  describe('prepare', () => {
+    it('should not pass any config when no flags are passed', async () => {
+      mockArgv('prepare');
+      await import('../cli');
+
+      expect(prepareMock).toBeCalledWith({});
+    });
+
+    it('should respect passing a custom root', async () => {
+      mockArgv('prepare', 'path/to/root');
+      await import('../cli');
+
+      expect(prepareMock).toBeCalledWith({
+        root: 'path/to/root',
+      });
+    });
+
+    it('should respect a custom config file', async () => {
+      mockArgv('prepare', '-c', './path/to/config.ts');
+      await import('../cli');
+
+      expect(prepareMock).toBeCalledWith({
+        configFile: './path/to/config.ts',
+      });
+    });
+
+    it('should respect passing --debug', async () => {
+      mockArgv('prepare', '--debug');
+      await import('../cli');
+
+      expect(prepareMock).toBeCalledWith({
+        debug: true,
+      });
+    });
+  });
+
+  describe('clean', () => {
+    it('should not pass any config when no flags are passed', async () => {
+      mockArgv('clean');
+      await import('../cli');
+
+      expect(cleanMock).toBeCalledWith(undefined);
+    });
+
+    it('should respect passing a custom root', async () => {
+      mockArgv('clean', 'path/to/root');
+      await import('../cli');
+
+      expect(cleanMock).toBeCalledWith('path/to/root');
+    });
+  });
+
+  describe('init', () => {
+    it('should not pass any options when no flags are passed', async () => {
+      mockArgv('init');
+      await import('../cli');
+
+      expect(initializeMock).toBeCalledWith({});
+    });
+
+    it('should respect the provided folder', async () => {
+      mockArgv('init', 'path/to/folder');
+      await import('../cli');
+
+      expect(initializeMock).toBeCalledWith({
+        directory: 'path/to/folder',
+      });
+    });
+
+    it('should respect passing --template', async () => {
+      mockArgv('init', '-t', 'vue');
+      await import('../cli');
+
+      expect(initializeMock).toBeCalledWith({
+        template: 'vue',
+      });
+    });
+
+    it('should respect passing --pm', async () => {
+      mockArgv('init', '--pm', 'pnpm');
+      await import('../cli');
+
+      expect(initializeMock).toBeCalledWith({
+        packageManager: 'pnpm',
+      });
+    });
+  });
+});

src/cli.ts

@@ -4,6 +4,7 @@ import { build, clean, createServer, initialize, prepare, zip } from '~/core';
 import consola, { LogLevels } from 'consola';
 import { printHeader } from '~/core/utils/log';
 import { formatDuration } from '~/core/utils/time';
+import { ValidationError } from './core/utils/validation';
 
 // TODO: Remove. See https://github.com/wxt-dev/wxt/issues/277
 process.env.VITE_CJS_IGNORE_WARNING = 'true';
@@ -20,6 +21,13 @@ cli
   .option('-c, --config <file>', 'use specified config file')
   .option('-m, --mode <mode>', 'set env mode')
   .option('-b, --browser <browser>', 'specify a browser')
+  .option(
+    '-e, --filter-entrypoint <entrypoint>',
+    'only build specific entrypoints',
+    {
+      type: [],
+    },
+  )
   .option('--mv3', 'target manifest v3')
   .option('--mv2', 'target manifest v2')
   .action(
@@ -31,6 +39,7 @@ cli
         manifestVersion: flags.mv3 ? 3 : flags.mv2 ? 2 : undefined,
         configFile: flags.config,
         debug: flags.debug,
+        filterEntrypoints: getArrayFromFlags(flags, 'filterEntrypoint'),
       });
       await server.start();
       return { isOngoing: true };
@@ -43,6 +52,13 @@ cli
   .option('-c, --config <file>', 'use specified config file')
   .option('-m, --mode <mode>', 'set env mode')
   .option('-b, --browser <browser>', 'specify a browser')
+  .option(
+    '-e, --filter-entrypoint <entrypoint>',
+    'only build specific entrypoints',
+    {
+      type: [],
+    },
+  )
   .option('--mv3', 'target manifest v3')
   .option('--mv2', 'target manifest v2')
   .option('--analyze', 'visualize extension bundle')
@@ -55,9 +71,8 @@ cli
         manifestVersion: flags.mv3 ? 3 : flags.mv2 ? 2 : undefined,
         configFile: flags.config,
         debug: flags.debug,
-        analysis: {
-          enabled: flags.analyze,
-        },
+        analysis: flags.analyze ? { enabled: true } : undefined,
+        filterEntrypoints: getArrayFromFlags(flags, 'filterEntrypoint'),
       });
     }),
   );
@@ -125,7 +140,7 @@ cli
     ),
   );
 
-cli.parse();
+cli.parse(process.argv);
 
 /**
  * Wrap an action handler to add a timer, error handling, and maybe enable debug mode.
@@ -160,8 +175,22 @@ function wrapAction(
       consola.fail(
         `Command failed after ${formatDuration(Date.now() - startTime)}`,
       );
-      consola.error(err);
+      if (err instanceof ValidationError) {
+        // Don't log these errors, they've already been logged
+      } else {
+        consola.error(err);
+      }
       process.exit(1);
     }
   };
 }
+
+/**
+ * Array flags, when not passed, are either `undefined` or `[undefined]`. This function filters out
+ * the
+ */
+function getArrayFromFlags<T>(flags: any, name: string): T[] | undefined {
+  const array = [flags[name]].flat() as Array<T | undefined>;
+  const result = array.filter((item) => item != null) as T[];
+  return result.length ? result : undefined;
+}

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

@@ -1,214 +0,0 @@
-/** @vitest-environment happy-dom */
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { createContentScriptIframe } from '~/client/content-scripts/content-script-iframe';
-import { ContentScriptContext } from '~/client/content-scripts/content-script-context';
-
-const createCtx = () => new ContentScriptContext('test');
-
-const fetch = vi.fn();
-
-describe('createContentScriptIframe', () => {
-  beforeEach(() => {
-    document.body.innerHTML = `
-      <div id="parent">
-        <p id="one">one</p>
-        <p id="two">two</p>
-        <p id="three"></p>
-      </div>
-    `;
-
-    window.fetch = fetch;
-    fetch.mockResolvedValue({ text: () => Promise.resolve('') });
-  });
-
-  describe('mount', () => {
-    describe('append option', () => {
-      it.each([undefined, 'last' as const])(
-        'should append the element as the last child to the anchor when append=%s',
-        async (append) => {
-          const ui = await createContentScriptIframe(createCtx(), {
-            page: '/test.html',
-            type: 'inline',
-            anchor: '#parent',
-            append,
-          });
-          ui.mount();
-
-          expect(
-            document.querySelector('#parent > :nth-child(4)')?.tagName,
-          ).toEqual('DIV');
-        },
-      );
-
-      it('should append the element as the first child to the anchor when append=first', async () => {
-        const ui = await createContentScriptIframe(createCtx(), {
-          page: '/test.html',
-          type: 'inline',
-          anchor: '#parent',
-          append: 'first',
-        });
-        ui.mount();
-
-        expect(
-          document.querySelector('#parent > :nth-child(1)')?.tagName,
-        ).toEqual('DIV');
-      });
-
-      it('should append the element normally when append=first but there are no other children', async () => {
-        const ui = await createContentScriptIframe(createCtx(), {
-          page: '/test.html',
-          type: 'inline',
-          anchor: '#three',
-          append: 'first',
-        });
-        ui.mount();
-
-        expect(
-          document.querySelector('#three > :nth-child(1)')?.tagName,
-        ).toEqual('DIV');
-      });
-
-      it('should replace the anchor with the element when append=replace', async () => {
-        const ui = await createContentScriptIframe(createCtx(), {
-          page: '/test.html',
-          type: 'inline',
-          anchor: '#two',
-          append: 'replace',
-        });
-        ui.mount();
-
-        expect(
-          document.querySelector('#parent > :nth-child(2)')?.tagName,
-        ).toEqual('DIV');
-      });
-
-      it('should append the element after the anchor when append=before', async () => {
-        const ui = await createContentScriptIframe(createCtx(), {
-          page: '/test.html',
-          type: 'inline',
-          anchor: '#two',
-          append: 'before',
-        });
-        ui.mount();
-
-        expect(
-          document.querySelector('#parent > :nth-child(2)')?.tagName,
-        ).toEqual('DIV');
-      });
-
-      it('should append the element after the anchor when append=after', async () => {
-        const ui = await createContentScriptIframe(createCtx(), {
-          page: '/test.html',
-          type: 'inline',
-          anchor: '#two',
-          append: 'after',
-        });
-        ui.mount();
-
-        // Happy DOM doesn't work in this case, so we just make sure the element is added.
-        // expect(
-        //   document.querySelector('#parent > :nth-child(3)')?.tagName,
-        // ).toEqual('DIV');
-        expect(document.querySelector('DIV')).toBeDefined();
-      });
-
-      it('should apply a custom function', async () => {
-        const ui = await createContentScriptIframe(createCtx(), {
-          page: '/test.html',
-          type: 'inline',
-          anchor: '#three',
-          append: (anchor, ui) => anchor.replaceWith(ui),
-        });
-        ui.mount();
-
-        expect(
-          document.querySelector('#parent > :nth-child(3)')?.tagName,
-        ).toEqual('DIV');
-      });
-    });
-
-    it('should default the anchor to the body when unset', async () => {
-      const ui = await createContentScriptIframe(createCtx(), {
-        page: '/test.html',
-        type: 'inline',
-      });
-      ui.mount();
-
-      expect(document.querySelector('body > :nth-child(2)')?.tagName).toEqual(
-        'DIV',
-      );
-    });
-
-    it.each(['#four', () => document.querySelector('#four')])(
-      "should throw an error if the anchor doesn't exist",
-      async (anchor) => {
-        const ui = await createContentScriptIframe(createCtx(), {
-          page: '/test.html',
-          type: 'inline',
-          anchor,
-        });
-
-        expect(ui.mount).toThrow(
-          'Failed to mount content script UI: could not find anchor element',
-        );
-      },
-    );
-  });
-
-  describe('remove', () => {
-    it("should not fail if the ui hasn't been mounted", async () => {
-      const ui = await createContentScriptIframe(createCtx(), {
-        page: '/test.html',
-        type: 'inline',
-      });
-      ui.remove();
-    });
-
-    it('should automatically remove the UI when the context is invalidated', async () => {
-      const ctx = createCtx();
-      const ui = await createContentScriptIframe(ctx, {
-        page: '/test.html',
-        type: 'inline',
-      });
-      ui.mount();
-
-      expect(document.querySelector('.wxt-iframe-wrapper')).toBeDefined();
-
-      ctx.abort();
-      expect(document.querySelector('.wxt-iframe-wrapper')).toBeNull();
-    });
-  });
-
-  describe('type', () => {
-    it.each(['inline', 'overlay', 'modal'] as const)(
-      'should render type=%s',
-      async (type) => {
-        const ui = await createContentScriptIframe(createCtx(), {
-          page: '/test.html',
-          type,
-        });
-        ui.mount();
-
-        expect(document.querySelector('DIV')).toBeDefined();
-      },
-    );
-  });
-
-  describe('anchor', () => {
-    it.each([
-      () => '#two',
-      () => () => '#two',
-      () => document.querySelector('#two'),
-      () => () => document.querySelector('#two'),
-    ])('should render anchor=%s', async (getAnchor) => {
-      const ui = await createContentScriptIframe(createCtx(), {
-        page: '/test.html',
-        type: 'inline',
-        anchor: getAnchor(),
-      });
-      ui.mount();
-
-      expect(document.querySelector('DIV')).toBeDefined();
-    });
-  });
-});

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

@@ -1,358 +0,0 @@
-/** @vitest-environment happy-dom */
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { createContentScriptUi } from '~/client/content-scripts/content-script-ui';
-import { ContentScriptContext } from '~/client/content-scripts/content-script-context';
-import { createIsolatedElement } from '@webext-core/isolated-element';
-import { mock } from 'vitest-mock-extended';
-import { browser } from '~/browser';
-import { faker } from '@faker-js/faker';
-
-vi.mock('@webext-core/isolated-element', async () => {
-  const { vi } = await import('vitest');
-  return {
-    createIsolatedElement: vi.fn(),
-  };
-});
-const createIsolatedElementMock = vi.mocked(createIsolatedElement);
-
-const testApp = (container: Element) => {
-  const app = document.createElement('div');
-  app.textContent = 'App';
-  container.append(app);
-};
-
-const createCtx = () => new ContentScriptContext('test');
-
-const fetch = vi.fn();
-
-describe('createContentScriptUi', () => {
-  beforeEach(() => {
-    document.body.innerHTML = `
-      <div id="parent">
-        <p id="one">one</p>
-        <p id="two">two</p>
-        <p id="three"></p>
-      </div>
-    `;
-
-    window.fetch = fetch;
-    fetch.mockResolvedValue({ text: () => Promise.resolve('') });
-
-    createIsolatedElementMock.mockImplementation(async (config) => {
-      const parentElement = document.createElement(config.name);
-      const isolatedElement = document.createElement('html');
-      parentElement.append(isolatedElement);
-
-      return {
-        isolatedElement,
-        parentElement: parentElement,
-        shadow: mock<ShadowRoot>({
-          querySelector: (selector: string) => {
-            if (selector === 'html') return isolatedElement;
-          },
-        }),
-      };
-    });
-  });
-
-  describe('css', () => {
-    it('should load the CSS for the current entrypoint when cssInjectionMode=ui', async () => {
-      fetch.mockResolvedValue({ text: () => Promise.resolve('body {}') });
-      const ctx = new ContentScriptContext('test', {
-        matches: [],
-        cssInjectionMode: 'ui',
-      });
-
-      await createContentScriptUi(ctx, {
-        name: 'test',
-        type: 'inline',
-        mount: testApp,
-      });
-
-      expect(fetch).toBeCalledTimes(1);
-      expect(fetch).toBeCalledWith(
-        `chrome-extension://${browser.runtime.id}/content-scripts/${__ENTRYPOINT__}.css`,
-      );
-      expect(createIsolatedElementMock).toBeCalledTimes(1);
-      expect(createIsolatedElementMock).toBeCalledWith(
-        expect.objectContaining({
-          css: {
-            textContent: 'body {}',
-          },
-        }),
-      );
-    });
-
-    it('should still load the UI when fetch fails to load CSS file when cssInjectionMode=ui', async () => {
-      const error = Error('Test fetch error');
-      fetch.mockRejectedValue(error);
-      const ctx = new ContentScriptContext('test', {
-        matches: [],
-        cssInjectionMode: 'ui',
-      });
-
-      await createContentScriptUi(ctx, {
-        name: 'test',
-        type: 'inline',
-        mount: testApp,
-      });
-
-      expect(fetch).toBeCalledTimes(1);
-      expect(fetch).toBeCalledWith(
-        `chrome-extension://${browser.runtime.id}/content-scripts/${__ENTRYPOINT__}.css`,
-      );
-      expect(createIsolatedElementMock).toBeCalledTimes(1);
-      expect(createIsolatedElementMock).toBeCalledWith(
-        expect.objectContaining({
-          css: {
-            textContent: '',
-          },
-        }),
-      );
-    });
-
-    it.each(['manifest', 'manual'] as const)(
-      'should not fetch CSS when cssInjectionMode=%s',
-      async (cssInjectionMode) => {
-        const ctx = new ContentScriptContext('test', {
-          matches: [],
-          cssInjectionMode,
-        });
-
-        await createContentScriptUi(ctx, {
-          name: 'test',
-          type: 'inline',
-          mount: testApp,
-        });
-
-        expect(fetch).not.toBeCalled();
-      },
-    );
-  });
-
-  describe('mount', () => {
-    describe('append option', () => {
-      it.each([undefined, 'last' as const])(
-        'should append the element as the last child to the anchor when append=%s',
-        async (append) => {
-          const ui = await createContentScriptUi(createCtx(), {
-            name: 'test-app',
-            type: 'inline',
-            anchor: '#parent',
-            append,
-            mount: testApp,
-          });
-          ui.mount();
-
-          expect(
-            document.querySelector('#parent > :nth-child(4)')?.tagName,
-          ).toEqual('TEST-APP');
-        },
-      );
-
-      it('should append the element as the first child to the anchor when append=first', async () => {
-        const ui = await createContentScriptUi(createCtx(), {
-          name: 'test-app',
-          type: 'inline',
-          anchor: '#parent',
-          append: 'first',
-          mount: testApp,
-        });
-        ui.mount();
-
-        expect(
-          document.querySelector('#parent > :nth-child(1)')?.tagName,
-        ).toEqual('TEST-APP');
-      });
-
-      it('should append the element normally when append=first but there are no other children', async () => {
-        const ui = await createContentScriptUi(createCtx(), {
-          name: 'test-app',
-          type: 'inline',
-          anchor: '#three',
-          append: 'first',
-          mount: testApp,
-        });
-        ui.mount();
-
-        expect(
-          document.querySelector('#three > :nth-child(1)')?.tagName,
-        ).toEqual('TEST-APP');
-      });
-
-      it('should replace the anchor with the element when append=replace', async () => {
-        const ui = await createContentScriptUi(createCtx(), {
-          name: 'test-app',
-          type: 'inline',
-          anchor: '#two',
-          append: 'replace',
-          mount: testApp,
-        });
-        ui.mount();
-
-        expect(
-          document.querySelector('#parent > :nth-child(2)')?.tagName,
-        ).toEqual('TEST-APP');
-      });
-
-      it('should append the element after the anchor when append=before', async () => {
-        const ui = await createContentScriptUi(createCtx(), {
-          name: 'test-app',
-          type: 'inline',
-          anchor: '#two',
-          append: 'before',
-          mount: testApp,
-        });
-        ui.mount();
-
-        expect(
-          document.querySelector('#parent > :nth-child(2)')?.tagName,
-        ).toEqual('TEST-APP');
-      });
-
-      it('should append the element after the anchor when append=after', async () => {
-        const ui = await createContentScriptUi(createCtx(), {
-          name: 'test-app',
-          type: 'inline',
-          anchor: '#two',
-          append: 'after',
-          mount: testApp,
-        });
-        ui.mount();
-
-        // Happy DOM doesn't work in this case, so we just make sure the element is added.
-        // expect(
-        //   document.querySelector('#parent > :nth-child(3)')?.tagName,
-        // ).toEqual('TEST-APP');
-        expect(document.querySelector('test-app')).toBeDefined();
-      });
-
-      it('should apply a custom function', async () => {
-        const ui = await createContentScriptUi(createCtx(), {
-          name: 'test-app',
-          type: 'inline',
-          anchor: '#three',
-          append: (anchor, ui) => anchor.replaceWith(ui),
-          mount: testApp,
-        });
-        ui.mount();
-
-        expect(
-          document.querySelector('#parent > :nth-child(3)')?.tagName,
-        ).toEqual('TEST-APP');
-      });
-    });
-
-    it('should default the anchor to the body when unset', async () => {
-      const ui = await createContentScriptUi(createCtx(), {
-        name: 'test-app',
-        type: 'inline',
-        mount: testApp,
-      });
-      ui.mount();
-
-      expect(document.querySelector('body > :nth-child(2)')?.tagName).toEqual(
-        'TEST-APP',
-      );
-    });
-
-    it.each(['#four', () => document.querySelector('#four')])(
-      "should throw an error if the anchor doesn't exist",
-      async (anchor) => {
-        const ui = await createContentScriptUi(createCtx(), {
-          name: 'test',
-          type: 'inline',
-          anchor,
-          mount: testApp,
-        });
-
-        expect(ui.mount).toThrow(
-          'Failed to mount content script UI: could not find anchor element',
-        );
-      },
-    );
-  });
-
-  describe('remove', () => {
-    it("should not fail if the ui hasn't been mounted", async () => {
-      const ui = await createContentScriptUi(createCtx(), {
-        name: 'test-app',
-        type: 'inline',
-        mount: testApp,
-      });
-      ui.remove();
-    });
-
-    it('should automatically remove the UI when the context is invalidated', async () => {
-      const ctx = createCtx();
-      const ui = await createContentScriptUi(ctx, {
-        name: 'test-app',
-        type: 'inline',
-        mount: testApp,
-      });
-      ui.mount();
-
-      expect(document.querySelector('test-app')).toBeDefined();
-
-      ctx.abort();
-      expect(document.querySelector('test-app')).toBeNull();
-    });
-  });
-
-  describe('type', () => {
-    it.each(['inline', 'overlay', 'modal'] as const)(
-      'should render type=%s',
-      async (type) => {
-        const ui = await createContentScriptUi(createCtx(), {
-          name: 'test-app',
-          type,
-          mount: testApp,
-        });
-        ui.mount();
-
-        expect(document.querySelector('test-app')).toBeDefined();
-      },
-    );
-  });
-
-  describe('anchor', () => {
-    it.each([
-      () => '#two',
-      () => () => '#two',
-      () => document.querySelector('#two'),
-      () => () => document.querySelector('#two'),
-    ])('should render anchor=%s', async (getAnchor) => {
-      const ui = await createContentScriptUi(createCtx(), {
-        name: 'test-app',
-        type: 'inline',
-        anchor: getAnchor(),
-        mount: testApp,
-      });
-      ui.mount();
-
-      expect(document.querySelector('test-app')).toBeDefined();
-    });
-  });
-
-  it('should forward isolateEvents into createIsolatedElement', async () => {
-    const isolateEvents = faker.helpers.arrayElement([
-      undefined,
-      true,
-      false,
-      ['click', 'keydown'],
-    ]);
-    await createContentScriptUi(createCtx(), {
-      name: 'test-app',
-      type: 'inline',
-      mount: testApp,
-      isolateEvents,
-    });
-
-    expect(createIsolatedElementMock).toBeCalledTimes(1);
-    expect(createIsolatedElementMock).toBeCalledWith(
-      expect.objectContaining({
-        isolateEvents,
-      }),
-    );
-  });
-});

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

@@ -1,83 +0,0 @@
-import { browser } from '~/browser';
-import {
-  ContentScriptAnchoredOptions,
-  ContentScriptPositioningOptions,
-  applyContentScriptUiPosition,
-  mountContentScriptUiRoot,
-} from '../utils/content-script-ui';
-import { ContentScriptContext } from './content-script-context';
-
-/**
- * Utility for mounting a content script UI inside an iframe. Automatically removed from the DOM
- * when the content script's context is invalidated.
- *
- * See https://wxt.dev/entrypoints/content-scripts.html#iframe for full documentation.
- *
- * @example
- * export default defineContentScript({
- *   matches: ["*://*.google.com/*"],
- *
- *   main(ctx) {
- *     const ui = await createContentScriptIframe(ctx, {
- *       page: "/content-script-overlay.html",
- *       type: "modal",
- *     })
- *     ui.mount();
- *   }
- * })
- */
-export function createContentScriptIframe(
-  ctx: ContentScriptContext,
-  options: ContentScriptIframeOptions,
-): ContentScriptIframe {
-  const wrapper = document.createElement('div');
-  wrapper.classList.add('wxt-iframe-wrapper');
-  const iframe = document.createElement('iframe');
-  iframe.src = browser.runtime.getURL(options.page);
-  wrapper.appendChild(iframe);
-
-  const mount = () => {
-    applyContentScriptUiPosition(wrapper, iframe, options);
-    mountContentScriptUiRoot(wrapper, options);
-  };
-
-  const remove = () => {
-    wrapper.remove();
-  };
-
-  ctx.onInvalidated(remove);
-
-  return {
-    iframe,
-    wrapper,
-    mount,
-    remove,
-  };
-}
-
-export interface ContentScriptIframe {
-  /**
-   * The iframe added to the DOM.
-   */
-  iframe: HTMLIFrameElement;
-  /**
-   * A wrapper div that assists in positioning.
-   */
-  wrapper: HTMLDivElement;
-  /**
-   * Function that mounts or remounts the UI on the page.
-   */
-  mount: () => void;
-  /**
-   * Function that removes the UI from the webpage.
-   */
-  remove: () => void;
-}
-
-export type ContentScriptIframeOptions = ContentScriptPositioningOptions &
-  ContentScriptAnchoredOptions & {
-    /**
-     * The path to the unlisted HTML file to display in the iframe.
-     */
-    page: import('wxt/browser').PublicPath;
-  };

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

@@ -1,183 +0,0 @@
-import { createIsolatedElement } from '@webext-core/isolated-element';
-import { browser } from '~/browser';
-import { logger } from '~/sandbox/utils/logger';
-import { ContentScriptContext } from './content-script-context';
-import {
-  ContentScriptAnchoredOptions,
-  ContentScriptPositioningOptions,
-  applyContentScriptUiPosition,
-  mountContentScriptUiRoot,
-} from '../utils/content-script-ui';
-
-/**
- * Utility for mounting content script UI's with isolated styles and controlled event bubbling.
- * Automatically removed from the DOM when the content script's context is invalidated.
- *
- * See https://wxt.dev/guide/content-script-ui.html for full documentation.
- *
- * @example
- * // entrypoints/example-ui.content/index.ts
- * import "./style.css"
- *
- * export default defineContentScript({
- *   matches: ["*://*.google.com/*"],
- *   cssInjectionMode: "ui",
- *
- *   async main(ctx) {
- *     const ui = await createContentScriptUi(ctx, {
- *       name: "example-overlay",
- *       type: "modal",
- *       mount(container) {
- *         const app = document.createElement("div");
- *         app.textContent = "Content Script UI";
- *         container.append(app);
- *       },
- *     })
- *     ui.mount();
- *   }
- * })
- */
-export async function createContentScriptUi<TApp>(
-  ctx: ContentScriptContext,
-  options: ContentScriptUiOptions<TApp>,
-): Promise<ContentScriptUi<TApp>> {
-  const css = [options.css ?? ''];
-  if (ctx.options?.cssInjectionMode === 'ui') {
-    css.push(await loadCss());
-  }
-
-  const {
-    isolatedElement: uiContainer,
-    parentElement: shadowHost,
-    shadow,
-  } = await createIsolatedElement({
-    name: options.name,
-    css: {
-      textContent: css.join('\n').trim(),
-    },
-    mode: 'open',
-    isolateEvents: options.isolateEvents,
-  });
-
-  let mounted: TApp;
-
-  const mount = () => {
-    // Mount UI inside shadow root
-    mounted = options.mount(uiContainer);
-
-    // Add shadow root element to DOM
-    mountContentScriptUiRoot(shadowHost, options);
-    applyContentScriptUiPosition(
-      shadowHost,
-      shadow.querySelector('html'),
-      options,
-    );
-  };
-
-  const remove = () => {
-    // Detatch shadow root from DOM
-    shadowHost.remove();
-    // Cleanup mounted state
-    options.onRemove?.(mounted);
-    // Remove children from uiContainer
-    while (uiContainer.lastChild)
-      uiContainer.removeChild(uiContainer.lastChild);
-  };
-
-  ctx.onInvalidated(remove);
-
-  return {
-    shadow,
-    shadowHost,
-    uiContainer,
-    mount,
-    remove,
-    mounted: mounted!,
-  };
-}
-
-/**
- * Load the CSS for the current entrypoint.
- */
-async function loadCss(): Promise<string> {
-  const url = browser.runtime.getURL(`/content-scripts/${__ENTRYPOINT__}.css`);
-  try {
-    const res = await fetch(url);
-    const css = await res.text();
-
-    // Replace :root selectors with :host since we're in a shadow root
-    return css.replaceAll(':root', ':host');
-  } catch (err) {
-    logger.warn(
-      `Failed to load styles @ ${url}. Did you forget to import the stylesheet in your entrypoint?`,
-      err,
-    );
-    return '';
-  }
-}
-
-export interface ContentScriptUi<TApp> {
-  /**
-   * The `HTMLElement` hosting the shadow root used to isolate the UI's styles. This is the element
-   * that get's added to the DOM. This element's style is not isolated from the webpage.
-   */
-  shadowHost: HTMLElement;
-  /**
-   * The container element inside the `ShadowRoot` whose styles are isolated. The UI is mounted
-   * inside this `HTMLElement`.
-   */
-  uiContainer: HTMLElement;
-  /**
-   * The shadow root performing the isolation.
-   */
-  shadow: ShadowRoot;
-  /**
-   * Custom data returned from the `options.mount` function.
-   */
-  mounted: TApp;
-  /**
-   * Function that mounts or remounts the UI on the page.
-   */
-  mount: () => void;
-  /**
-   * Function that removes the UI from the webpage.
-   */
-  remove: () => void;
-}
-
-export type ContentScriptUiOptions<TApp> = ContentScriptPositioningOptions &
-  ContentScriptAnchoredOptions & {
-    /**
-     * The name of the custom component used to host the ShadowRoot. Must be kebab-case.
-     */
-    name: string;
-    /**
-     * Callback executed when mounting the UI. This function should create and append the UI to the
-     * `container` element. It is called every time `ui.mount()` is called
-     *
-     * Optionally return a value that can be accessed at `ui.mounted` or in the `onRemove` callback.
-     */
-    mount: (container: Element) => TApp;
-    /**
-     * Callback called when the UI is removed from the webpage. Use to cleanup your UI, like
-     * unmounting your vue or react apps.
-     */
-    onRemove?: (mounted: TApp) => void;
-    /**
-     * Custom CSS text to apply to the UI. If your content script imports/generates CSS and you've
-     * set `cssInjectionMode: "ui"`, the imported CSS will be included automatically. You do not need
-     * to pass those styles in here. This is for any additional styles not in the imported CSS.
-     *
-     * See https://wxt.dev/guide/content-script-ui.html for more info.
-     */
-    css?: string;
-    /**
-     * When enabled, `event.stopPropagation` will be called on events trying to bubble out of the
-     * shadow root.
-     *
-     * - Set to `true` to stop the propagation of a default set of events,
-     *   `["keyup", "keydown", "keypress"]`
-     * - Set to an array of event names to stop the propagation of a custom list of events
-     */
-    isolateEvents?: boolean | string[];
-  };

src/client/content-scripts/index.ts

@@ -1,3 +1,2 @@
 export * from './content-script-context';
-export * from './content-script-ui';
-export * from './content-script-iframe';
+export * from './ui';

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

@@ -0,0 +1,407 @@
+/** @vitest-environment happy-dom */
+import { describe, it, beforeEach, vi, expect } from 'vitest';
+import { createIntegratedUi, createIframeUi, createShadowRootUi } from '..';
+import { ContentScriptContext } from '../../content-script-context';
+
+function appendTestApp(container: HTMLElement) {
+  container.innerHTML = '<app>Hello world</app>';
+}
+
+const fetch = vi.fn();
+
+describe('Content Script UIs', () => {
+  let ctx: ContentScriptContext;
+
+  beforeEach(() => {
+    document.body.innerHTML = `
+      <div id="parent">
+        <p id="one">one</p>
+        <p id="two">two</p>
+        <p id="three"></p>
+      </div>
+    `;
+    window.fetch = fetch;
+    fetch.mockResolvedValue({ text: () => Promise.resolve('') });
+    ctx = new ContentScriptContext('test');
+  });
+
+  describe('type', () => {
+    describe('integrated', () => {
+      it('should add a wrapper and custom UI to the page', () => {
+        const ui = createIntegratedUi(ctx, {
+          position: 'inline',
+          onMount: appendTestApp,
+        });
+        ui.mount();
+
+        expect(
+          document.querySelector('div[data-wxt-integrated]'),
+        ).not.toBeNull();
+        expect(document.querySelector('app')).not.toBeNull();
+      });
+
+      it('should allow customizing the wrapper tag', () => {
+        const ui = createIntegratedUi(ctx, {
+          position: 'inline',
+          tag: 'pre',
+          onMount: appendTestApp,
+        });
+        ui.mount();
+
+        expect(
+          document.querySelector('pre[data-wxt-integrated]'),
+        ).not.toBeNull();
+        expect(document.querySelector('app')).not.toBeNull();
+      });
+    });
+
+    describe('iframe', () => {
+      it('should add a wrapper and iframe to the page', () => {
+        const ui = createIframeUi(ctx, {
+          page: '/page.html',
+          position: 'inline',
+        });
+        ui.mount();
+
+        expect(document.querySelector('div[data-wxt-iframe]')).toBeDefined();
+        expect(document.querySelector('iframe')).toBeDefined();
+      });
+    });
+
+    describe('shadow-root', () => {
+      it('should load a shadow root to the page', async () => {
+        const ui = await createShadowRootUi(ctx, {
+          position: 'inline',
+          name: 'test',
+          onMount(uiContainer) {
+            appendTestApp(uiContainer);
+          },
+        });
+        ui.mount();
+
+        expect(
+          document.querySelector('test[data-wxt-shadow-root]'),
+        ).not.toBeNull();
+        expect(ui.shadow.querySelector('app')).not.toBeNull();
+      });
+
+      it.each([
+        ['open', 'open'],
+        [undefined, 'open'],
+        ['closed', 'closed'],
+      ] as const)(
+        'should respect the shadow root mode (%s -> %s)',
+        async (input, expected) => {
+          const ui = await createShadowRootUi(ctx, {
+            position: 'inline',
+            name: 'test',
+            mode: input,
+            onMount: appendTestApp,
+          });
+
+          expect(ui.shadow.mode).toBe(expected);
+        },
+      );
+    });
+  });
+
+  describe('position', () => {
+    describe('inline', () => {
+      it('should wrap the UI in a simple div', () => {
+        const ui = createIframeUi(ctx, {
+          position: 'inline',
+          page: '/page.html',
+        });
+
+        expect(ui.wrapper.outerHTML).toMatchInlineSnapshot(
+          `"<div data-wxt-iframe=""><iframe src="chrome-extension://test-extension-id/page.html"></iframe></div>"`,
+        );
+      });
+    });
+
+    describe('overlay', () => {
+      it('should wrap the UI in a positioned div when alignment=undefined', () => {
+        const ui = createIframeUi(ctx, {
+          position: 'overlay',
+          page: '/page.html',
+        });
+        ui.mount();
+
+        expect(ui.wrapper.outerHTML).toMatchInlineSnapshot(
+          `"<div data-wxt-iframe="" style="overflow: visible; position: relative; width: 0px; height: 0px; display: block;"><iframe src="chrome-extension://test-extension-id/page.html" style="position: absolute; top: 0px; left: 0px;"></iframe></div>"`,
+        );
+      });
+
+      it('should wrap the UI in a positioned div when alignment=top-left', () => {
+        const ui = createIframeUi(ctx, {
+          position: 'overlay',
+          page: '/page.html',
+          alignment: 'top-left',
+        });
+        ui.mount();
+
+        expect(ui.wrapper.outerHTML).toMatchInlineSnapshot(
+          `"<div data-wxt-iframe="" style="overflow: visible; position: relative; width: 0px; height: 0px; display: block;"><iframe src="chrome-extension://test-extension-id/page.html" style="position: absolute; top: 0px; left: 0px;"></iframe></div>"`,
+        );
+      });
+
+      it('should wrap the UI in a positioned div when alignment=top-right', () => {
+        const ui = createIframeUi(ctx, {
+          position: 'overlay',
+          page: '/page.html',
+          alignment: 'top-right',
+        });
+        ui.mount();
+
+        expect(ui.wrapper.outerHTML).toMatchInlineSnapshot(
+          `"<div data-wxt-iframe="" style="overflow: visible; position: relative; width: 0px; height: 0px; display: block;"><iframe src="chrome-extension://test-extension-id/page.html" style="position: absolute; top: 0px; right: 0px;"></iframe></div>"`,
+        );
+      });
+
+      it('should wrap the UI in a positioned div when alignment=bottom-right', () => {
+        const ui = createIframeUi(ctx, {
+          position: 'overlay',
+          page: '/page.html',
+          alignment: 'bottom-right',
+        });
+        ui.mount();
+
+        expect(ui.wrapper.outerHTML).toMatchInlineSnapshot(
+          `"<div data-wxt-iframe="" style="overflow: visible; position: relative; width: 0px; height: 0px; display: block;"><iframe src="chrome-extension://test-extension-id/page.html" style="position: absolute; bottom: 0px; right: 0px;"></iframe></div>"`,
+        );
+      });
+
+      it('should wrap the UI in a positioned div when alignment=bottom-left', () => {
+        const ui = createIframeUi(ctx, {
+          position: 'overlay',
+          page: '/page.html',
+          alignment: 'bottom-left',
+        });
+        ui.mount();
+
+        expect(ui.wrapper.outerHTML).toMatchInlineSnapshot(
+          `"<div data-wxt-iframe="" style="overflow: visible; position: relative; width: 0px; height: 0px; display: block;"><iframe src="chrome-extension://test-extension-id/page.html" style="position: absolute; bottom: 0px; left: 0px;"></iframe></div>"`,
+        );
+      });
+
+      it('should respect the provided zIndex', () => {
+        const zIndex = 123;
+        const ui = createIframeUi(ctx, {
+          position: 'overlay',
+          page: '/page.html',
+          zIndex,
+        });
+        ui.mount();
+
+        expect(ui.wrapper.style.zIndex).toBe(String(zIndex));
+      });
+    });
+
+    describe('modal', () => {
+      it('should wrap the UI in a div with a fixed position', () => {
+        const ui = createIframeUi(ctx, {
+          position: 'modal',
+          page: '/page.html',
+        });
+        ui.mount();
+
+        expect(ui.wrapper.outerHTML).toMatchInlineSnapshot(
+          `"<div data-wxt-iframe="" style="overflow: visible; position: relative; width: 0px; height: 0px; display: block;"><iframe src="chrome-extension://test-extension-id/page.html" style="position: fixed; top: 0px; bottom: 0px; left: 0px; right: 0px;"></iframe></div>"`,
+        );
+      });
+
+      it('should respect the provided zIndex', () => {
+        const zIndex = 123;
+        const ui = createIframeUi(ctx, {
+          position: 'modal',
+          page: '/page.html',
+          zIndex,
+        });
+        ui.mount();
+
+        expect(ui.wrapper.style.zIndex).toBe(String(zIndex));
+      });
+    });
+  });
+
+  describe('anchor', () => {
+    describe('undefined', () => {
+      it('should append the element to the body', () => {
+        const ui = createIntegratedUi(ctx, {
+          position: 'inline',
+          onMount: appendTestApp,
+        });
+        ui.mount();
+
+        expect(
+          document.querySelector('body > div[data-wxt-integrated]'),
+        ).not.toBeNull();
+      });
+    });
+
+    describe('string', () => {
+      it('should append the element using the specified query selector', () => {
+        const ui = createIntegratedUi(ctx, {
+          position: 'inline',
+          onMount: appendTestApp,
+          anchor: '#parent',
+        });
+        ui.mount();
+
+        expect(
+          document.querySelector('#parent > div[data-wxt-integrated]'),
+        ).not.toBeNull();
+      });
+    });
+
+    describe('Element', () => {
+      it('should append the element using the specified element', () => {
+        const ui = createIntegratedUi(ctx, {
+          position: 'inline',
+          onMount: appendTestApp,
+          anchor: document.getElementById('parent'),
+        });
+        ui.mount();
+
+        expect(
+          document.querySelector('#parent > div[data-wxt-integrated]'),
+        ).not.toBeNull();
+      });
+    });
+
+    describe('function', () => {
+      it('should append the element using the specified function', () => {
+        const ui = createIntegratedUi(ctx, {
+          position: 'inline',
+          onMount: appendTestApp,
+          anchor: () => document.getElementById('parent'),
+        });
+        ui.mount();
+
+        expect(
+          document.querySelector('#parent > div[data-wxt-integrated]'),
+        ).not.toBeNull();
+      });
+    });
+
+    it('should throw an error when the anchor does not exist', () => {
+      const ui = createIntegratedUi(ctx, {
+        position: 'inline',
+        onMount: appendTestApp,
+        anchor: () => document.getElementById('i-do-not-exist'),
+      });
+
+      expect(ui.mount).toThrow();
+    });
+  });
+
+  describe('append', () => {
+    describe.each([undefined, 'last'] as const)('%s', (append) => {
+      it('should append the element as the last child of the anchor', () => {
+        const ui = createIntegratedUi(ctx, {
+          position: 'inline',
+          anchor: '#parent',
+          append,
+          onMount: appendTestApp,
+        });
+        ui.mount();
+
+        expect(
+          document.querySelector(
+            '#parent > div[data-wxt-integrated]:last-child',
+          ),
+        ).not.toBeNull();
+      });
+    });
+
+    describe('first', () => {
+      it('should append the element as the last child of the anchor', () => {
+        const ui = createIntegratedUi(ctx, {
+          position: 'inline',
+          anchor: '#parent',
+          append: 'first',
+          onMount: appendTestApp,
+        });
+        ui.mount();
+
+        expect(
+          document.querySelector(
+            '#parent > div[data-wxt-integrated]:first-child',
+          ),
+        ).not.toBeNull();
+      });
+    });
+
+    describe('replace', () => {
+      it('should replace the the anchor', () => {
+        const ui = createIntegratedUi(ctx, {
+          position: 'inline',
+          anchor: '#parent',
+          append: 'replace',
+          onMount: appendTestApp,
+        });
+        ui.mount();
+
+        expect(
+          document.querySelector('body > div[data-wxt-integrated]'),
+        ).not.toBeNull();
+        expect(document.querySelector('#parent')).toBeNull();
+      });
+    });
+
+    describe('before', () => {
+      it('should append the UI before the anchor', () => {
+        const ui = createIntegratedUi(ctx, {
+          position: 'inline',
+          anchor: '#one',
+          append: 'before',
+          onMount: appendTestApp,
+        });
+        ui.mount();
+
+        expect(
+          document.querySelector(
+            '#parent > div[data-wxt-integrated]:first-child',
+          ),
+        ).not.toBeNull();
+      });
+    });
+
+    describe.todo('after', () => {
+      it('should append the UI after the anchor', () => {
+        const ui = createIntegratedUi(ctx, {
+          position: 'inline',
+          anchor: '#three',
+          append: 'after',
+          onMount: appendTestApp,
+        });
+        ui.mount();
+
+        expect(
+          document.querySelector(
+            '#parent > div[data-wxt-integrated]:last-child',
+          ),
+        ).not.toBeNull();
+      });
+    });
+
+    describe('function', () => {
+      it('should append the UI using a function', () => {
+        const ui = createIntegratedUi(ctx, {
+          position: 'inline',
+          anchor: '#parent',
+          append: (anchor, ui) => {
+            anchor.replaceWith(ui);
+          },
+          onMount: appendTestApp,
+        });
+        ui.mount();
+
+        expect(
+          document.querySelector('body > div[data-wxt-integrated]'),
+        ).not.toBeNull();
+        expect(document.querySelector('#parent')).toBeNull();
+      });
+    });
+  });
+});

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

@@ -0,0 +1,250 @@
+import { browser } from '~/browser';
+import { ContentScriptContext } from '..';
+import {
+  ContentScriptAnchoredOptions,
+  ContentScriptPositioningOptions,
+  IframeContentScriptUi,
+  IframeContentScriptUiOptions,
+  IntegratedContentScriptUi,
+  IntegratedContentScriptUiOptions,
+  ShadowRootContentScriptUi,
+  ShadowRootContentScriptUiOptions,
+} from './types';
+import { logger } from '~/sandbox/utils/logger';
+import { createIsolatedElement } from '@webext-core/isolated-element';
+export * from './types';
+
+/**
+ * Create a content script UI without any isolation.
+ *
+ * @see https://wxt.dev/guide/content-script-ui.html#integrated
+ */
+export function createIntegratedUi<TMounted>(
+  ctx: ContentScriptContext,
+  options: IntegratedContentScriptUiOptions<TMounted>,
+): IntegratedContentScriptUi<TMounted> {
+  const wrapper = document.createElement(options.tag || 'div');
+  wrapper.setAttribute('data-wxt-integrated', '');
+
+  let mounted: TMounted | undefined = undefined;
+  const mount = () => {
+    applyPosition(wrapper, undefined, options);
+    mountUi(wrapper, options);
+    mounted = options.onMount?.(wrapper);
+  };
+  const remove = () => {
+    options.onRemove?.(mounted);
+    wrapper.remove();
+  };
+
+  ctx.onInvalidated(remove);
+
+  return {
+    mounted,
+    wrapper,
+    mount,
+    remove,
+  };
+}
+
+/**
+ * Create a content script UI using an iframe.
+ *
+ * @see https://wxt.dev/guide/content-script-ui.html#iframe
+ */
+export function createIframeUi<TMounted>(
+  ctx: ContentScriptContext,
+  options: IframeContentScriptUiOptions<TMounted>,
+): IframeContentScriptUi<TMounted> {
+  const wrapper = document.createElement('div');
+  wrapper.setAttribute('data-wxt-iframe', '');
+  const iframe = document.createElement('iframe');
+  iframe.src = browser.runtime.getURL(options.page);
+  wrapper.appendChild(iframe);
+
+  let mounted: TMounted | undefined = undefined;
+  const mount = () => {
+    applyPosition(wrapper, iframe, options);
+    mountUi(wrapper, options);
+    mounted = options.onMount?.(wrapper, iframe);
+  };
+  const remove = () => {
+    options.onRemove?.(mounted);
+    wrapper.remove();
+  };
+
+  ctx.onInvalidated(remove);
+
+  return {
+    mounted,
+    iframe,
+    wrapper,
+    mount,
+    remove,
+  };
+}
+
+/**
+ * Create a content script UI inside a [`ShadowRoot`](https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot).
+ *
+ * > This function is async because it has to load the CSS via a network call.
+ *
+ * @see https://wxt.dev/guide/content-script-ui.html#shadowroot
+ */
+export async function createShadowRootUi<TMounted>(
+  ctx: ContentScriptContext,
+  options: ShadowRootContentScriptUiOptions<TMounted>,
+): Promise<ShadowRootContentScriptUi<TMounted>> {
+  const css = [options.css ?? ''];
+  if (ctx.options?.cssInjectionMode === 'ui') {
+    const entryCss = await loadCss();
+    // Replace :root selectors with :host since we're in a shadow root
+    css.push(entryCss.replaceAll(':root', ':host'));
+  }
+
+  const {
+    isolatedElement: uiContainer,
+    parentElement: shadowHost,
+    shadow,
+  } = await createIsolatedElement({
+    name: options.name,
+    css: {
+      textContent: css.join('\n').trim(),
+    },
+    mode: options.mode ?? 'open',
+    isolateEvents: options.isolateEvents,
+  });
+  shadowHost.setAttribute('data-wxt-shadow-root', '');
+
+  let mounted: TMounted;
+
+  const mount = () => {
+    // Mount UI inside shadow root
+    mounted = options.onMount(uiContainer, shadow, shadowHost);
+
+    // Add shadow root element to DOM
+    mountUi(shadowHost, options);
+    applyPosition(shadowHost, shadow.querySelector('html'), options);
+  };
+
+  const remove = () => {
+    // Detatch shadow root from DOM
+    shadowHost.remove();
+    // Cleanup mounted state
+    options.onRemove?.(mounted);
+    // Remove children from uiContainer
+    while (uiContainer.lastChild)
+      uiContainer.removeChild(uiContainer.lastChild);
+  };
+
+  ctx.onInvalidated(remove);
+
+  return {
+    shadow,
+    shadowHost,
+    uiContainer,
+    mount,
+    remove,
+    mounted: mounted!,
+  };
+}
+
+function applyPosition(
+  root: HTMLElement,
+  positionedElement: HTMLElement | undefined | null,
+  options: ContentScriptPositioningOptions,
+): void {
+  // No positioning for inline UIs
+  if (options.position === 'inline') return;
+
+  if (options.zIndex != null) root.style.zIndex = String(options.zIndex);
+
+  root.style.overflow = 'visible';
+  root.style.position = 'relative';
+  root.style.width = '0';
+  root.style.height = '0';
+  root.style.display = 'block';
+
+  if (positionedElement) {
+    if (options.position === 'overlay') {
+      positionedElement.style.position = 'absolute';
+      if (options.alignment?.startsWith('bottom-'))
+        positionedElement.style.bottom = '0';
+      else positionedElement.style.top = '0';
+
+      if (options.alignment?.endsWith('-right'))
+        positionedElement.style.right = '0';
+      else positionedElement.style.left = '0';
+    } else {
+      positionedElement.style.position = 'fixed';
+      positionedElement.style.top = '0';
+      positionedElement.style.bottom = '0';
+      positionedElement.style.left = '0';
+      positionedElement.style.right = '0';
+    }
+  }
+}
+
+function getAnchor(options: ContentScriptAnchoredOptions): Element | undefined {
+  if (options.anchor == null) return document.body;
+
+  let resolved =
+    typeof options.anchor === 'function' ? options.anchor() : options.anchor;
+  if (typeof resolved === 'string')
+    return document.querySelector<Element>(resolved) ?? undefined;
+  return resolved ?? undefined;
+}
+
+function mountUi(
+  root: HTMLElement,
+  options: ContentScriptAnchoredOptions,
+): void {
+  const anchor = getAnchor(options);
+  if (anchor == null)
+    throw Error(
+      'Failed to mount content script UI: could not find anchor element',
+    );
+
+  switch (options.append) {
+    case undefined:
+    case 'last':
+      anchor.append(root);
+      break;
+    case 'first':
+      if (anchor.firstChild) {
+        anchor.insertBefore(root, anchor.firstChild);
+      } else {
+        anchor.append(root);
+      }
+      break;
+    case 'replace':
+      anchor.replaceWith(root);
+      break;
+    case 'after':
+      anchor.replaceWith(anchor, root);
+      break;
+    case 'before':
+      anchor.replaceWith(root, anchor);
+      break;
+    default:
+      options.append(anchor, root);
+      break;
+  }
+}
+
+/**
+ * Load the CSS for the current entrypoint.
+ */
+async function loadCss(): Promise<string> {
+  const url = browser.runtime.getURL(`/content-scripts/${__ENTRYPOINT__}.css`);
+  try {
+    const res = await fetch(url);
+    return await res.text();
+  } catch (err) {
+    logger.warn(
+      `Failed to load styles @ ${url}. Did you forget to import the stylesheet in your entrypoint?`,
+      err,
+    );
+    return '';
+  }
+}

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

@@ -0,0 +1,217 @@
+export interface IntegratedContentScriptUi<TMounted>
+  extends ContentScriptUi<TMounted> {
+  /**
+   * A wrapper div that assists in positioning.
+   */
+  wrapper: HTMLElement;
+}
+
+export interface IframeContentScriptUi<TMounted>
+  extends ContentScriptUi<TMounted> {
+  /**
+   * The iframe added to the DOM.
+   */
+  iframe: HTMLIFrameElement;
+  /**
+   * A wrapper div that assists in positioning.
+   */
+  wrapper: HTMLDivElement;
+}
+
+export interface ShadowRootContentScriptUi<TMounted>
+  extends ContentScriptUi<TMounted> {
+  /**
+   * The `HTMLElement` hosting the shadow root used to isolate the UI's styles. This is the element
+   * that get's added to the DOM. This element's style is not isolated from the webpage.
+   */
+  shadowHost: HTMLElement;
+  /**
+   * The container element inside the `ShadowRoot` whose styles are isolated. The UI is mounted
+   * inside this `HTMLElement`.
+   */
+  uiContainer: HTMLElement;
+  /**
+   * The shadow root performing the isolation.
+   */
+  shadow: ShadowRoot;
+}
+
+export interface ContentScriptUi<TMounted> {
+  /**
+   * Function that mounts or remounts the UI on the page.
+   */
+  mount: () => void;
+  /**
+   * Function that removes the UI from the webpage.
+   */
+  remove: () => void;
+  /**>
+   * Custom data returned from the `options.mount` function.
+   */
+  mounted: TMounted | undefined;
+}
+
+export type ContentScriptUiOptions<TMounted> = ContentScriptPositioningOptions &
+  ContentScriptAnchoredOptions & {
+    /**
+     * Callback called before the UI is removed from the webpage. Use to cleanup your UI, like
+     * unmounting your Vue or React apps.
+     */
+    onRemove?: (mounted: TMounted | undefined) => void;
+  };
+
+export type IntegratedContentScriptUiOptions<TMounted> =
+  ContentScriptUiOptions<TMounted> & {
+    /**
+     * Tag used to create the wrapper element.
+     *
+     * @default "div"
+     */
+    tag?: string;
+    /**
+     * Callback executed when mounting the UI. This function should create and append the UI to the
+     * `wrapper` element. It is called every time `ui.mount()` is called.
+     *
+     * Optionally return a value that can be accessed at `ui.mounted` or in the `onRemove` callback.
+     */
+    onMount: (wrapper: HTMLElement) => TMounted;
+  };
+
+export type IframeContentScriptUiOptions<TMounted> =
+  ContentScriptUiOptions<TMounted> & {
+    /**
+     * The path to the HTML page that will be shown in the iframe. This string is passed into
+     * `browser.runtime.getURL`.
+     */
+    page: PublicPath;
+    /**
+     * Callback executed when mounting the UI. Use this function to customize the iframe or wrapper
+     * element's appearance. It is called every time `ui.mount()` is called.
+     *
+     * Optionally return a value that can be accessed at `ui.mounted` or in the `onRemove` callback.
+     */
+    onMount?: (wrapper: HTMLElement, iframe: HTMLIFrameElement) => TMounted;
+  };
+
+export type ShadowRootContentScriptUiOptions<TMounted> =
+  ContentScriptUiOptions<TMounted> & {
+    /**
+     * The name of the custom component used to host the ShadowRoot. Must be kebab-case.
+     */
+    name: string;
+    /**
+     * Custom CSS text to apply to the UI. If your content script imports/generates CSS and you've
+     * set `cssInjectionMode: "ui"`, the imported CSS will be included automatically. You do not need
+     * to pass those styles in here. This is for any additional styles not in the imported CSS.
+     */
+    css?: string;
+    /**
+     * ShadowRoot's mode.
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot/mode
+     * @default "open"
+     */
+    mode?: 'open' | 'closed';
+    /**
+     * When enabled, `event.stopPropagation` will be called on events trying to bubble out of the
+     * shadow root.
+     *
+     * - Set to `true` to stop the propagation of a default set of events,
+     *   `["keyup", "keydown", "keypress"]`
+     * - Set to an array of event names to stop the propagation of a custom list of events
+     */
+    isolateEvents?: boolean | string[];
+    /**
+     * Callback executed when mounting the UI. This function should create and append the UI to the
+     * `uiContainer` element. It is called every time `ui.mount()` is called.
+     *
+     * Optionally return a value that can be accessed at `ui.mounted` or in the `onRemove` callback.
+     */
+    onMount: (
+      uiContainer: HTMLElement,
+      shadow: ShadowRoot,
+      shadowHost: HTMLElement,
+    ) => TMounted;
+  };
+
+export type ContentScriptOverlayAlignment =
+  | 'top-left'
+  | 'top-right'
+  | 'bottom-left'
+  | 'bottom-right';
+
+/**
+ * ![Visualization of different append modes](https://wxt.dev/content-script-ui-append.png)
+ */
+export type ContentScriptAppendMode =
+  | 'last'
+  | 'first'
+  | 'replace'
+  | 'before'
+  | 'after'
+  | ((anchor: Element, ui: Element) => void);
+
+export interface ContentScriptInlinePositioningOptions {
+  position: 'inline';
+}
+
+export interface ContentScriptOverlayPositioningOptions {
+  position: 'overlay';
+  /**
+   * The `z-index` used on the `wrapper` element. Set to a positive number to show your UI over website
+   * content.
+   */
+  zIndex?: number;
+  /**
+   * When using `type: "overlay"`, the mounted element is 0px by 0px in size. Alignment specifies
+   * which corner is aligned with that 0x0 pixel space.
+   *
+   * ![Visualization of alignment options](https://wxt.dev/content-script-ui-alignment.png)
+   *
+   * @default "top-left"
+   */
+  alignment?: ContentScriptOverlayAlignment;
+}
+
+export interface ContentScriptModalPositioningOptions {
+  position: 'modal';
+  /**
+   * The `z-index` used on the `shadowHost`. Set to a positive number to show your UI over website
+   * content.
+   */
+  zIndex?: number;
+}
+
+/**
+ * Choose between `"inline"`, `"overlay"`, or `"modal" `types.
+ *
+ * ![Visualization of different types](https://wxt.dev/content-script-ui-type.png)
+ */
+export type ContentScriptPositioningOptions =
+  | ContentScriptInlinePositioningOptions
+  | ContentScriptOverlayPositioningOptions
+  | ContentScriptModalPositioningOptions;
+
+export interface ContentScriptAnchoredOptions {
+  /**
+   * A CSS selector, element, or function that returns one of the two. Along with `append`, the
+   * `anchor` dictates where in the page the UI will be added.
+   */
+  anchor?:
+    | string
+    | Element
+    | null
+    | undefined
+    | (() => string | Element | null | undefined);
+  /**
+   * In combination with `anchor`, decide how to add the UI to the DOM.
+   *
+   * - `"last"` (default) - Add the UI as the last child of the `anchor` element
+   * - `"first"` - Add the UI as the last child of the `anchor` element
+   * - `"replace"` - Replace the `anchor` element with the UI.
+   * - `"before"` - Add the UI as the sibling before the `anchor` element
+   * - `"after"` - Add the UI as the sibling after the `anchor` element
+   * - `(anchor, ui) => void` - Customizable function that let's you add the UI to the DOM
+   */
+  append?: ContentScriptAppendMode | ((anchor: Element, ui: Element) => void);
+}

src/client/index.ts

@@ -4,12 +4,3 @@
  * @module wxt/client
  */
 export * from './content-scripts';
-export {
-  ContentScriptOverlayAlignment,
-  ContentScriptAppendMode,
-  ContentScriptPositioningOptions,
-  ContentScriptAnchoredOptions,
-  ContentScriptInlinePositioningOptions,
-  ContentScriptOverlayPositioningOptions,
-  ContentScriptModalPositioningOptions,
-} from './utils/content-script-ui';

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

@@ -1,163 +0,0 @@
-export type ContentScriptOverlayAlignment =
-  | 'top-left'
-  | 'top-right'
-  | 'bottom-left'
-  | 'bottom-right';
-
-/**
- * ![Visualization of different append modes](https://wxt.dev/content-script-ui-append.png)
- */
-export type ContentScriptAppendMode =
-  | 'last'
-  | 'first'
-  | 'replace'
-  | 'before'
-  | 'after'
-  | ((anchor: Element, ui: Element) => void);
-
-export function mountContentScriptUiRoot(
-  root: HTMLElement,
-  options: ContentScriptAnchoredOptions,
-): void {
-  const anchor = getAnchor(options);
-  if (anchor == null)
-    throw Error(
-      'Failed to mount content script UI: could not find anchor element',
-    );
-
-  switch (options.append) {
-    case undefined:
-    case 'last':
-      anchor.append(root);
-      break;
-    case 'first':
-      if (anchor.firstChild) {
-        anchor.insertBefore(root, anchor.firstChild);
-      } else {
-        anchor.append(root);
-      }
-      break;
-    case 'replace':
-      anchor.replaceWith(root);
-      break;
-    case 'after':
-      anchor.replaceWith(anchor, root);
-      break;
-    case 'before':
-      anchor.replaceWith(root, anchor);
-      break;
-    default:
-      options.append(anchor, root);
-      break;
-  }
-}
-
-export interface ContentScriptInlinePositioningOptions {
-  type: 'inline';
-}
-
-export interface ContentScriptOverlayPositioningOptions {
-  type: 'overlay';
-  /**
-   * The `z-index` used on the `shadowHost`. Set to a positive number to show your UI over website
-   * content.
-   */
-  zIndex?: number;
-  /**
-   * When using `type: "overlay"`, the mounted element is 0px by 0px in size. Alignment specifies
-   * which corner is aligned with that 0x0 pixel space.
-   *
-   * ![Visualization of alignment options](https://wxt.dev/content-script-ui-alignment.png)
-   *
-   * @default "top-left"
-   */
-  alignment?: ContentScriptOverlayAlignment;
-}
-
-export interface ContentScriptModalPositioningOptions {
-  type: 'modal';
-  /**
-   * The `z-index` used on the `shadowHost`. Set to a positive number to show your UI over website
-   * content.
-   */
-  zIndex?: number;
-}
-
-/**
- * Choose between `"inline"`, `"overlay"`, or `"modal" `types.
- *
- * ![Visualization of different types](https://wxt.dev/content-script-ui-type.png)
- */
-export type ContentScriptPositioningOptions =
-  | ContentScriptInlinePositioningOptions
-  | ContentScriptOverlayPositioningOptions
-  | ContentScriptModalPositioningOptions;
-
-export function applyContentScriptUiPosition(
-  root: HTMLElement,
-  positionedElement: HTMLElement | undefined | null,
-  options: ContentScriptPositioningOptions,
-): void {
-  if (options.type !== 'inline') {
-    if (options.zIndex != null) root.style.zIndex = String(options.zIndex);
-
-    root.style.overflow = 'visible';
-    root.style.position = 'relative';
-    root.style.width = '0';
-    root.style.height = '0';
-    root.style.display = 'block';
-
-    if (positionedElement) {
-      if (options.type === 'overlay') {
-        positionedElement.style.position = 'absolute';
-        if (options.alignment?.startsWith('bottom-'))
-          positionedElement.style.bottom = '0';
-        else positionedElement.style.top = '0';
-
-        if (options.alignment?.endsWith('-right'))
-          positionedElement.style.right = '0';
-        else positionedElement.style.left = '0';
-      } else {
-        positionedElement.style.position = 'fixed';
-        positionedElement.style.top = '0';
-        positionedElement.style.bottom = '0';
-        positionedElement.style.left = '0';
-        positionedElement.style.right = '0';
-      }
-    }
-  }
-}
-
-function getAnchor(options: ContentScriptAnchoredOptions): Element | undefined {
-  if (options.anchor == null) return document.body;
-
-  let resolved =
-    typeof options.anchor === 'function' ? options.anchor() : options.anchor;
-  if (typeof resolved === 'string')
-    return document.querySelector<Element>(resolved) ?? undefined;
-  return resolved ?? undefined;
-}
-
-export interface ContentScriptAnchoredOptions {
-  /**
-   * A CSS selector, element, or function that returns one of the two. Along with `append`, the
-   * `anchor` dictates where in the page the UI will be added.
-   */
-  anchor?:
-    | string
-    | Element
-    | null
-    | undefined
-    | (() => string | Element | null | undefined);
-  /**
-   * In combination with `anchor`, decide how to add the UI to the DOM.
-   *
-   * - `"last"` (default) - Add the UI as the last child of the `anchor` element
-   * - `"first"` - Add the UI as the last child of the `anchor` element
-   * - `"replace"` - Replace the `anchor` element with the UI.
-   * - `"before"` - Add the UI as the sibling before the `anchor` element
-   * - `"after"` - Add the UI as the sibling after the `anchor` element
-   * - `(anchor, ui) => void` - Customizable function that let's you add the UI to the DOM
-   */
-  append?: ContentScriptAppendMode | ((anchor: Element, ui: Element) => void);
-}

src/core/builders/vite/index.ts

@@ -12,7 +12,7 @@ import {
 import * as wxtPlugins from './plugins';
 import { getEntrypointBundlePath } from '~/core/utils/entrypoints';
 
-export async function craeteViteBuilder(
+export async function createViteBuilder(
   inlineConfig: InlineConfig,
   userConfig: UserConfig,
   wxtConfig: Omit<InternalConfig, 'builder'>,
@@ -230,6 +230,9 @@ export async function craeteViteBuilder(
         async listen() {
           await viteServer.listen(info.port);
         },
+        async close() {
+          await viteServer.close();
+        },
         transformHtml(...args) {
           return viteServer.transformIndexHtml(...args);
         },

src/core/create-server.ts

@@ -20,6 +20,7 @@ import {
   getInternalConfig,
   detectDevChanges,
   rebuild,
+  findEntrypoints,
 } from '~/core/utils/building';
 import { createExtensionRunner } from '~/core/runners';
 import { consola } from 'consola';
@@ -48,22 +49,46 @@ export async function createServer(
     origin,
   };
 
+  const buildAndOpenBrowser = async () => {
+    // Build after starting the dev server so it can be used to transform HTML files
+    server.currentOutput = await internalBuild(config);
+
+    // Open browser after everything is ready to go.
+    await runner.openBrowser(config);
+  };
+
+  /**
+   * Stops the previous runner, grabs the latest config, and recreates the runner.
+   */
+  const closeAndRecreateRunner = async () => {
+    await runner.closeBrowser();
+    config = await getLatestConfig();
+    runner = await createExtensionRunner(config);
+  };
+
   // Server instance must be created first so its reference can be added to the internal config used
   // to pre-render entrypoints
   const server: WxtDevServer = {
     ...serverInfo,
-    watcher: undefined as any, // Filled out later down below
-    ws: undefined as any, // Filled out later down below
-    currentOutput: undefined as any, // Filled out later down below
+    get watcher() {
+      return builderServer.watcher;
+    },
+    get ws() {
+      return builderServer.ws;
+    },
+    currentOutput: undefined,
     async start() {
       await builderServer.listen();
       config.logger.success(`Started dev server @ ${serverInfo.origin}`);
-
-      // Build after starting the dev server so it can be used to transform HTML files
-      server.currentOutput = await internalBuild(config);
-
-      // Open browser after everything is ready to go.
-      await runner.openBrowser(config);
+      await buildAndOpenBrowser();
+    },
+    async stop() {
+      await runner.closeBrowser();
+      await builderServer.close();
+    },
+    async restart() {
+      await closeAndRecreateRunner();
+      await buildAndOpenBrowser();
     },
     transformHtml(url, html, originalUrl) {
       return builderServer.transformHtml(url, html, originalUrl);
@@ -77,23 +102,25 @@ export async function createServer(
     reloadExtension() {
       server.ws.send('wxt:reload-extension');
     },
+    async restartBrowser() {
+      await closeAndRecreateRunner();
+      await runner.openBrowser(config);
+    },
   };
 
   const getLatestConfig = () =>
     getInternalConfig(inlineConfig ?? {}, 'serve', server);
   let config = await getLatestConfig();
 
-  const [runner, builderServer] = await Promise.all([
+  let [runner, builderServer] = await Promise.all([
     createExtensionRunner(config),
     config.builder.createServer(server),
   ]);
 
-  server.watcher = builderServer.watcher;
-  server.ws = builderServer.ws;
-
   // Register content scripts for the first time after the background starts up since they're not
   // listed in the manifest
   server.ws.on('wxt:background-initialized', () => {
+    if (server.currentOutput == null) return;
     reloadContentScripts(server.currentOutput.steps, config, server);
   });
 
@@ -137,18 +164,39 @@ function createFileReloader(options: {
     changeQueue.push([event, path]);
 
     await fileChangedMutex.runExclusive(async () => {
-      const fileChanges = changeQueue.splice(0, changeQueue.length);
+      if (server.currentOutput == null) return;
+
+      const fileChanges = changeQueue
+        .splice(0, changeQueue.length)
+        .map(([_, file]) => file);
       if (fileChanges.length === 0) return;
 
-      const changes = detectDevChanges(fileChanges, server.currentOutput);
+      const changes = detectDevChanges(
+        config,
+        fileChanges,
+        server.currentOutput,
+      );
       if (changes.type === 'no-change') return;
 
+      if (changes.type === 'full-restart') {
+        config.logger.info('Config changed, restarting server...');
+        server.restart();
+        return;
+      }
+
+      if (changes.type === 'browser-restart') {
+        config.logger.info('Runner config changed, restarting browser...');
+        server.restartBrowser();
+        return;
+      }
+
       // Log the entrypoints that were effected
       config.logger.info(
-        `Changed: ${Array.from(new Set(fileChanges.map((change) => change[1])))
+        `Changed: ${Array.from(new Set(fileChanges))
           .map((file) => pc.dim(relative(config.root, file)))
           .join(', ')}`,
       );
+
       const rebuiltNames = changes.rebuildGroups
         .flat()
         .map((entry) => {
@@ -159,8 +207,10 @@ function createFileReloader(options: {
         .join(pc.dim(', '));
 
       // Rebuild entrypoints on change
+      const allEntrypoints = await findEntrypoints(config);
       const { output: newOutput } = await rebuild(
         config,
+        allEntrypoints,
         // TODO: this excludes new entrypoints, so they're not built until the dev command is restarted
         changes.rebuildGroups,
         changes.cachedOutput,
@@ -194,6 +244,8 @@ function reloadContentScripts(
 ) {
   if (config.manifestVersion === 3) {
     steps.forEach((step) => {
+      if (server.currentOutput == null) return;
+
       const entry = step.entrypoints;
       if (Array.isArray(entry) || entry.type !== 'content-script') return;
 

src/core/runners/web-ext.ts

@@ -1,5 +1,6 @@
 import type { WebExtRunInstance } from 'web-ext-run';
 import { ExtensionRunner } from '~/types';
+import { formatDuration } from '../utils/time';
 
 /**
  * Create an `ExtensionRunner` backed by `web-ext`.
@@ -9,7 +10,7 @@ export function createWebExtRunner(): ExtensionRunner {
 
   return {
     async openBrowser(config) {
-      config.logger.info('Opening browser...');
+      const startTime = Date.now();
 
       if (config.browser === 'firefox' && config.manifestVersion === 3) {
         throw Error(
@@ -17,7 +18,7 @@ export function createWebExtRunner(): ExtensionRunner {
         );
       }
 
-      // Use the plugin's logger instead of web-ext's built-in one.
+      // Use WXT's logger instead of web-ext's built-in one.
       const webExtLogger = await import('web-ext-run/util/logger');
       webExtLogger.consoleStream.write = ({ level, msg, name }) => {
         if (level >= ERROR_LOG_LEVEL) config.logger.error(name, msg);
@@ -61,7 +62,8 @@ export function createWebExtRunner(): ExtensionRunner {
       const webExt = await import('web-ext-run');
       runner = await webExt.default.cmd.run(finalConfig, options);
 
-      config.logger.success('Opened!');
+      const duration = Date.now() - startTime;
+      config.logger.success(`Opened browser in ${formatDuration(duration)}`);
     },
 
     async closeBrowser() {

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

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { every } from '~/core/utils/arrays';
+import { every, some } from '~/core/utils/arrays';
 
 describe('Array Utils', () => {
   describe('every', () => {
@@ -15,4 +15,20 @@ describe('Array Utils', () => {
       expect(every([1, 2, 1], (item) => item === 1)).toBe(false);
     });
   });
+
+  describe('some', () => {
+    it('should return true if one value returns true', () => {
+      const array = [1, 2, 3];
+      const predicate = (item: number) => item === 2;
+
+      expect(some(array, predicate)).toBe(true);
+    });
+
+    it('should return false if no values match', () => {
+      const array = [1, 2, 3];
+      const predicate = (item: number) => item === 4;
+
+      expect(some(array, predicate)).toBe(false);
+    });
+  });
 });

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

@@ -47,6 +47,7 @@ describe('Entrypoint Utils', () => {
         name,
         outputDir,
         options: {},
+        skipped: false,
       };
 
       const actual = getEntrypointOutputFile(entrypoint, ext);

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

@@ -6,6 +6,7 @@ import {
   fakeBuildOutput,
   fakeEntrypoint,
   fakeInternalConfig,
+  fakeManifestCommand,
   fakeOptionsEntrypoint,
   fakePopupEntrypoint,
 } from '../testing/fake-objects';
@@ -52,7 +53,11 @@ describe('Manifest Utils', () => {
           },
         };
 
-        const actual = await generateManifest([popup], buildOutput, config);
+        const { manifest: actual } = await generateManifest(
+          [popup],
+          buildOutput,
+          config,
+        );
 
         expect(actual).toMatchObject(expected);
       });
@@ -79,7 +84,11 @@ describe('Manifest Utils', () => {
             default_popup: 'popup.html',
           };
 
-          const actual = await generateManifest([popup], buildOutput, config);
+          const { manifest: actual } = await generateManifest(
+            [popup],
+            buildOutput,
+            config,
+          );
 
           expect(actual[expectedType]).toEqual(expected);
         },
@@ -102,7 +111,11 @@ describe('Manifest Utils', () => {
           action: config.manifest.action,
         };
 
-        const actual = await generateManifest([], buildOutput, config);
+        const { manifest: actual } = await generateManifest(
+          [],
+          buildOutput,
+          config,
+        );
 
         expect(actual).toMatchObject(expected);
       });
@@ -131,7 +144,11 @@ describe('Manifest Utils', () => {
           page: 'options.html',
         };
 
-        const actual = await generateManifest([options], buildOutput, config);
+        const { manifest: actual } = await generateManifest(
+          [options],
+          buildOutput,
+          config,
+        );
 
         expect(actual.options_ui).toEqual(expected);
       });
@@ -149,7 +166,11 @@ describe('Manifest Utils', () => {
           page: 'options.html',
         };
 
-        const actual = await generateManifest([options], buildOutput, config);
+        const { manifest: actual } = await generateManifest(
+          [options],
+          buildOutput,
+          config,
+        );
 
         expect(actual.options_ui).toEqual(expected);
       });
@@ -179,7 +200,7 @@ describe('Manifest Utils', () => {
               service_worker: 'background.js',
             };
 
-            const actual = await generateManifest(
+            const { manifest: actual } = await generateManifest(
               [background],
               buildOutput,
               config,
@@ -201,7 +222,7 @@ describe('Manifest Utils', () => {
             scripts: ['background.js'],
           };
 
-          const actual = await generateManifest(
+          const { manifest: actual } = await generateManifest(
             [background],
             buildOutput,
             config,
@@ -226,7 +247,7 @@ describe('Manifest Utils', () => {
               scripts: ['background.js'],
             };
 
-            const actual = await generateManifest(
+            const { manifest: actual } = await generateManifest(
               [background],
               buildOutput,
               config,
@@ -248,7 +269,7 @@ describe('Manifest Utils', () => {
             scripts: ['background.js'],
           };
 
-          const actual = await generateManifest(
+          const { manifest: actual } = await generateManifest(
             [background],
             buildOutput,
             config,
@@ -274,7 +295,11 @@ describe('Manifest Utils', () => {
         });
         const config = fakeInternalConfig();
 
-        const actual = await generateManifest(entrypoints, buildOutput, config);
+        const { manifest: actual } = await generateManifest(
+          entrypoints,
+          buildOutput,
+          config,
+        );
 
         expect(actual.icons).toEqual({
           16: 'icon-16.png',
@@ -296,7 +321,11 @@ describe('Manifest Utils', () => {
         });
         const config = fakeInternalConfig();
 
-        const actual = await generateManifest(entrypoints, buildOutput, config);
+        const { manifest: actual } = await generateManifest(
+          entrypoints,
+          buildOutput,
+          config,
+        );
 
         expect(actual.icons).toBeUndefined();
       });
@@ -323,7 +352,11 @@ describe('Manifest Utils', () => {
           },
         });
 
-        const actual = await generateManifest(entrypoints, buildOutput, config);
+        const { manifest: actual } = await generateManifest(
+          entrypoints,
+          buildOutput,
+          config,
+        );
 
         expect(actual.icons).toEqual(expected);
       });
@@ -339,6 +372,7 @@ describe('Manifest Utils', () => {
           options: {
             matches: ['*://google.com/*'],
           },
+          skipped: false,
         };
         const cs1Styles: OutputAsset = {
           type: 'asset',
@@ -353,6 +387,7 @@ describe('Manifest Utils', () => {
             matches: ['*://google.com/*'],
             runAt: 'document_end',
           },
+          skipped: false,
         };
         const cs2Styles: OutputAsset = {
           type: 'asset',
@@ -367,6 +402,7 @@ describe('Manifest Utils', () => {
             matches: ['*://google.com/*'],
             runAt: 'document_end',
           },
+          skipped: false,
         };
         const cs3Styles: OutputAsset = {
           type: 'asset',
@@ -381,6 +417,7 @@ describe('Manifest Utils', () => {
             matches: ['*://duckduckgo.com/*'],
             runAt: 'document_end',
           },
+          skipped: false,
         };
         const cs4Styles: OutputAsset = {
           type: 'asset',
@@ -395,6 +432,7 @@ describe('Manifest Utils', () => {
             matches: ['*://google.com/*'],
             world: 'MAIN',
           },
+          skipped: false,
         };
         const cs5Styles: OutputAsset = {
           type: 'asset',
@@ -418,7 +456,11 @@ describe('Manifest Utils', () => {
           ],
         };
 
-        const actual = await generateManifest(entrypoints, buildOutput, config);
+        const { manifest: actual } = await generateManifest(
+          entrypoints,
+          buildOutput,
+          config,
+        );
 
         expect(actual.content_scripts).toContainEqual({
           matches: ['*://google.com/*'],
@@ -454,6 +496,7 @@ describe('Manifest Utils', () => {
           options: {
             matches: ['*://google.com/*'],
           },
+          skipped: false,
         };
         const generatedContentScript = {
           matches: ['*://google.com/*'],
@@ -474,7 +517,11 @@ describe('Manifest Utils', () => {
           },
         });
 
-        const actual = await generateManifest(entrypoints, buildOutput, config);
+        const { manifest: actual } = await generateManifest(
+          entrypoints,
+          buildOutput,
+          config,
+        );
 
         expect(actual.content_scripts).toContainEqual(userContentScript);
         expect(actual.content_scripts).toContainEqual(generatedContentScript);
@@ -493,6 +540,7 @@ describe('Manifest Utils', () => {
                 matches: ['*://google.com/*'],
                 cssInjectionMode,
               },
+              skipped: false,
             };
             const styles: OutputAsset = {
               type: 'asset',
@@ -509,7 +557,7 @@ describe('Manifest Utils', () => {
               command: 'build',
             });
 
-            const actual = await generateManifest(
+            const { manifest: actual } = await generateManifest(
               entrypoints,
               buildOutput,
               config,
@@ -537,6 +585,7 @@ describe('Manifest Utils', () => {
                 matches: ['*://google.com/*'],
                 cssInjectionMode,
               },
+              skipped: false,
             };
             const styles: OutputAsset = {
               type: 'asset',
@@ -553,7 +602,7 @@ describe('Manifest Utils', () => {
               command: 'build',
             });
 
-            const actual = await generateManifest(
+            const { manifest: actual } = await generateManifest(
               entrypoints,
               buildOutput,
               config,
@@ -578,6 +627,7 @@ describe('Manifest Utils', () => {
               matches: ['*://google.com/*'],
               cssInjectionMode: 'ui',
             },
+            skipped: false,
           };
           const styles: OutputAsset = {
             type: 'asset',
@@ -595,7 +645,7 @@ describe('Manifest Utils', () => {
             manifestVersion: 3,
           });
 
-          const actual = await generateManifest(
+          const { manifest: actual } = await generateManifest(
             entrypoints,
             buildOutput,
             config,
@@ -619,6 +669,7 @@ describe('Manifest Utils', () => {
               matches: ['*://google.com/*'],
               cssInjectionMode: 'ui',
             },
+            skipped: false,
           };
           const styles: OutputAsset = {
             type: 'asset',
@@ -636,7 +687,7 @@ describe('Manifest Utils', () => {
             manifestVersion: 2,
           });
 
-          const actual = await generateManifest(
+          const { manifest: actual } = await generateManifest(
             entrypoints,
             buildOutput,
             config,
@@ -657,6 +708,7 @@ describe('Manifest Utils', () => {
               matches: ['*://play.google.com/books/*'],
               cssInjectionMode: 'ui',
             },
+            skipped: false,
           };
           const styles: OutputAsset = {
             type: 'asset',
@@ -674,7 +726,7 @@ describe('Manifest Utils', () => {
             manifestVersion: 3,
           });
 
-          const actual = await generateManifest(
+          const { manifest: actual } = await generateManifest(
             entrypoints,
             buildOutput,
             config,
@@ -701,6 +753,7 @@ describe('Manifest Utils', () => {
             matches: ['*://google.com/*'],
             cssInjectionMode: 'ui',
           },
+          skipped: false,
         };
         const styles: OutputAsset = {
           type: 'asset',
@@ -723,7 +776,11 @@ describe('Manifest Utils', () => {
           },
         });
 
-        const actual = await generateManifest(entrypoints, buildOutput, config);
+        const { manifest: actual } = await generateManifest(
+          entrypoints,
+          buildOutput,
+          config,
+        );
 
         expect(actual.web_accessible_resources).toEqual([
           { resources: ['one.png'], matches: ['*://one.com/*'] },
@@ -744,6 +801,7 @@ describe('Manifest Utils', () => {
             matches: ['*://google.com/*'],
             cssInjectionMode: 'ui',
           },
+          skipped: false,
         };
         const styles: OutputAsset = {
           type: 'asset',
@@ -764,7 +822,11 @@ describe('Manifest Utils', () => {
           },
         });
 
-        const actual = await generateManifest(entrypoints, buildOutput, config);
+        const { manifest: actual } = await generateManifest(
+          entrypoints,
+          buildOutput,
+          config,
+        );
 
         expect(actual.web_accessible_resources).toEqual([
           'one.png',
@@ -787,7 +849,11 @@ describe('Manifest Utils', () => {
           author: newAuthor,
         };
 
-        const actual = await generateManifest(entrypoints, buildOutput, config);
+        const { manifest: actual } = await generateManifest(
+          entrypoints,
+          buildOutput,
+          config,
+        );
 
         expect(actual).toMatchObject(expected);
       });
@@ -809,7 +875,7 @@ describe('Manifest Utils', () => {
             },
           });
 
-          const actual = await generateManifest(
+          const { manifest: actual } = await generateManifest(
             entrypoints,
             buildOutput,
             config,
@@ -835,7 +901,7 @@ describe('Manifest Utils', () => {
             },
           });
 
-          const actual = await generateManifest(
+          const { manifest: actual } = await generateManifest(
             entrypoints,
             buildOutput,
             config,
@@ -860,7 +926,7 @@ describe('Manifest Utils', () => {
             },
           });
 
-          const actual = await generateManifest(
+          const { manifest: actual } = await generateManifest(
             entrypoints,
             buildOutput,
             config,
@@ -881,7 +947,11 @@ describe('Manifest Utils', () => {
           },
         });
 
-        const actual = await generateManifest(entrypoints, buildOutput, config);
+        const { manifest: actual } = await generateManifest(
+          entrypoints,
+          buildOutput,
+          config,
+        );
 
         expect(actual.version).toBe('0.0.0');
         expect(actual.version_name).toBeUndefined();
@@ -895,8 +965,9 @@ describe('Manifest Utils', () => {
     describe('commands', () => {
       const reloadCommandName = 'wxt:reload-extension';
       const reloadCommand = {
+        description: expect.any(String),
         suggested_key: {
-          default: 'Ctrl+E',
+          default: 'Alt+R',
         },
       };
 
@@ -905,21 +976,65 @@ describe('Manifest Utils', () => {
         const output = fakeBuildOutput();
         const entrypoints = fakeArray(fakeEntrypoint);
 
-        const actual = await generateManifest(entrypoints, output, config);
+        const { manifest: actual } = await generateManifest(
+          entrypoints,
+          output,
+          config,
+        );
 
-        expect(actual.commands).toMatchObject({
+        expect(actual.commands).toEqual({
           [reloadCommandName]: reloadCommand,
         });
       });
 
+      it('should customize the reload commands key binding if passing a custom command', async () => {
+        const config = fakeInternalConfig({
+          command: 'serve',
+          dev: {
+            reloadCommand: 'Ctrl+E',
+          },
+        });
+        const output = fakeBuildOutput();
+        const entrypoints = fakeArray(fakeEntrypoint);
+
+        const { manifest: actual } = await generateManifest(
+          entrypoints,
+          output,
+          config,
+        );
+
+        expect(actual.commands).toEqual({
+          [reloadCommandName]: {
+            ...reloadCommand,
+            suggested_key: {
+              default: 'Ctrl+E',
+            },
+          },
+        });
+      });
+
+      it("should not include the reload command when it's been disabled", async () => {
+        const config = fakeInternalConfig({
+          command: 'serve',
+          dev: {
+            reloadCommand: false,
+          },
+        });
+        const output = fakeBuildOutput();
+        const entrypoints = fakeArray(fakeEntrypoint);
+
+        const { manifest: actual } = await generateManifest(
+          entrypoints,
+          output,
+          config,
+        );
+
+        expect(actual.commands).toBeUndefined();
+      });
+
       it('should not override any existing commands when adding the one to reload the extension', async () => {
         const customCommandName = 'custom-command';
-        const customCommand = {
-          description: 'Some other command',
-          suggested_key: {
-            default: 'Ctrl+H',
-          },
-        };
+        const customCommand = fakeManifestCommand();
         const config = fakeInternalConfig({
           command: 'serve',
           manifest: {
@@ -931,20 +1046,52 @@ describe('Manifest Utils', () => {
         const output = fakeBuildOutput();
         const entrypoints = fakeArray(fakeEntrypoint);
 
-        const actual = await generateManifest(entrypoints, output, config);
+        const { manifest: actual } = await generateManifest(
+          entrypoints,
+          output,
+          config,
+        );
 
-        expect(actual.commands).toMatchObject({
+        expect(actual.commands).toEqual({
           [reloadCommandName]: reloadCommand,
           [customCommandName]: customCommand,
         });
       });
 
+      it('should not include the command if there are already 4 others (the max)', async () => {
+        const commands = {
+          command1: fakeManifestCommand(),
+          command2: fakeManifestCommand(),
+          command3: fakeManifestCommand(),
+          command4: fakeManifestCommand(),
+        };
+        const config = fakeInternalConfig({
+          command: 'serve',
+          manifest: { commands },
+        });
+        const output = fakeBuildOutput();
+        const entrypoints = fakeArray(fakeEntrypoint);
+
+        const { manifest: actual, warnings } = await generateManifest(
+          entrypoints,
+          output,
+          config,
+        );
+
+        expect(actual.commands).toEqual(commands);
+        expect(warnings).toHaveLength(1);
+      });
+
       it('should not include the command when building an extension', async () => {
         const config = fakeInternalConfig({ command: 'build' });
         const output = fakeBuildOutput();
         const entrypoints = fakeArray(fakeEntrypoint);
 
-        const actual = await generateManifest(entrypoints, output, config);
+        const { manifest: actual } = await generateManifest(
+          entrypoints,
+          output,
+          config,
+        );
 
         expect(actual.commands).toBeUndefined();
       });

src/core/utils/__tests__/test-entrypoints/imported-option.ts

@@ -0,0 +1,7 @@
+import { defineContentScript } from '~/sandbox';
+import { faker } from '@faker-js/faker';
+
+export default defineContentScript({
+  matches: [faker.string.nanoid()],
+  main() {},
+});

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

@@ -0,0 +1,100 @@
+import { describe, it, expect } from 'vitest';
+import {
+  fakeArray,
+  fakeContentScriptEntrypoint,
+  fakeEntrypoint,
+  fakeGenericEntrypoint,
+} from '../testing/fake-objects';
+import { validateEntrypoints } from '../validation';
+
+describe('Validation Utils', () => {
+  describe('validateEntrypoints', () => {
+    it('should return no errors when there are no errors', () => {
+      const entrypoints = fakeArray(fakeEntrypoint);
+      const expected = {
+        errors: [],
+        errorCount: 0,
+        warningCount: 0,
+      };
+
+      const actual = validateEntrypoints(entrypoints);
+
+      expect(actual).toEqual(expected);
+    });
+
+    it('should return an error when exclude is not an array', () => {
+      const entrypoint = fakeGenericEntrypoint({
+        options: {
+          // @ts-expect-error
+          exclude: 0,
+        },
+      });
+      const expected = {
+        errors: [
+          {
+            type: 'error',
+            message: '`exclude` must be an array of browser names',
+            value: 0,
+            entrypoint,
+          },
+        ],
+        errorCount: 1,
+        warningCount: 0,
+      };
+
+      const actual = validateEntrypoints([entrypoint]);
+
+      expect(actual).toEqual(expected);
+    });
+
+    it('should return an error when include is not an array', () => {
+      const entrypoint = fakeGenericEntrypoint({
+        options: {
+          // @ts-expect-error
+          include: 0,
+        },
+      });
+      const expected = {
+        errors: [
+          {
+            type: 'error',
+            message: '`include` must be an array of browser names',
+            value: 0,
+            entrypoint,
+          },
+        ],
+        errorCount: 1,
+        warningCount: 0,
+      };
+
+      const actual = validateEntrypoints([entrypoint]);
+
+      expect(actual).toEqual(expected);
+    });
+
+    it("should return an error when content scripts don't have a matches", () => {
+      const entrypoint = fakeContentScriptEntrypoint({
+        options: {
+          // @ts-expect-error
+          matches: null,
+        },
+      });
+      const expected = {
+        errors: [
+          {
+            type: 'error',
+            message: '`matches` is required',
+            value: null,
+            entrypoint,
+          },
+        ],
+        errorCount: 1,
+        warningCount: 0,
+      };
+
+      const actual = validateEntrypoints([entrypoint]);
+
+      expect(actual).toEqual(expected);
+    });
+  });
+});

src/core/utils/arrays.ts

@@ -9,3 +9,15 @@ export function every<T>(
     if (!predicate(array[i], i)) return false;
   return true;
 }
+
+/**
+ * Returns true when any of the predicates return true;
+ */
+export function some<T>(
+  array: T[],
+  predicate: (item: T, index: number) => boolean,
+): boolean {
+  for (let i = 0; i < array.length; i++)
+    if (predicate(array[i], i)) return true;
+  return false;
+}

src/core/utils/building/__tests__/detect-dev-changes.test.ts

@@ -10,22 +10,15 @@ import {
   fakePopupEntrypoint,
   fakeOutputAsset,
   fakeOutputChunk,
+  fakeInternalConfig,
 } from '~/core/utils/testing/fake-objects';
 import { BuildOutput, BuildStepOutput } from '~/types';
 
 describe('Detect Dev Changes', () => {
   describe('No changes', () => {
-    it("should return 'no-change' when a build hasn't finished", () => {
-      const actual = detectDevChanges(
-        [['unknown', '/path/to/file.ts']],
-        undefined,
-      );
-
-      expect(actual).toEqual({ type: 'no-change' });
-    });
-
     it("should return 'no-change' when the changed file isn't used by any of the entrypoints", () => {
-      const change: [string, string] = ['unknown', '/some/path.ts'];
+      const config = fakeInternalConfig();
+      const changes = ['/some/path.ts'];
       const currentOutput: BuildOutput = {
         manifest: fakeManifest(),
         publicAssets: [],
@@ -41,18 +34,64 @@ describe('Detect Dev Changes', () => {
         ],
       };
 
-      const actual = detectDevChanges([change], currentOutput);
+      const actual = detectDevChanges(config, changes, currentOutput);
 
       expect(actual).toEqual({ type: 'no-change' });
     });
   });
 
+  describe('wxt.config.ts', () => {
+    it("should return 'full-restart' when one of the changed files is the config file", () => {
+      const configFile = '/root/wxt.config.ts';
+      const config = fakeInternalConfig({
+        userConfigMetadata: {
+          configFile,
+        },
+      });
+      const changes = ['/root/src/public/image.svg', configFile];
+      const currentOutput: BuildOutput = {
+        manifest: fakeManifest(),
+        publicAssets: [],
+        steps: [],
+      };
+      const expected: DevModeChange = {
+        type: 'full-restart',
+      };
+
+      const actual = detectDevChanges(config, changes, currentOutput);
+
+      expect(actual).toEqual(expected);
+    });
+  });
+
+  describe('web-ext.config.ts', () => {
+    it("should return 'browser-restart' when one of the changed files is the config file", () => {
+      const runnerFile = '/root/web-ext.config.ts';
+      const config = fakeInternalConfig({
+        runnerConfig: {
+          configFile: runnerFile,
+        },
+      });
+      const changes = ['/root/src/public/image.svg', runnerFile];
+      const currentOutput: BuildOutput = {
+        manifest: fakeManifest(),
+        publicAssets: [],
+        steps: [],
+      };
+      const expected: DevModeChange = {
+        type: 'browser-restart',
+      };
+
+      const actual = detectDevChanges(config, changes, currentOutput);
+
+      expect(actual).toEqual(expected);
+    });
+  });
+
   describe('Public Assets', () => {
     it("should return 'extension-reload' without any groups to rebuild when the changed file is a public asset", () => {
-      const change: [string, string] = [
-        'unknown',
-        '/root/src/public/image.svg',
-      ];
+      const config = fakeInternalConfig();
+      const changes = ['/root/src/public/image.svg'];
       const asset1 = fakeOutputAsset({
         fileName: 'image.svg',
       });
@@ -73,7 +112,7 @@ describe('Detect Dev Changes', () => {
         },
       };
 
-      const actual = detectDevChanges([change], currentOutput);
+      const actual = detectDevChanges(config, changes, currentOutput);
 
       expect(actual).toEqual(expected);
     });
@@ -81,6 +120,7 @@ describe('Detect Dev Changes', () => {
 
   describe('Background', () => {
     it("should rebuild the background and reload the extension when the changed file in it's chunks' `moduleIds` field", () => {
+      const config = fakeInternalConfig();
       const changedPath = '/root/utils/shared.ts';
       const contentScript = fakeContentScriptEntrypoint({
         inputPath: '/root/overlay.content.ts',
@@ -120,10 +160,7 @@ describe('Detect Dev Changes', () => {
         rebuildGroups: [background],
       };
 
-      const actual = detectDevChanges(
-        [['unknown', changedPath]],
-        currentOutput,
-      );
+      const actual = detectDevChanges(config, [changedPath], currentOutput);
 
       expect(actual).toEqual(expected);
     });
@@ -131,6 +168,7 @@ describe('Detect Dev Changes', () => {
 
   describe('HTML Pages', () => {
     it('should rebuild then reload only the effected pages', async () => {
+      const config = fakeInternalConfig();
       const changedPath = '/root/page1/index.html';
       const htmlPage1 = fakePopupEntrypoint({
         inputPath: changedPath,
@@ -174,10 +212,7 @@ describe('Detect Dev Changes', () => {
         rebuildGroups: [[htmlPage1, htmlPage2]],
       };
 
-      const actual = detectDevChanges(
-        [['unknown', changedPath]],
-        currentOutput,
-      );
+      const actual = detectDevChanges(config, [changedPath], currentOutput);
 
       expect(actual).toEqual(expected);
     });
@@ -185,6 +220,7 @@ describe('Detect Dev Changes', () => {
 
   describe('Content Scripts', () => {
     it('should rebuild then reload only the effected content scripts', async () => {
+      const config = fakeInternalConfig();
       const changedPath = '/root/utils/shared.ts';
       const script1 = fakeContentScriptEntrypoint({
         inputPath: '/root/overlay1.content/index.ts',
@@ -236,10 +272,7 @@ describe('Detect Dev Changes', () => {
         rebuildGroups: [script1, script3],
       };
 
-      const actual = detectDevChanges(
-        [['unknown', changedPath]],
-        currentOutput,
-      );
+      const actual = detectDevChanges(config, [changedPath], currentOutput);
 
       expect(actual).toEqual(expected);
     });

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

@@ -53,6 +53,7 @@ describe('findEntrypoints', () => {
           defaultIcon: { '16': '/icon/16.png' },
           defaultTitle: 'Default Title',
         },
+        skipped: false,
       },
     ],
     [
@@ -72,6 +73,7 @@ describe('findEntrypoints', () => {
         options: {
           defaultTitle: 'Title',
         },
+        skipped: false,
       },
     ],
   ])(
@@ -103,6 +105,7 @@ describe('findEntrypoints', () => {
         inputPath: resolve(config.entrypointsDir, 'options.html'),
         outputDir: config.outDir,
         options: {},
+        skipped: false,
       },
     ],
     [
@@ -123,6 +126,7 @@ describe('findEntrypoints', () => {
         options: {
           openInTab: true,
         },
+        skipped: false,
       },
     ],
   ])(
@@ -146,6 +150,7 @@ describe('findEntrypoints', () => {
         name: 'content',
         inputPath: resolve(config.entrypointsDir, 'content.ts'),
         outputDir: resolve(config.outDir, 'content-scripts'),
+        skipped: false,
       },
     ],
     [
@@ -155,6 +160,7 @@ describe('findEntrypoints', () => {
         name: 'overlay',
         inputPath: resolve(config.entrypointsDir, 'overlay.content.ts'),
         outputDir: resolve(config.outDir, 'content-scripts'),
+        skipped: false,
       },
     ],
     [
@@ -164,6 +170,7 @@ describe('findEntrypoints', () => {
         name: 'content',
         inputPath: resolve(config.entrypointsDir, 'content/index.ts'),
         outputDir: resolve(config.outDir, 'content-scripts'),
+        skipped: false,
       },
     ],
     [
@@ -173,6 +180,7 @@ describe('findEntrypoints', () => {
         name: 'overlay',
         inputPath: resolve(config.entrypointsDir, 'overlay.content/index.ts'),
         outputDir: resolve(config.outDir, 'content-scripts'),
+        skipped: false,
       },
     ],
     [
@@ -182,6 +190,7 @@ describe('findEntrypoints', () => {
         name: 'overlay',
         inputPath: resolve(config.entrypointsDir, 'overlay.content.tsx'),
         outputDir: resolve(config.outDir, 'content-scripts'),
+        skipped: false,
       },
     ],
   ])(
@@ -212,6 +221,7 @@ describe('findEntrypoints', () => {
         name: 'background',
         inputPath: resolve(config.entrypointsDir, 'background.ts'),
         outputDir: config.outDir,
+        skipped: false,
       },
     ],
     [
@@ -221,6 +231,7 @@ describe('findEntrypoints', () => {
         name: 'background',
         inputPath: resolve(config.entrypointsDir, 'background/index.ts'),
         outputDir: config.outDir,
+        skipped: false,
       },
     ],
   ])(
@@ -258,6 +269,7 @@ describe('findEntrypoints', () => {
       name: 'background',
       options: {},
       outputDir: config.outDir,
+      skipped: false,
     });
   });
 
@@ -278,6 +290,7 @@ describe('findEntrypoints', () => {
         name: 'injected',
         inputPath: resolve(config.entrypointsDir, path),
         outputDir: config.outDir,
+        skipped: false,
       };
       const options: GenericEntrypoint['options'] = {};
       globMock.mockResolvedValueOnce([path]);
@@ -304,6 +317,7 @@ describe('findEntrypoints', () => {
         inputPath: resolve(config.entrypointsDir, 'sandbox.html'),
         outputDir: config.outDir,
         options: {},
+        skipped: false,
       },
     ],
     [
@@ -314,6 +328,7 @@ describe('findEntrypoints', () => {
         inputPath: resolve(config.entrypointsDir, 'sandbox/index.html'),
         outputDir: config.outDir,
         options: {},
+        skipped: false,
       },
     ],
     [
@@ -324,6 +339,7 @@ describe('findEntrypoints', () => {
         inputPath: resolve(config.entrypointsDir, 'named.sandbox.html'),
         outputDir: config.outDir,
         options: {},
+        skipped: false,
       },
     ],
     [
@@ -334,6 +350,7 @@ describe('findEntrypoints', () => {
         inputPath: resolve(config.entrypointsDir, 'named.sandbox/index.html'),
         outputDir: config.outDir,
         options: {},
+        skipped: false,
       },
     ],
 
@@ -346,6 +363,7 @@ describe('findEntrypoints', () => {
         inputPath: resolve(config.entrypointsDir, 'bookmarks.html'),
         outputDir: config.outDir,
         options: {},
+        skipped: false,
       },
     ],
     [
@@ -356,6 +374,7 @@ describe('findEntrypoints', () => {
         inputPath: resolve(config.entrypointsDir, 'bookmarks/index.html'),
         outputDir: config.outDir,
         options: {},
+        skipped: false,
       },
     ],
 
@@ -368,6 +387,7 @@ describe('findEntrypoints', () => {
         inputPath: resolve(config.entrypointsDir, 'history.html'),
         outputDir: config.outDir,
         options: {},
+        skipped: false,
       },
     ],
     [
@@ -378,6 +398,7 @@ describe('findEntrypoints', () => {
         inputPath: resolve(config.entrypointsDir, 'history/index.html'),
         outputDir: config.outDir,
         options: {},
+        skipped: false,
       },
     ],
 
@@ -390,6 +411,7 @@ describe('findEntrypoints', () => {
         inputPath: resolve(config.entrypointsDir, 'newtab.html'),
         outputDir: config.outDir,
         options: {},
+        skipped: false,
       },
     ],
     [
@@ -400,6 +422,7 @@ describe('findEntrypoints', () => {
         inputPath: resolve(config.entrypointsDir, 'newtab/index.html'),
         outputDir: config.outDir,
         options: {},
+        skipped: false,
       },
     ],
 
@@ -412,6 +435,7 @@ describe('findEntrypoints', () => {
         inputPath: resolve(config.entrypointsDir, 'sidepanel.html'),
         outputDir: config.outDir,
         options: {},
+        skipped: false,
       },
     ],
     [
@@ -422,6 +446,7 @@ describe('findEntrypoints', () => {
         inputPath: resolve(config.entrypointsDir, 'sidepanel/index.html'),
         outputDir: config.outDir,
         options: {},
+        skipped: false,
       },
     ],
     [
@@ -432,6 +457,7 @@ describe('findEntrypoints', () => {
         inputPath: resolve(config.entrypointsDir, 'named.sidepanel.html'),
         outputDir: config.outDir,
         options: {},
+        skipped: false,
       },
     ],
     [
@@ -442,6 +468,7 @@ describe('findEntrypoints', () => {
         inputPath: resolve(config.entrypointsDir, 'named.sidepanel/index.html'),
         outputDir: config.outDir,
         options: {},
+        skipped: false,
       },
     ],
 
@@ -454,6 +481,7 @@ describe('findEntrypoints', () => {
         inputPath: resolve(config.entrypointsDir, 'devtools.html'),
         outputDir: config.outDir,
         options: {},
+        skipped: false,
       },
     ],
     [
@@ -464,6 +492,7 @@ describe('findEntrypoints', () => {
         inputPath: resolve(config.entrypointsDir, 'devtools/index.html'),
         outputDir: config.outDir,
         options: {},
+        skipped: false,
       },
     ],
 
@@ -476,6 +505,7 @@ describe('findEntrypoints', () => {
         inputPath: resolve(config.entrypointsDir, 'onboarding.html'),
         outputDir: config.outDir,
         options: {},
+        skipped: false,
       },
     ],
     [
@@ -486,6 +516,7 @@ describe('findEntrypoints', () => {
         inputPath: resolve(config.entrypointsDir, 'onboarding/index.html'),
         outputDir: config.outDir,
         options: {},
+        skipped: false,
       },
     ],
 
@@ -498,6 +529,7 @@ describe('findEntrypoints', () => {
         inputPath: resolve(config.entrypointsDir, 'iframe.scss'),
         outputDir: config.outDir,
         options: {},
+        skipped: false,
       },
     ],
     [
@@ -508,6 +540,7 @@ describe('findEntrypoints', () => {
         inputPath: resolve(config.entrypointsDir, 'iframe.css'),
         outputDir: config.outDir,
         options: {},
+        skipped: false,
       },
     ],
 
@@ -520,6 +553,7 @@ describe('findEntrypoints', () => {
         inputPath: resolve(config.entrypointsDir, 'content.css'),
         outputDir: resolve(config.outDir, 'content-scripts'),
         options: {},
+        skipped: false,
       },
     ],
     [
@@ -530,6 +564,7 @@ describe('findEntrypoints', () => {
         inputPath: resolve(config.entrypointsDir, 'overlay.content.css'),
         outputDir: resolve(config.outDir, 'content-scripts'),
         options: {},
+        skipped: false,
       },
     ],
     [
@@ -540,6 +575,7 @@ describe('findEntrypoints', () => {
         inputPath: resolve(config.entrypointsDir, 'content/index.css'),
         outputDir: resolve(config.outDir, 'content-scripts'),
         options: {},
+        skipped: false,
       },
     ],
     [
@@ -550,6 +586,7 @@ describe('findEntrypoints', () => {
         inputPath: resolve(config.entrypointsDir, 'overlay.content/index.css'),
         outputDir: resolve(config.outDir, 'content-scripts'),
         options: {},
+        skipped: false,
       },
     ],
   ])('should find entrypoint for %s', async (path, expected) => {
@@ -737,4 +774,29 @@ describe('findEntrypoints', () => {
       expect(entrypoints).toEqual([]);
     });
   });
+
+  describe('filterEntrypoints option', () => {
+    it('should control entrypoints accessible', async () => {
+      globMock.mockResolvedValue([
+        'options/index.html',
+        'popup/index.html',
+        'ui.content/index.ts',
+        'injected.content/index.ts',
+      ]);
+      importEntrypointFileMock.mockResolvedValue({});
+      const filterEntrypoints = ['popup', 'ui'];
+      const config = fakeInternalConfig({
+        root: '/',
+        entrypointsDir: resolve('/src/entrypoints'),
+        outDir: resolve('.output'),
+        command: 'build',
+        filterEntrypoints: new Set(filterEntrypoints),
+      });
+
+      const entrypoints = await findEntrypoints(config);
+      const names = entrypoints.map((item) => item.name);
+      expect(names).toHaveLength(2);
+      expect(names).toEqual(filterEntrypoints);
+    });
+  });
 });

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

@@ -8,6 +8,7 @@ const background: Entrypoint = {
   inputPath: '/background.ts',
   outputDir: '/.output/background',
   options: {},
+  skipped: false,
 };
 const contentScript: Entrypoint = {
   type: 'content-script',
@@ -17,6 +18,7 @@ const contentScript: Entrypoint = {
   options: {
     matches: ['<all_urls>'],
   },
+  skipped: false,
 };
 const unlistedScript: Entrypoint = {
   type: 'unlisted-script',
@@ -24,6 +26,7 @@ const unlistedScript: Entrypoint = {
   inputPath: '/injected.ts',
   outputDir: '/.output/injected',
   options: {},
+  skipped: false,
 };
 const popup: Entrypoint = {
   type: 'popup',
@@ -31,6 +34,7 @@ const popup: Entrypoint = {
   inputPath: '/popup.html',
   outputDir: '/.output/popup',
   options: {},
+  skipped: false,
 };
 const unlistedPage: Entrypoint = {
   type: 'unlisted-page',
@@ -38,6 +42,7 @@ const unlistedPage: Entrypoint = {
   inputPath: '/onboarding.html',
   outputDir: '/.output/onboarding',
   options: {},
+  skipped: false,
 };
 const options: Entrypoint = {
   type: 'options',
@@ -45,6 +50,7 @@ const options: Entrypoint = {
   inputPath: '/options.html',
   outputDir: '/.output/options',
   options: {},
+  skipped: false,
 };
 const sandbox1: Entrypoint = {
   type: 'sandbox',
@@ -52,6 +58,7 @@ const sandbox1: Entrypoint = {
   inputPath: '/sandbox1.html',
   outputDir: '/.output/sandbox1',
   options: {},
+  skipped: false,
 };
 const sandbox2: Entrypoint = {
   type: 'sandbox',
@@ -59,6 +66,7 @@ const sandbox2: Entrypoint = {
   inputPath: '/sandbox2.html',
   outputDir: '/.output/sandbox2',
   options: {},
+  skipped: false,
 };
 const unlistedStyle: Entrypoint = {
   type: 'unlisted-style',
@@ -66,6 +74,7 @@ const unlistedStyle: Entrypoint = {
   inputPath: '/injected.scss',
   outputDir: '/.output',
   options: {},
+  skipped: false,
 };
 const contentScriptStyle: Entrypoint = {
   type: 'content-script-style',
@@ -73,6 +82,7 @@ const contentScriptStyle: Entrypoint = {
   inputPath: '/overlay.content.scss',
   outputDir: '/.output/content-scripts',
   options: {},
+  skipped: false,
 };
 
 describe('groupEntrypoints', () => {

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

@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest';
 import { importEntrypointFile } from '~/core/utils/building';
 import { fakeInternalConfig } from '~/core/utils/testing/fake-objects';
 import { resolve } from 'node:path';
+import { unnormalizePath } from '../../paths';
 
 const entrypointPath = (filename: string) =>
   resolve('src/core/utils/__tests__/test-entrypoints', filename);
@@ -38,4 +39,15 @@ describe('importEntrypointFile', () => {
 
     expect(actual).toBeUndefined();
   });
+
+  it('should throw a custom error message when an imported variable is used before main', async () => {
+    const filePath = unnormalizePath(
+      '../src/core/utils/__tests__/test-entrypoints/imported-option.ts',
+    );
+    await expect(() =>
+      importEntrypointFile(entrypointPath('imported-option.ts'), config),
+    ).rejects.toThrowErrorMatchingInlineSnapshot(
+      `[Error: ${filePath}: Cannot use imported variable "faker" outside the main function. See https://wxt.dev/guide/entrypoints.html#side-effects]`,
+    );
+  });
 });

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

@@ -18,12 +18,15 @@ export async function buildEntrypoints(
   const steps: BuildStepOutput[] = [];
   for (let i = 0; i < groups.length; i++) {
     const group = groups[i];
-    const groupNames = [group]
-      .flat()
-      .map((e) => e.name)
-      .join(pc.dim(', '));
-    spinner.text = pc.dim(`[${i + 1}/${groups.length}]`) + ` ${groupNames}`;
-    steps.push(await config.builder.build(group));
+    const groupNames = [group].flat().map((e) => e.name);
+    const groupNameColored = groupNames.join(pc.dim(', '));
+    spinner.text =
+      pc.dim(`[${i + 1}/${groups.length}]`) + ` ${groupNameColored}`;
+    try {
+      steps.push(await config.builder.build(group));
+    } catch (err) {
+      throw Error(`Failed to build ${groupNames.join(', ')}`, { cause: err });
+    }
   }
   const publicAssets = await copyPublicDirectory(config);
 

src/core/utils/building/detect-dev-changes.ts

@@ -2,10 +2,11 @@ import {
   BuildOutput,
   BuildStepOutput,
   EntrypointGroup,
+  InternalConfig,
   OutputAsset,
   OutputFile,
 } from '~/types';
-import { every } from '~/core/utils/arrays';
+import { every, some } from '~/core/utils/arrays';
 import { normalizePath } from '~/core/utils/paths';
 
 /**
@@ -29,10 +30,21 @@ import { normalizePath } from '~/core/utils/paths';
  *   - Config file changed (wxt.config.ts, .env, web-ext.config.ts, etc)
  */
 export function detectDevChanges(
-  changedFiles: [event: string, path: string][],
-  currentOutput: BuildOutput | undefined,
+  config: InternalConfig,
+  changedFiles: string[],
+  currentOutput: BuildOutput,
 ): DevModeChange {
-  if (currentOutput == null) return { type: 'no-change' };
+  const isConfigChange = some(
+    changedFiles,
+    (file) => file === config.userConfigMetadata.configFile,
+  );
+  if (isConfigChange) return { type: 'full-restart' };
+
+  const isRunnerChange = some(
+    changedFiles,
+    (file) => file === config.runnerConfig.configFile,
+  );
+  if (isRunnerChange) return { type: 'browser-restart' };
 
   const changedSteps = new Set(
     changedFiles.flatMap((changedFile) =>
@@ -69,7 +81,7 @@ export function detectDevChanges(
 
   const isOnlyHtmlChanges =
     changedFiles.length > 0 &&
-    every(changedFiles, ([_, file]) => file.endsWith('.html'));
+    every(changedFiles, (file) => file.endsWith('.html'));
   if (isOnlyHtmlChanges) {
     return {
       type: 'html-reload',
@@ -104,11 +116,11 @@ export function detectDevChanges(
  * For a single change, return all the step of the build output that were effected by it.
  */
 function findEffectedSteps(
-  changedFile: [event: string, path: string],
+  changedFile: string,
   currentOutput: BuildOutput,
 ): DetectedChange[] {
   const changes: DetectedChange[] = [];
-  const changedPath = normalizePath(changedFile[1]);
+  const changedPath = normalizePath(changedFile);
 
   const isChunkEffected = (chunk: OutputFile): boolean =>
     // If it's an HTML file with the same path, is is effected because HTML files need to be pre-rendered
@@ -139,8 +151,9 @@ export type DevModeChange =
   | NoChange
   | HtmlReload
   | ExtensionReload
-  | ContentScriptReload;
-// | BrowserRestart
+  | ContentScriptReload
+  | FullRestart
+  | BrowserRestart;
 
 interface NoChange {
   type: 'no-change';
@@ -157,6 +170,14 @@ interface RebuildChange {
   cachedOutput: BuildOutput;
 }
 
+interface FullRestart {
+  type: 'full-restart';
+}
+
+interface BrowserRestart {
+  type: 'browser-restart';
+}
+
 interface HtmlReload extends RebuildChange {
   type: 'html-reload';
 }

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

@@ -24,6 +24,7 @@ import {
 } from '~/core/utils/entrypoints';
 import { VIRTUAL_NOOP_BACKGROUND_MODULE_ID } from '~/core/utils/constants';
 import { CSS_EXTENSIONS_PATTERN } from '~/core/utils/paths';
+import pc from 'picocolors';
 
 /**
  * Return entrypoints and their configuration by looking through the project's files.
@@ -48,7 +49,14 @@ export async function findEntrypoints(
     );
     if (matchingGlob) {
       const type = PATH_GLOB_TO_TYPE_MAP[matchingGlob];
-      results.push({ name, inputPath, type });
+      results.push({
+        name,
+        inputPath,
+        type,
+        skipped:
+          config.filterEntrypoints != null &&
+          !config.filterEntrypoints.has(name),
+      });
     }
     return results;
   }, []);
@@ -106,11 +114,22 @@ export async function findEntrypoints(
         inputPath: VIRTUAL_NOOP_BACKGROUND_MODULE_ID,
         name: 'background',
         type: 'background',
+        skipped: false,
       }),
     );
   }
 
   config.logger.debug('All entrypoints:', entrypoints);
+  const skippedEntrypointNames = entrypointInfos
+    .filter((item) => item.skipped)
+    .map((item) => item.name);
+  if (skippedEntrypointNames.length) {
+    config.logger.warn(
+      `Filter excluded the following entrypoints:\n${skippedEntrypointNames
+        .map((item) => `${pc.dim('-')} ${pc.cyan(item)}`)
+        .join('\n')}`,
+    );
+  }
   const targetEntrypoints = entrypoints.filter((entry) => {
     const { include, exclude } = entry.options;
     if (include?.length && exclude?.length) {
@@ -125,6 +144,9 @@ export async function findEntrypoints(
     if (include?.length && !exclude?.length) {
       return include.includes(config.browser);
     }
+    if (skippedEntrypointNames.includes(entry.name)) {
+      return false;
+    }
 
     return true;
   });
@@ -136,6 +158,10 @@ interface EntrypointInfo {
   name: string;
   inputPath: string;
   type: Entrypoint['type'];
+  /**
+   * @default false
+   */
+  skipped: boolean;
 }
 
 function preventDuplicateEntrypointNames(
@@ -202,7 +228,7 @@ function getHtmlBaseOptions(document: Document): BaseEntrypointOptions {
  */
 async function getPopupEntrypoint(
   config: InternalConfig,
-  { inputPath, name }: EntrypointInfo,
+  { inputPath, name, skipped }: EntrypointInfo,
 ): Promise<PopupEntrypoint> {
   const content = await fs.readFile(inputPath, 'utf-8');
   const { document } = parseHTML(content);
@@ -247,6 +273,7 @@ async function getPopupEntrypoint(
     options,
     inputPath,
     outputDir: config.outDir,
+    skipped,
   };
 }
 
@@ -256,7 +283,7 @@ async function getPopupEntrypoint(
  */
 async function getOptionsEntrypoint(
   config: InternalConfig,
-  { inputPath, name }: EntrypointInfo,
+  { inputPath, name, skipped }: EntrypointInfo,
 ): Promise<OptionsEntrypoint> {
   const content = await fs.readFile(inputPath, 'utf-8');
   const { document } = parseHTML(content);
@@ -290,6 +317,7 @@ async function getOptionsEntrypoint(
     options,
     inputPath,
     outputDir: config.outDir,
+    skipped,
   };
 }
 
@@ -299,7 +327,7 @@ async function getOptionsEntrypoint(
  */
 async function getUnlistedPageEntrypoint(
   config: InternalConfig,
-  { inputPath, name }: EntrypointInfo,
+  { inputPath, name, skipped }: EntrypointInfo,
 ): Promise<GenericEntrypoint> {
   const content = await fs.readFile(inputPath, 'utf-8');
   const { document } = parseHTML(content);
@@ -310,6 +338,7 @@ async function getUnlistedPageEntrypoint(
     inputPath,
     outputDir: config.outDir,
     options: getHtmlBaseOptions(document),
+    skipped,
   };
 }
 
@@ -319,7 +348,7 @@ async function getUnlistedPageEntrypoint(
  */
 async function getUnlistedScriptEntrypoint(
   config: InternalConfig,
-  { inputPath, name }: EntrypointInfo,
+  { inputPath, name, skipped }: EntrypointInfo,
 ): Promise<GenericEntrypoint> {
   const defaultExport = await importEntrypointFile<UnlistedScriptDefinition>(
     inputPath,
@@ -338,6 +367,7 @@ async function getUnlistedScriptEntrypoint(
     inputPath,
     outputDir: config.outDir,
     options,
+    skipped,
   };
 }
 
@@ -346,7 +376,7 @@ async function getUnlistedScriptEntrypoint(
  */
 async function getBackgroundEntrypoint(
   config: InternalConfig,
-  { inputPath, name }: EntrypointInfo,
+  { inputPath, name, skipped }: EntrypointInfo,
 ): Promise<BackgroundEntrypoint> {
   let options: Omit<BackgroundDefinition, 'main'> = {};
   if (inputPath !== VIRTUAL_NOOP_BACKGROUND_MODULE_ID) {
@@ -372,6 +402,7 @@ async function getBackgroundEntrypoint(
       type: resolvePerBrowserOption(options.type, config.browser),
       persistent: resolvePerBrowserOption(options.persistent, config.browser),
     },
+    skipped,
   };
 }
 
@@ -380,7 +411,7 @@ async function getBackgroundEntrypoint(
  */
 async function getContentScriptEntrypoint(
   config: InternalConfig,
-  { inputPath, name }: EntrypointInfo,
+  { inputPath, name, skipped }: EntrypointInfo,
 ): Promise<ContentScriptEntrypoint> {
   const { main: _, ...options } =
     await importEntrypointFile<ContentScriptDefinition>(inputPath, config);
@@ -395,6 +426,7 @@ async function getContentScriptEntrypoint(
     inputPath,
     outputDir: resolve(config.outDir, CONTENT_SCRIPT_OUT_DIR),
     options,
+    skipped,
   };
 }
 

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

@@ -79,8 +79,10 @@ import "wxt/browser";
 declare module "wxt/browser" {
   export type PublicPath =
 {{ union }}
+  type HtmlPublicPath = Extract<PublicPath, \`\${string}.html\`>
   export interface WxtRuntime extends Runtime.Static {
     getURL(path: PublicPath): string;
+    getURL(path: \`\${HtmlPublicPath}\${string}\`): string;
   }
 }
 `;

src/core/utils/building/get-internal-config.ts

@@ -12,7 +12,7 @@ import {
 import path from 'node:path';
 import { createFsCache } from '~/core/utils/cache';
 import consola, { LogLevels } from 'consola';
-import { craeteViteBuilder } from '~/core/builders/vite';
+import { createViteBuilder } from '~/core/builders/vite';
 import defu from 'defu';
 import { NullablyRequired } from '../types';
 
@@ -72,10 +72,14 @@ export async function getInternalConfig(
     srcDir,
     mergedConfig.entrypointsDir ?? 'entrypoints',
   );
+  const filterEntrypoints = !!mergedConfig.filterEntrypoints?.length
+    ? new Set(mergedConfig.filterEntrypoints)
+    : undefined;
   const publicDir = path.resolve(srcDir, mergedConfig.publicDir ?? 'public');
   const typesDir = path.resolve(wxtDir, 'types');
   const outBaseDir = path.resolve(root, mergedConfig.outDir ?? '.output');
   const outDir = path.resolve(outBaseDir, `${browser}-mv${manifestVersion}`);
+  const reloadCommand = mergedConfig.dev?.reloadCommand ?? 'Alt+R';
 
   const runnerConfig = await loadConfig<ExtensionRunnerConfig>({
     name: 'web-ext',
@@ -101,6 +105,7 @@ export async function getInternalConfig(
     command,
     debug,
     entrypointsDir,
+    filterEntrypoints,
     env,
     fsCache: createFsCache(wxtDir),
     imports: mergedConfig.imports ?? {},
@@ -132,9 +137,12 @@ export async function getInternalConfig(
         mergedConfig.experimental?.includeBrowserPolyfill ?? true,
     },
     server,
+    dev: {
+      reloadCommand,
+    },
   };
 
-  const builder = await craeteViteBuilder(
+  const builder = await createViteBuilder(
     inlineConfig,
     userConfig,
     finalConfig,
@@ -191,6 +199,8 @@ function mergeInlineConfig(
     configFile: inlineConfig.configFile,
     debug: inlineConfig.debug ?? userConfig.debug,
     entrypointsDir: inlineConfig.entrypointsDir ?? userConfig.entrypointsDir,
+    filterEntrypoints:
+      inlineConfig.filterEntrypoints ?? userConfig.filterEntrypoints,
     imports,
     logger: inlineConfig.logger ?? userConfig.logger,
     manifest,
@@ -215,6 +225,10 @@ function mergeInlineConfig(
     },
     vite: undefined,
     transformManifest: undefined,
+    dev: {
+      ...userConfig.dev,
+      ...inlineConfig.dev,
+    },
   };
 }
 

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

@@ -2,7 +2,7 @@ import createJITI, { TransformOptions as JitiTransformOptions } from 'jiti';
 import { InternalConfig } from '~/types';
 import { createUnimport } from 'unimport';
 import fs from 'fs-extra';
-import { resolve } from 'node:path';
+import { relative, resolve } from 'node:path';
 import { getUnimportOptions } from '~/core/utils/unimport';
 import { removeProjectImportStatements } from '~/core/utils/strings';
 import { normalizePath } from '~/core/utils/paths';
@@ -89,8 +89,17 @@ export async function importEntrypointFile<T>(
     const res = await jiti(path);
     return res.default;
   } catch (err) {
-    config.logger.error(err);
-    throw err;
+    const filePath = relative(config.root, path);
+    if (err instanceof ReferenceError) {
+      // "XXX is not defined" - usually due to WXT removing imports
+      const variableName = err.message.replace(' is not defined', '');
+      throw Error(
+        `${filePath}: Cannot use imported variable "${variableName}" outside the main function. See https://wxt.dev/guide/entrypoints.html#side-effects`,
+        { cause: err },
+      );
+    } else {
+      throw Error(`Failed to load entrypoint: ${filePath}`, { cause: err });
+    }
   }
 }
 

src/core/utils/building/internal-build.ts

@@ -1,5 +1,5 @@
 import { findEntrypoints } from './find-entrypoints';
-import { InternalConfig, BuildOutput } from '~/types';
+import { InternalConfig, BuildOutput, Entrypoint } from '~/types';
 import pc from 'picocolors';
 import fs from 'fs-extra';
 import { groupEntrypoints } from './group-entrypoints';
@@ -8,6 +8,15 @@ import { printBuildSummary } from '~/core/utils/log';
 import glob from 'fast-glob';
 import { unnormalizePath } from '~/core/utils/paths';
 import { rebuild } from './rebuild';
+import managePath from 'manage-path';
+import { resolve, relative } from 'node:path';
+import {
+  ValidationError,
+  ValidationResult,
+  ValidationResults,
+  validateEntrypoints,
+} from '../validation';
+import consola from 'consola';
 
 /**
  * Builds the extension based on an internal config. No more config discovery is performed, the
@@ -37,8 +46,24 @@ export async function internalBuild(
 
   const entrypoints = await findEntrypoints(config);
   config.logger.debug('Detected entrypoints:', entrypoints);
+
+  const validationResults = validateEntrypoints(entrypoints);
+  if (validationResults.errorCount + validationResults.warningCount > 0) {
+    printValidationResults(config, validationResults);
+  }
+  if (validationResults.errorCount > 0) {
+    throw new ValidationError(`Entrypoint validation failed`, {
+      cause: validationResults,
+    });
+  }
+
   const groups = groupEntrypoints(entrypoints);
-  const { output } = await rebuild(config, groups, undefined);
+  const { output, warnings } = await rebuild(
+    config,
+    entrypoints,
+    groups,
+    undefined,
+  );
 
   // Post-build
   await printBuildSummary(
@@ -48,6 +73,10 @@ export async function internalBuild(
     config,
   );
 
+  for (const warning of warnings) {
+    config.logger.warn(...warning);
+  }
+
   if (config.analysis.enabled) {
     await combineAnalysisStats(config);
     config.logger.info(
@@ -66,6 +95,10 @@ async function combineAnalysisStats(config: InternalConfig): Promise<void> {
   });
   const absolutePaths = unixFiles.map(unnormalizePath);
 
+  const alterPath = managePath(process.env);
+  // Add subdependency path for PNPM shamefully-hoist=false
+  alterPath.push(resolve(config.root, 'node_modules/wxt/node_modules/.bin'));
+
   await execaCommand(
     `rollup-plugin-visualizer ${absolutePaths.join(' ')} --template ${
       config.analysis.template
@@ -73,3 +106,33 @@ async function combineAnalysisStats(config: InternalConfig): Promise<void> {
     { cwd: config.root, stdio: 'inherit' },
   );
 }
+
+function printValidationResults(
+  config: InternalConfig,
+  { errorCount, errors, warningCount }: ValidationResults,
+) {
+  (errorCount > 0 ? config.logger.error : config.logger.warn)(
+    `Entrypoint validation failed: ${errorCount} error${
+      errorCount === 1 ? '' : 's'
+    }, ${warningCount} warning${warningCount === 1 ? '' : 's'}`,
+  );
+
+  const cwd = process.cwd();
+  const entrypointErrors = errors.reduce((map, error) => {
+    const entryErrors = map.get(error.entrypoint) ?? [];
+    entryErrors.push(error);
+    map.set(error.entrypoint, entryErrors);
+    return map;
+  }, new Map<Entrypoint, ValidationResult[]>());
+
+  Array.from(entrypointErrors.entries()).forEach(([entrypoint, errors]) => {
+    consola.log(relative(cwd, entrypoint.inputPath));
+    console.log();
+    errors.forEach((err) => {
+      const type = err.type === 'error' ? pc.red('ERROR') : pc.yellow('WARN');
+      const recieved = pc.dim(`(recieved: ${JSON.stringify(err.value)})`);
+      consola.log(`  - ${type} ${err.message} ${recieved}`);
+    });
+    console.log();
+  });
+}

src/core/utils/building/rebuild.ts

@@ -1,6 +1,10 @@
 import type { Manifest } from '~/browser';
-import { BuildOutput, EntrypointGroup, InternalConfig } from '~/types';
-import { findEntrypoints } from './find-entrypoints';
+import {
+  BuildOutput,
+  Entrypoint,
+  EntrypointGroup,
+  InternalConfig,
+} from '~/types';
 import { generateTypesDir } from './generate-wxt-dir';
 import { buildEntrypoints } from './build-entrypoints';
 import { generateManifest, writeManifest } from '~/core/utils/manifest';
@@ -14,20 +18,30 @@ import { generateManifest, writeManifest } from '~/core/utils/manifest';
  * 2. Build the `entrypointGroups` (and copies public files)
  * 3. Generate the latest manifest for all entrypoints
  * 4. Write the new manifest to the file system
+ *
+ * @param config Internal config containing all the project information.
+ * @param allEntrypoints List of entrypoints used to generate the types inside .wxt directory.
+ * @param entrypointGroups The list of entrypoint groups to build.
+ * @param existingOutput The previous output to combine the rebuild results into. An emptry array if
+ *                       this is the first build.
  */
 export async function rebuild(
   config: InternalConfig,
+  allEntrypoints: Entrypoint[],
   entrypointGroups: EntrypointGroup[],
   existingOutput: Omit<BuildOutput, 'manifest'> = {
     steps: [],
     publicAssets: [],
   },
-): Promise<{ output: BuildOutput; manifest: Manifest.WebExtensionManifest }> {
+): Promise<{
+  output: BuildOutput;
+  manifest: Manifest.WebExtensionManifest;
+  warnings: any[][];
+}> {
   const { default: ora } = await import('ora');
   const spinner = ora(`Preparing...`).start();
 
   // Update types directory with new files and types
-  const allEntrypoints = await findEntrypoints(config);
   await generateTypesDir(allEntrypoints, config).catch((err) => {
     config.logger.warn('Failed to update .wxt directory:', err);
     // Throw the error if doing a regular build, don't for dev mode.
@@ -41,11 +55,8 @@ export async function rebuild(
     publicAssets: [...existingOutput.publicAssets, ...newOutput.publicAssets],
   };
 
-  const newManifest = await generateManifest(
-    allEntrypoints,
-    mergedOutput,
-    config,
-  );
+  const { manifest: newManifest, warnings: manifestWarnings } =
+    await generateManifest(allEntrypoints, mergedOutput, config);
   const finalOutput: BuildOutput = {
     manifest: newManifest,
     ...newOutput,
@@ -67,5 +78,6 @@ export async function rebuild(
       ],
     },
     manifest: newManifest,
+    warnings: manifestWarnings,
   };
 }

src/core/utils/manifest.ts

@@ -54,7 +54,8 @@ export async function generateManifest(
   entrypoints: Entrypoint[],
   buildOutput: Omit<BuildOutput, 'manifest'>,
   config: InternalConfig,
-): Promise<Manifest.WebExtensionManifest> {
+): Promise<{ manifest: Manifest.WebExtensionManifest; warnings: any[][] }> {
+  const warnings: any[][] = [];
   const pkg = await getPackageJson(config);
 
   let versionName =
@@ -75,16 +76,6 @@ export async function generateManifest(
     short_name: pkg?.shortName,
     icons: discoverIcons(buildOutput),
   };
-  if (config.command === 'serve') {
-    baseManifest.commands = {
-      'wxt:reload-extension': {
-        description: 'Reload the extension during development',
-        suggested_key: {
-          default: 'Ctrl+E',
-        },
-      },
-    };
-  }
   const userManifest = config.manifest;
 
   const manifest = defu(
@@ -92,6 +83,23 @@ export async function generateManifest(
     baseManifest,
   ) as Manifest.WebExtensionManifest;
 
+  // Add reload command in dev mode
+  if (config.command === 'serve' && config.dev.reloadCommand) {
+    if (manifest.commands && Object.keys(manifest.commands).length >= 4) {
+      warnings.push([
+        "Extension already has 4 registered commands, WXT's reload command is disabled",
+      ]);
+    } else {
+      manifest.commands ??= {};
+      manifest.commands['wxt:reload-extension'] = {
+        description: 'Reload the extension during development',
+        suggested_key: {
+          default: config.dev.reloadCommand,
+        },
+      };
+    }
+  }
+
   // Apply the final version fields after merging the user manifest
   manifest.version = version;
   manifest.version_name =
@@ -117,7 +125,10 @@ export async function generateManifest(
     );
   }
 
-  return finalManifest;
+  return {
+    manifest: finalManifest,
+    warnings,
+  };
 }
 
 /**

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

@@ -4,7 +4,7 @@
 import { resolve } from 'path';
 import { faker } from '@faker-js/faker';
 import merge from 'lodash.merge';
-import type { Manifest } from '~/browser';
+import { Commands, type Manifest } from '~/browser';
 import {
   FsCache,
   InternalConfig,
@@ -59,7 +59,7 @@ export const fakeContentScriptEntrypoint =
     name: faker.string.alpha(),
     options: {
       matches: [],
-      matchAboutBlank: faker.helpers.arrayElement([true, false, undefined]),
+      matchAboutBlank: faker.datatype.boolean(),
       matchOriginAsFallback: faker.helpers.arrayElement([
         true,
         false,
@@ -73,6 +73,7 @@ export const fakeContentScriptEntrypoint =
       ]),
     },
     outputDir: fakeDir('.output'),
+    skipped: faker.datatype.boolean(),
   }));
 
 export const fakeBackgroundEntrypoint = fakeObjectCreator<BackgroundEntrypoint>(
@@ -81,10 +82,11 @@ export const fakeBackgroundEntrypoint = fakeObjectCreator<BackgroundEntrypoint>(
     inputPath: 'entrypoints/background.ts',
     name: 'background',
     options: {
-      persistent: faker.helpers.arrayElement([true, false, undefined]),
+      persistent: faker.datatype.boolean(),
       type: faker.helpers.maybe(() => 'module'),
     },
     outputDir: fakeDir('.output'),
+    skipped: faker.datatype.boolean(),
   }),
 );
 
@@ -95,6 +97,7 @@ export const fakeUnlistedScriptEntrypoint =
     name: faker.string.alpha(),
     outputDir: fakeDir('.output'),
     options: {},
+    skipped: faker.datatype.boolean(),
   }));
 
 export const fakeOptionsEntrypoint = fakeObjectCreator<OptionsEntrypoint>(
@@ -104,10 +107,11 @@ export const fakeOptionsEntrypoint = fakeObjectCreator<OptionsEntrypoint>(
     name: 'options',
     outputDir: fakeDir('.output'),
     options: {
-      browserStyle: faker.helpers.arrayElement([true, false, undefined]),
-      chromeStyle: faker.helpers.arrayElement([true, false, undefined]),
-      openInTab: faker.helpers.arrayElement([true, false, undefined]),
+      browserStyle: faker.datatype.boolean(),
+      chromeStyle: faker.datatype.boolean(),
+      openInTab: faker.datatype.boolean(),
     },
+    skipped: faker.datatype.boolean(),
   }),
 );
 
@@ -134,6 +138,7 @@ export const fakePopupEntrypoint = fakeObjectCreator<PopupEntrypoint>(() => ({
       undefined,
     ]),
   },
+  skipped: faker.datatype.boolean(),
 }));
 
 export const fakeGenericEntrypoint = fakeObjectCreator<GenericEntrypoint>(
@@ -152,6 +157,7 @@ export const fakeGenericEntrypoint = fakeObjectCreator<GenericEntrypoint>(
     name: faker.string.alpha(),
     outputDir: fakeDir('.output'),
     options: {},
+    skipped: faker.datatype.boolean(),
   }),
 );
 
@@ -238,6 +244,9 @@ export const fakeInternalConfig = fakeObjectCreator<InternalConfig>(() => {
       includeBrowserPolyfill: true,
     },
     builder: mock(),
+    dev: {
+      reloadCommand: 'Alt+R',
+    },
   };
 });
 
@@ -251,3 +260,11 @@ export const fakeBuildStepOutput = fakeObjectCreator<BuildStepOutput>(() => ({
   chunks: fakeArray(fakeOutputChunk),
   entrypoints: fakeArray(fakeEntrypoint),
 }));
+
+export const fakeManifestCommand = fakeObjectCreator<Commands.Command>(() => ({
+  description: faker.string.sample(),
+  shortcut: `${faker.helpers.arrayElement(['ctrl', 'alt'])}+${faker.number.int({
+    min: 0,
+    max: 9,
+  })}`,
+}));

src/core/utils/validation.ts

@@ -0,0 +1,86 @@
+import { ContentScriptEntrypoint, Entrypoint } from '~/types';
+
+export function validateEntrypoints(
+  entrypoints: Entrypoint[],
+): ValidationResults {
+  const errors = entrypoints.flatMap((entrypoint) => {
+    switch (entrypoint.type) {
+      case 'content-script':
+        return validateContentScriptEntrypoint(entrypoint);
+      default:
+        return validateBaseEntrypoint(entrypoint);
+    }
+  });
+
+  let errorCount = 0;
+  let warningCount = 0;
+  for (const err of errors) {
+    if (err.type === 'warning') warningCount++;
+    else errorCount++;
+  }
+
+  return {
+    errors,
+    errorCount,
+    warningCount,
+  };
+}
+
+function validateContentScriptEntrypoint(
+  definition: ContentScriptEntrypoint,
+): ValidationResult[] {
+  const errors = validateBaseEntrypoint(definition);
+  if (definition.options.matches == null) {
+    errors.push({
+      type: 'error',
+      message: '`matches` is required',
+      value: definition.options.matches,
+      entrypoint: definition,
+    });
+  }
+  return errors;
+}
+
+function validateBaseEntrypoint(definition: Entrypoint): ValidationResult[] {
+  const errors: ValidationResult[] = [];
+
+  if (
+    definition.options.exclude != null &&
+    !Array.isArray(definition.options.exclude)
+  ) {
+    errors.push({
+      type: 'error',
+      message: '`exclude` must be an array of browser names',
+      value: definition.options.exclude,
+      entrypoint: definition,
+    });
+  }
+  if (
+    definition.options.include != null &&
+    !Array.isArray(definition.options.include)
+  ) {
+    errors.push({
+      type: 'error',
+      message: '`include` must be an array of browser names',
+      value: definition.options.include,
+      entrypoint: definition,
+    });
+  }
+
+  return errors;
+}
+
+export interface ValidationResult {
+  type: 'warning' | 'error';
+  message: string;
+  entrypoint: Entrypoint;
+  value: any;
+}
+
+export interface ValidationResults {
+  errors: ValidationResult[];
+  errorCount: number;
+  warningCount: number;
+}
+
+export class ValidationError extends Error {}

src/storage.ts

@@ -308,10 +308,20 @@ function createDriver(
   storageArea: 'local' | 'session' | 'sync' | 'managed',
 ): WxtStorageDriver {
   const getStorageArea = () => {
-    if (browser.storage == null)
+    if (browser.runtime == null) {
+      throw Error(
+        [
+          "'wxt/storage' must be loaded in a web extension environment",
+          '\n - If thrown during a build, see https://github.com/wxt-dev/wxt/issues/371',
+          " - If thrown during tests, mock 'wxt/browser' correctly. See https://wxt.dev/guide/testing.html\n",
+        ].join('\n'),
+      );
+    }
+    if (browser.storage == null) {
       throw Error(
         "You must add the 'storage' permission to your manifest to use 'wxt/storage'",
       );
+    }
 
     return browser.storage[storageArea];
   };

src/types/external.ts

@@ -31,6 +31,12 @@ export interface InlineConfig {
    * @default "${config.srcDir}/entrypoints"
    */
   entrypointsDir?: string;
+  /**
+   * A list of entrypoint names (`"popup"`, `"options"`, etc.) to build. Will speed up the build if
+   * your extension has lots of entrypoints, and you don't need to build all of them to develop a
+   * feature.
+   */
+  filterEntrypoints?: string[];
   /**
    * Output directory that stored build folders and ZIPs.
    *
@@ -223,6 +229,24 @@ export interface InlineConfig {
      */
     includeBrowserPolyfill?: boolean;
   };
+  /**
+   * Config effecting dev mode only.
+   */
+  dev?: {
+    /**
+     * Controls whether a custom keyboard shortcut command, `Alt+R`, is added during dev mode to
+     * quickly reload the extension.
+     *
+     * If false, the shortcut is not added during development.
+     *
+     * If set to a custom string, you can override the key combo used. See
+     * [Chrome's command docs](https://developer.chrome.com/docs/extensions/reference/api/commands)
+     * for available options.
+     *
+     * @default "Alt+R"
+     */
+    reloadCommand?: string | false;
+  };
 }
 
 // TODO: Extract to @wxt/vite-builder and use module augmentation to include the vite field
@@ -284,16 +308,24 @@ export interface BuildStepOutput {
 }
 
 export interface WxtDevServer
-  extends Omit<WxtBuilderServer, 'listen'>,
+  extends Omit<WxtBuilderServer, 'listen' | 'close'>,
     ServerInfo {
   /**
    * Stores the current build output of the server.
    */
-  currentOutput: BuildOutput;
+  currentOutput: BuildOutput | undefined;
   /**
    * Start the server.
    */
   start(): Promise<void>;
+  /**
+   * Stop the server.
+   */
+  stop(): Promise<void>;
+  /**
+   * Close the browser, stop the server, rebuild the entire extension, and start the server again.
+   */
+  restart(): Promise<void>;
   /**
    * Transform the HTML for dev mode.
    */
@@ -326,6 +358,10 @@ export interface WxtDevServer
   reloadContentScript: (
     contentScript: Omit<Scripting.RegisteredContentScript, 'id'>,
   ) => void;
+  /**
+   * Grab the latest runner config and restart the browser.
+   */
+  restartBrowser: () => void;
 }
 
 export type TargetBrowser = string;
@@ -377,6 +413,7 @@ export interface BaseEntrypoint {
    */
   outputDir: string;
   options: BaseEntrypointOptions;
+  skipped: boolean;
 }
 
 export interface GenericEntrypoint extends BaseEntrypoint {
@@ -667,6 +704,10 @@ export interface WxtBuilderServer {
    * Start the server.
    */
   listen(): Promise<void>;
+  /**
+   * Stop the server.
+   */
+  close(): Promise<void>;
   /**
    * Transform the HTML for dev mode.
    */

src/types/internal.ts

@@ -21,6 +21,7 @@ export interface InternalConfig {
   wxtDir: string;
   typesDir: string;
   entrypointsDir: string;
+  filterEntrypoints?: Set<string>;
   outBaseDir: string;
   outDir: string;
   debug: boolean;
@@ -56,6 +57,9 @@ export interface InternalConfig {
     includeBrowserPolyfill: boolean;
   };
   builder: WxtBuilder;
+  dev: {
+    reloadCommand: string | false;
+  };
 }
 
 export interface FsCache {

src/types/modules.d.ts

@@ -50,6 +50,10 @@ declare module 'web-ext-run/util/logger' {
   export const consoleStream: IConsoleStream;
 }
 
+declare module 'manage-path' {
+  export default function managePath(env: object): string[];
+}
+
 declare module 'wxt/browser' {
   // Overridden when types are generated per project
   export type PublicPath = string;

templates/react/package.json

@@ -23,6 +23,6 @@
     "@types/react-dom": "^18.2.18",
     "@vitejs/plugin-react": "^4.2.1",
     "typescript": "^5.3.3",
-    "wxt": "^0.13.0"
+    "wxt": "^0.14.0"
   }
 }

templates/solid/package.json

@@ -20,6 +20,6 @@
   "devDependencies": {
     "typescript": "^5.3.3",
     "vite-plugin-solid": "^2.8.0",
-    "wxt": "^0.13.0"
+    "wxt": "^0.14.0"
   }
 }

templates/svelte/package.json

@@ -20,6 +20,6 @@
     "svelte-check": "^3.6.2",
     "tslib": "^2.6.2",
     "typescript": "^5.3.3",
-    "wxt": "^0.13.0"
+    "wxt": "^0.14.0"
   }
 }

templates/vanilla/package.json

@@ -16,6 +16,6 @@
   },
   "devDependencies": {
     "typescript": "^5.3.3",
-    "wxt": "^0.13.0"
+    "wxt": "^0.14.0"
   }
 }

templates/vue/package.json

@@ -21,6 +21,6 @@
     "@vitejs/plugin-vue": "^5.0.1",
     "typescript": "^5.3.3",
     "vue-tsc": "^1.8.27",
-    "wxt": "^0.13.0"
+    "wxt": "^0.14.0"
   }
 }