chore(release): v0.8.7

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

.github/actions/setup/action.yml

@@ -0,0 +1,17 @@
+name: Basic Setup
+description: Install PNPM, Node, and dependencies
+runs:
+  using: composite
+  steps:
+    - name: Setup PNPM
+      uses: pnpm/action-setup@v2
+      with:
+        version: 8
+    - name: Setup NodeJS
+      uses: actions/setup-node@v4
+      with:
+        node-version: 18
+        cache: pnpm
+    - name: Install Dependencies
+      shell: bash
+      run: pnpm install

.github/workflows/release.yml

@@ -11,24 +11,11 @@ jobs:
     needs:
       - validate
     steps:
-      - name: Checkout
-        uses: actions/checkout@v3
+      - uses: actions/checkout@v3
         with:
           fetch-depth: 0
 
-      - name: Setup PNPM
-        uses: pnpm/action-setup@v2
-        with:
-          version: 8
-
-      - name: Setup NodeJS
-        uses: actions/setup-node@v3
-        with:
-          node-version: 18
-          cache: 'pnpm'
-
-      - name: Install dependencies
-        run: pnpm install
+      - uses: ./.github/actions/setup
 
       - name: Bump and Tag
         run: |

.github/workflows/validate.yml

@@ -7,141 +7,70 @@ on:
       - main
 
 jobs:
-  checks:
-    name: Checks
+  formatting:
     runs-on: ubuntu-22.04
     steps:
-      - name: Checkout
-        uses: actions/checkout@v3
-
-      - name: Setup PNPM
-        uses: pnpm/action-setup@v2
-        with:
-          version: 8
-
-      - name: Setup NodeJS
-        uses: actions/setup-node@v3
-        with:
-          node-version: 18
-          cache: 'pnpm'
-
-      - name: Install dependencies
-        run: pnpm install
-
-      - name: Formatting
-        run: pnpm format:check
-
-      - name: Type Check
-        run: pnpm compile
-
-      - name: Build Demo
-        run: |
-          pnpm build:all:chrome-mv2
-          pnpm build:all:chrome-mv3
-          pnpm build:all:firefox-mv2
-          pnpm build:all:firefox-mv3
-          pnpm tsc --noEmit
-          pnpm wxt zip
-          pnpm vitest run
+      - uses: actions/checkout@v3
+      - uses: ./.github/actions/setup
+      - run: pnpm format:check
+  type-check:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v3
+      - uses: ./.github/actions/setup
+      - run: pnpm compile
+  validate-demo:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v3
+      - uses: ./.github/actions/setup
+      - run: pnpm build:all
         working-directory: demo
-
-      - name: Tests
+      - run: pnpm tsc --noEmit
+        working-directory: demo
+      - run: pnpm wxt zip
+        working-directory: demo
+      - run: pnpm vitest run
+        working-directory: demo
+  tests:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v3
+      - uses: ./.github/actions/setup
+      - name: pnpm test:coverage
         run: pnpm test:coverage --reporter=default --reporter=hanging-process
-
-      - name: Upload coverage reports to Codecov
-        uses: codecov/codecov-action@v3
+      - uses: codecov/codecov-action@v3
         env:
           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
-
   windows-tests:
-    name: Windows Tests
     runs-on: windows-latest
     steps:
-      - name: Checkout
-        uses: actions/checkout@v3
-
-      - name: Setup PNPM
-        uses: pnpm/action-setup@v2
-        with:
-          version: 8
-
-      - name: Setup NodeJS
-        uses: actions/setup-node@v3
-        with:
-          node-version: 18
-          cache: 'pnpm'
-
-      - name: Install dependencies
-        run: pnpm install
-
-      - name: Tests
-        run: pnpm test:coverage --reporter=default --reporter=hanging-process
-
-  project-templates:
-    name: Project Templates
+      - uses: actions/checkout@v3
+      - uses: ./.github/actions/setup
+      - run: pnpm test run
+  template:
     runs-on: ubuntu-22.04
+    strategy:
+      matrix:
+        template:
+          - react
+          - solid
+          - svelte
+          - vanilla
+          - vue
     steps:
-      - name: Checkout
-        uses: actions/checkout@v3
-
-      - name: Setup PNPM
-        uses: pnpm/action-setup@v2
-        with:
-          version: 8
-
-      - name: Setup NodeJS
-        uses: actions/setup-node@v3
-        with:
-          node-version: 18
-          cache: 'pnpm'
-
-      - name: Install dependencies
-        run: pnpm install
-
-      - name: Build Local Tarball
-        run: pnpm pack
-
-      - name: Validate Vanilla
-        working-directory: templates/vanilla
-        run: |
-          npm i
-          npm i -D ../../wxt-*.tgz
-          npm ls vite
-          npm run build
-          npm run compile
-
-      - name: Validate Vue
-        working-directory: templates/vue
-        run: |
-          npm i
-          npm i -D ../../wxt-*.tgz
-          npm ls vite
-          npm run build
-          npm run compile
-
-      - name: Validate React
-        working-directory: templates/react
-        run: |
-          npm i
-          npm i -D ../../wxt-*.tgz
-          npm ls vite
-          npm run build
-          npm run compile
-
-      - name: Validate Svelte
-        working-directory: templates/svelte
-        run: |
-          npm i
-          npm i -D ../../wxt-*.tgz
-          npm ls vite
-          npm run build
-          npm run check
-
-      - name: Validate Solid
-        working-directory: templates/solid
-        run: |
-          npm i
-          npm i -D ../../wxt-*.tgz
-          npm ls vite
-          npm run build
-          npm run compile
+      - uses: actions/checkout@v3
+      - uses: ./.github/actions/setup
+      - run: pnpm pack
+      - run: npm i
+        working-directory: templates/${{ matrix.template }}
+      - run: npm i -D ../../wxt-*.tgz
+        working-directory: templates/${{ matrix.template }}
+      - run: npm run compile
+        if: matrix.template != 'svelte'
+        working-directory: templates/${{ matrix.template }}
+      - run: npm run check
+        if: matrix.template == 'svelte'
+        working-directory: templates/${{ matrix.template }}
+      - run: npm run build
+        working-directory: templates/${{ matrix.template }}

.prettierignore

@@ -5,12 +5,3 @@ dist
 docs/.vitepress/cache
 pnpm-lock.yaml
 CHANGELOG.md
-.gitattributes
-.gitignore
-.prettierignore
-*.png
-*.svg
-*.txt
-_gitignore
-_redirects
-*.svelte

CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## v0.8.7
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.8.6...v0.8.7)
+
+### 🚀 Enhancements
+
+- `createContentScriptIframe` utility ([#206](https://github.com/wxt-dev/wxt/pull/206))
+
+### 🏡 Chore
+
+- **deps-dev:** Bump happy-dom from 12.4.0 to 12.10.3 ([#194](https://github.com/wxt-dev/wxt/pull/194))
+- **deps-dev:** Bump tsx from 3.12.8 to 3.14.0 ([#198](https://github.com/wxt-dev/wxt/pull/198))
+- Upgrade types ([f3874da](https://github.com/wxt-dev/wxt/commit/f3874da))
+- **deps-dev:** Upgrade `lint-staged` to `^15.0.2` ([5f74a54](https://github.com/wxt-dev/wxt/commit/5f74a54))
+- **deps-dev:** Upgrade `execa` to `^8.0.1` ([#200](https://github.com/wxt-dev/wxt/pull/200))
+- **deps-dev:** Upgrade `typedoc` to `^0.25.3` ([#201](https://github.com/wxt-dev/wxt/pull/201))
+- **deps-dev:** Upgrade `vue` to `3.3.7` ([0b8d101](https://github.com/wxt-dev/wxt/commit/0b8d101))
+- **deps-dev:** Upgrade `vitepress` to `1.0.0-rc.24` ([5de18e5](https://github.com/wxt-dev/wxt/commit/5de18e5))
+- **deps-dev:** Update `@type/*` packages for demo ([cd4d00e](https://github.com/wxt-dev/wxt/commit/cd4d00e))
+- **deps-dev:** Update `sass` to `1.69.5` ([183bb02](https://github.com/wxt-dev/wxt/commit/183bb02))
+- Improve prettier git hook ([0f09cbe](https://github.com/wxt-dev/wxt/commit/0f09cbe))
+- Run E2E tests in parallel ([#204](https://github.com/wxt-dev/wxt/pull/204))
+
+### 🤖 CI
+
+- Separate validation into multiple jobs ([#203](https://github.com/wxt-dev/wxt/pull/203))
+
+## v0.8.6
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.8.5...v0.8.6)
+
+### 🩹 Fixes
+
+- Inline WXT modules inside `WxtVitest` plugin ([b75c553](https://github.com/wxt-dev/wxt/commit/b75c553))
+
 ## v0.8.5
 
 [compare changes](https://github.com/wxt-dev/wxt/compare/v0.8.4...v0.8.5)

demo/package.json

@@ -1,12 +1,12 @@
 {
-  "name": "WXT Demo",
+  "name": "demo",
   "version": "1.0.0",
   "description": "Demo extension for WXT",
   "type": "module",
   "scripts": {
     "dev": "pnpm -w build && wxt",
     "build": "pnpm -w build && wxt build",
-    "build:all": "pnpm -w build && run-s -s build:all:*",
+    "build:all": "pnpm -w build && run-s -s 'build:all:*'",
     "build:all:chrome-mv3": "wxt build",
     "build:all:chrome-mv2": "wxt build --mv2",
     "build:all:firefox-mv3": "wxt build -b firefox --mv3",
@@ -23,10 +23,10 @@
     "webextension-polyfill": "^0.10.0"
   },
   "devDependencies": {
-    "@types/react": "^18.2.14",
-    "@types/react-dom": "^18.2.6",
-    "@types/webextension-polyfill": "^0.10.0",
-    "sass": "^1.64.0",
+    "@types/react": "^18.2.34",
+    "@types/react-dom": "^18.2.14",
+    "@types/webextension-polyfill": "^0.10.5",
+    "sass": "^1.69.5",
     "wxt": "workspace:*"
   }
 }

demo/src/entrypoints/iframe-src/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Iframe Example</title>
+  </head>
+  <body>
+    <p>Hello iframe page!</p>
+    <script type="module" src="./main.ts"></script>
+  </body>
+</html>

demo/src/entrypoints/iframe-src/main.ts

@@ -0,0 +1 @@
+console.log('iframe 2');

demo/src/entrypoints/iframe.content.ts

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

demo/wxt.config.ts

@@ -4,5 +4,11 @@ export default defineConfig({
   srcDir: 'src',
   manifest: {
     default_locale: 'en',
+    web_accessible_resources: [
+      {
+        resources: ['/iframe-src.html'],
+        matches: ['*://*.google.com/*'],
+      },
+    ],
   },
 });

docs/entrypoints/content-scripts.md

@@ -153,6 +153,8 @@ const anchor = document.querySelector('#anchor-selector');
 anchor.append(ui);
 ```
 
+You can try out [`createContentScriptIframe`](#createcontentscriptiframe) as an alternative solution
+
 :::
 
 ### Usage
@@ -162,7 +164,7 @@ To use `createContentScriptUi`, follow these steps:
 1. Import your CSS file at the top of your content script
 2. Set `cssInjectionMode: "ui"` inside `defineContentScript`
 3. Call `createContentScriptUi`
-4. Call `ui.mount()` to add the UI to the webpage
+4. Call `mount` to add the UI to the webpage
 
 Here's a basic example:
 
@@ -185,7 +187,7 @@ export default defineContentScript({
       },
     });
 
-    // Yoy must call `mount` to add the UI to the page.
+    // You must call `mount` to add the UI to the page.
     ui.mount();
   },
 });
@@ -290,3 +292,44 @@ There are 3 types of UI's you can mount.
 Because the overlay UI type results in a 0px by 0px container being added to the webpage, the `alignment` option allows you to configure which corner of your UI is aligned with the 0x0 element.
 
 > TODO: Add visualization of the different alignments.
+
+## UI
+
+WXT provides a utility function, `createContentScriptIframe` to simplify mounting a UI from a content script. It creates an iframe to an unlisted HTML page. Unlike `createContentScriptUi`, this API support HMR.
+
+`createContentScriptIframe` requires a `ContentScriptContext` so that when the context is invalidated, the UI is automatically removed from the webpage.
+
+### Usage
+
+To use `createContentScriptIframe`, follow these steps:
+
+1. Create an unlisted HTML page that will be loaded into your iframe
+1. Add unlisted page to the manifest's `web_accessible_resouces`
+1. Call `createContentScriptUi`
+1. Call `mount` to add the UI to the webpage
+
+Here's a basic example:
+
+```ts
+export default defineContentScript({
+  // ...
+
+  async main(ctx) {
+    const ui = await createContentScriptIframe(ctx, {
+      page: '/your-unlisted-page.html',
+      type: 'inline',
+      anchor: '#some-element',
+      append: 'after',
+    });
+
+    // You must call `mount` to add the UI to the page.
+    ui.mount();
+  },
+});
+```
+
+The options, other than `page`, are the same as [`createContentScriptUi`](#anchor).
+
+### `page`
+
+The HTML page you want to load inside the iframe. This string will be passed into `browser.runtime.getURL` to resolve the full path of to your HTML page.

e2e/tests/auto-imports.test.ts

@@ -18,6 +18,7 @@ describe('Auto Imports', () => {
           declare global {
             const ContentScriptContext: typeof import('wxt/client')['ContentScriptContext']
             const browser: typeof import('wxt/browser')['browser']
+            const createContentScriptIframe: typeof import('wxt/client')['createContentScriptIframe']
             const createContentScriptUi: typeof import('wxt/client')['createContentScriptUi']
             const defineBackground: typeof import('wxt/client')['defineBackground']
             const defineConfig: typeof import('wxt')['defineConfig']

e2e/tests/typescript-project.test.ts

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

package.json

@@ -1,7 +1,7 @@
 {
   "name": "wxt",
   "type": "module",
-  "version": "0.8.5",
+  "version": "0.8.7",
   "description": "Next gen framework for developing web extensions",
   "engines": {
     "node": ">=18",
@@ -75,46 +75,46 @@
     "sync-releases": "pnpx changelogen@latest gh release"
   },
   "dependencies": {
-    "@types/webextension-polyfill": "^0.10.1",
+    "@types/webextension-polyfill": "^0.10.5",
     "@webext-core/fake-browser": "^1.2.2",
     "@webext-core/isolated-element": "^1.0.4",
     "@webext-core/match-patterns": "^1.0.2",
     "async-mutex": "^0.4.0",
-    "c12": "^1.4.2",
+    "c12": "^1.5.1",
     "cac": "^6.7.14",
     "consola": "^3.2.3",
-    "esbuild": "^0.19.4",
+    "esbuild": "^0.19.5",
     "fast-glob": "^3.3.1",
     "filesize": "^10.0.8",
     "fs-extra": "^11.1.1",
     "get-port": "^7.0.0",
-    "giget": "^1.1.2",
-    "immer": "^10.0.2",
+    "giget": "^1.1.3",
+    "immer": "^10.0.3",
     "is-wsl": "^3.0.0",
-    "jiti": "^1.19.1",
+    "jiti": "^1.21.0",
     "json5": "^2.2.3",
-    "linkedom": "^0.15.1",
+    "linkedom": "^0.16.1",
     "minimatch": "^9.0.3",
     "ora": "^7.0.1",
     "picocolors": "^1.0.0",
     "prompts": "^2.4.2",
     "rollup-plugin-visualizer": "^5.9.2",
-    "unimport": "^3.1.0",
-    "vite": "^4.4.11",
+    "unimport": "^3.4.0",
+    "vite": "^4.5.0",
     "web-ext-run": "^0.1.0",
     "webextension-polyfill": "^0.10.0",
     "zip-dir": "^2.0.0"
   },
   "devDependencies": {
-    "@faker-js/faker": "^8.0.2",
-    "@types/fs-extra": "^11.0.1",
-    "@types/lodash.merge": "^4.6.7",
-    "@types/node": "^20.8.6",
-    "@types/prompts": "^2.4.4",
+    "@faker-js/faker": "^8.2.0",
+    "@types/fs-extra": "^11.0.3",
+    "@types/lodash.merge": "^4.6.8",
+    "@types/node": "^20.8.10",
+    "@types/prompts": "^2.4.7",
     "@vitest/coverage-v8": "^0.34.6",
-    "execa": "^7.2.0",
+    "execa": "^8.0.1",
     "happy-dom": "^12.4.0",
-    "lint-staged": "^14.0.0",
+    "lint-staged": "^15.0.2",
     "lodash.merge": "^4.6.2",
     "npm-run-all": "^4.1.5",
     "p-map": "^6.0.0",
@@ -122,14 +122,14 @@
     "simple-git-hooks": "^2.9.0",
     "tsup": "^7.2.0",
     "tsx": "^3.12.7",
-    "typedoc": "^0.25.2",
+    "typedoc": "^0.25.3",
     "typedoc-plugin-markdown": "4.0.0-next.23",
     "typedoc-vitepress-theme": "1.0.0-next.3",
     "typescript": "^5.2.2",
-    "vitepress": "1.0.0-rc.10",
+    "vitepress": "1.0.0-rc.24",
     "vitest": "^0.34.6",
     "vitest-mock-extended": "^1.3.1",
-    "vue": "^3.3.4",
+    "vue": "^3.3.7",
     "webextension-polyfill": "^0.10.0"
   },
   "peerDependencies": {
@@ -140,7 +140,7 @@
     "pre-commit": "pnpm lint-staged"
   },
   "lint-staged": {
-    "*": "prettier --write"
+    "*": "prettier --ignore-unknown --write"
   },
   "changelog": {
     "excludeAuthors": [

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

@@ -0,0 +1,214 @@
+/** @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

@@ -266,7 +266,7 @@ describe('createContentScriptUi', () => {
         });
 
         expect(ui.mount).toThrow(
-          'Failed to mount content script ui: could not find anchor element',
+          'Failed to mount content script UI: could not find anchor element',
         );
       },
     );

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

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

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

@@ -2,6 +2,12 @@ import { createIsolatedElement } from '@webext-core/isolated-element';
 import { browser } from '~/browser';
 import { logger } from '~/client/utils/logger';
 import { ContentScriptContext } from './content-script-context';
+import {
+  ContentScriptAnchoredOptions,
+  ContentScriptPositioningOptions,
+  applyContentScriptUiPosition,
+  mountContentScriptUiRoot,
+} from '../utils/content-script-ui';
 
 /**
  * Utility for mounting content script UI's with isolated styles. Automatically removed from the DOM
@@ -52,83 +58,19 @@ export async function createContentScriptUi<TApp>(
     mode: 'open',
   });
 
-  const getAnchor = (): 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;
-  };
-
   let mounted: TApp;
 
   const mount = () => {
-    const anchor = getAnchor();
-    if (anchor == null)
-      throw Error(
-        'Failed to mount content script ui: could not find anchor element',
-      );
-
     // Mount UI inside shadow root
     mounted = options.mount(uiContainer);
 
     // Add shadow root element to DOM
-    switch (options.append) {
-      case undefined:
-      case 'last':
-        anchor.append(shadowHost);
-        break;
-      case 'first':
-        if (anchor.firstChild) {
-          anchor.insertBefore(shadowHost, anchor.firstChild);
-        } else {
-          anchor.append(shadowHost);
-        }
-        break;
-      case 'replace':
-        anchor.replaceWith(shadowHost);
-        break;
-      case 'after':
-        anchor.replaceWith(anchor, shadowHost);
-        break;
-      case 'before':
-        anchor.replaceWith(shadowHost, anchor);
-        break;
-      default:
-        options.append(anchor, shadowHost);
-        break;
-    }
-
-    // Apply types
-    if (options.type !== 'inline') {
-      if (options.zIndex != null)
-        shadowHost.style.zIndex = String(options.zIndex);
-
-      shadowHost.style.overflow = 'visible';
-      shadowHost.style.position = 'relative';
-      shadowHost.style.width = '0';
-      shadowHost.style.height = '0';
-      shadowHost.style.display = 'block';
-
-      const html = shadow.querySelector('html')!;
-      // HTML doesn't exist in tests
-      if (options.type === 'overlay') {
-        html.style.position = 'absolute';
-        if (options.alignment?.startsWith('bottom-')) html.style.bottom = '0';
-        else html.style.top = '0';
-
-        if (options.alignment?.endsWith('-right')) html.style.right = '0';
-        else html.style.left = '0';
-      } else {
-        html.style.position = 'fixed';
-        html.style.top = '0';
-        html.style.bottom = '0';
-        html.style.left = '0';
-        html.style.right = '0';
-      }
-    }
+    mountContentScriptUiRoot(shadowHost, options);
+    applyContentScriptUiPosition(
+      shadowHost,
+      shadow.querySelector('html'),
+      options,
+    );
   };
 
   const remove = () => {
@@ -202,100 +144,30 @@ export interface ContentScriptUi<TApp> {
   remove: () => void;
 }
 
-export interface BaseContentScriptUiOptions<TApp> {
-  /**
-   * The name of the custom component used to host the ShadowRoot. Must be kebab-case.
-   */
-  name: string;
-  /**
-   * 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);
-  /**
-   * 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);
-  /**
-   * Callback executed when mounting the UI. This function should create and append the UI to the
-   * `container` element. It is called every time `ui.mount()` is called
-   *
-   * Optionally return a value that can be accessed at `ui.mounted` or in the `onRemove` callback.
-   */
-  mount: (container: Element) => TApp;
-  /**
-   * Callback called when the UI is removed from the webpage. Use to cleanup your UI, like
-   * unmounting your vue or react apps.
-   */
-  onRemove?: (mounted: TApp) => void;
-  /**
-   * Custom CSS text to apply to the UI. If your content script imports/generates CSS and you've
-   * set `cssInjectionMode: "ui"`, the imported CSS will be included automatically. You do not need
-   * to pass those styles in here. This is for any additional styles not in the imported CSS.
-   *
-   * See https://wxt.dev/entrypoints/content-scripts.html#ui for more info.
-   */
-  css?: string;
-}
-
-export type OverlayContentScriptUiOptions<TApp> =
-  BaseContentScriptUiOptions<TApp> & {
-    type: 'overlay';
+export type ContentScriptUiOptions<TApp> = ContentScriptPositioningOptions &
+  ContentScriptAnchoredOptions & {
     /**
-     * When using `type: "overlay"`, the mounted element is 0px by 0px in size. Alignment specifies
-     * which corner is aligned with that 0x0 pixel space.
+     * 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
      *
-     * @default "top-left"
+     * Optionally return a value that can be accessed at `ui.mounted` or in the `onRemove` callback.
      */
-    alignment?: ContentScriptUiOverlayAlignment;
+    mount: (container: Element) => TApp;
     /**
-     * The `z-index` used on the `shadowHost`. Set to a positive number to show your UI over website
-     * content.
+     * Callback called when the UI is removed from the webpage. Use to cleanup your UI, like
+     * unmounting your vue or react apps.
      */
-    zIndex?: number;
-  };
-
-export type ModalContentScriptUiOptions<TApp> =
-  BaseContentScriptUiOptions<TApp> & {
-    type: 'modal';
+    onRemove?: (mounted: TApp) => void;
     /**
-     * The `z-index` used on the `shadowHost`. Set to a positive number to show your UI over website
-     * content.
+     * Custom CSS text to apply to the UI. If your content script imports/generates CSS and you've
+     * set `cssInjectionMode: "ui"`, the imported CSS will be included automatically. You do not need
+     * to pass those styles in here. This is for any additional styles not in the imported CSS.
+     *
+     * See https://wxt.dev/entrypoints/content-scripts.html#ui for more info.
      */
-    zIndex?: number;
+    css?: string;
   };
-
-export type InlineContentScriptUiOptions<TApp> =
-  BaseContentScriptUiOptions<TApp> & {
-    type: 'inline';
-  };
-
-export type ContentScriptUiOverlayAlignment =
-  | 'top-left'
-  | 'top-right'
-  | 'bottom-left'
-  | 'bottom-right';
-
-export type ContentScriptAppendMode =
-  | 'last'
-  | 'first'
-  | 'replace'
-  | 'before'
-  | 'after';
-
-export type ContentScriptUiOptions<TApp> =
-  | OverlayContentScriptUiOptions<TApp>
-  | ModalContentScriptUiOptions<TApp>
-  | InlineContentScriptUiOptions<TApp>;

src/client/content-scripts/index.ts

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

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

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

src/core/create-server.ts

@@ -6,7 +6,7 @@ import {
   WxtDevServer,
 } from '~/types';
 import * as vite from 'vite';
-import { Scripting } from 'webextension-polyfill';
+import type { Scripting } from 'webextension-polyfill';
 import {
   getEntrypointBundlePath,
   getEntrypointOutputFile,

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

@@ -77,7 +77,7 @@ async function writePathsDeclarationFile(
 import "wxt/browser";
 
 declare module "wxt/browser" {
-  type PublicPath =
+  export type PublicPath =
 {{ union }}
   export interface WxtRuntime extends Runtime.Static {
     getURL(path: PublicPath): string;

src/core/utils/building/rebuild.ts

@@ -1,4 +1,4 @@
-import { Manifest } from 'webextension-polyfill';
+import type { Manifest } from 'webextension-polyfill';
 import { BuildOutput, EntrypointGroup, InternalConfig } from '~/types';
 import { findEntrypoints } from './find-entrypoints';
 import { generateTypesDir } from './generate-wxt-dir';

src/core/utils/content-scripts.ts

@@ -1,4 +1,4 @@
-import { Manifest } from 'webextension-polyfill';
+import type { Manifest } from 'webextension-polyfill';
 import { ContentScriptEntrypoint, InternalConfig } from '~/types';
 import { resolvePerBrowserOption } from './entrypoints';
 

src/core/utils/manifest.ts

@@ -1,4 +1,4 @@
-import { Manifest } from 'webextension-polyfill';
+import type { Manifest } from 'webextension-polyfill';
 import {
   Entrypoint,
   BackgroundEntrypoint,

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

@@ -5,7 +5,7 @@ import { resolve } from 'path';
 import { faker } from '@faker-js/faker';
 import merge from 'lodash.merge';
 import { Rollup } from 'vite';
-import { Manifest } from 'webextension-polyfill';
+import type { Manifest } from 'webextension-polyfill';
 import {
   FsCache,
   InternalConfig,
@@ -164,6 +164,7 @@ export const fakeRollupOutputChunk = fakeObjectCreator<Rollup.OutputChunk>(
       importedCss: new Set(),
     },
     preliminaryFileName: faker.string.alphanumeric(),
+    sourcemapFileName: null,
   }),
 );
 

src/core/vite-plugins/index.ts

@@ -10,3 +10,4 @@ export * from './cssEntrypoints';
 export * from './bundleAnalysis';
 export * from './globals';
 export * from './webextensionPolyfillAlias';
+export * from './webextensionPolyfillInlineDeps';

src/core/vite-plugins/webextensionPolyfillInlineDeps.ts

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

src/testing/wxt-vitest-plugin.ts

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

src/types/modules.d.ts

@@ -49,3 +49,8 @@ declare module 'web-ext-run/util/logger' {
   }
   export const consoleStream: IConsoleStream;
 }
+
+declare module 'wxt/browser' {
+  // Overridden when types are generated per project
+  export type PublicPath = string;
+}

src/types/project-types.d.ts

@@ -0,0 +1,3 @@
+// Types generated in the .wxt directory available after wxt prepare
+
+declare type PublicPath = string;

vitest.workspace.ts

@@ -41,7 +41,6 @@ export default defineWorkspace([
     test: {
       name: 'e2e',
       dir: 'e2e',
-      singleThread: true,
       testTimeout: 120e3,
     },
     plugins: [testSeed()],