chore(release): v0.17.11

fix: Resolve absolute paths from the public directory properly (#583 )
chore: Extract helper function
2024-03-31 13:22:25 +00:00 · 2024-03-31 08:19:06 -05:00 · 2024-03-30 14:49:10 -05:00 · 2024-03-30 13:30:45 -05:00 · 2024-03-30 12:44:27 -05:00 · 2024-03-30 08:37:26 -05:00
173 changed files with 8056 additions and 3634 deletions
@@ -1,2 +1,5 @@
 * text=auto eol=lf
 pnpm-lock.yaml linguist-generated
+package-lock.json linguist-generated
+bun.lockb linguist-generated
+yarn.lock linguist-generated
@@ -4,7 +4,7 @@ runs:
  using: composite
  steps:
    - name: Setup PNPM
-      uses: pnpm/action-setup@v2
+      uses: pnpm/action-setup@v3
      with:
        version: 8
    - name: Setup NodeJS
@@ -9,3 +9,7 @@ updates:
    directory: '/' # Location of package manifests
    schedule:
      interval: 'monthly'
+  - package-ecosystem: 'github-actions'
+    directory: '/'
+    schedule:
+      interval: 'monthly'
@@ -14,7 +14,7 @@ jobs:
  publish:
    runs-on: ubuntu-22.04
    steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
      - uses: ./.github/actions/setup
      - uses: docker/login-action@v3
        with:
@@ -5,13 +5,14 @@ on:
 jobs:
  validate:
    uses: './.github/workflows/validate.yml'
+    secrets: inherit

  publish:
    runs-on: ubuntu-22.04
    needs:
      - validate
    steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

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

 jobs:
-  formatting:
+  checks:
    runs-on: ubuntu-22.04
    steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
      - uses: ./.github/actions/setup
-      - run: pnpm format:check
-  lint:
-    runs-on: ubuntu-22.04
-    steps:
-      - uses: actions/checkout@v3
-      - uses: ./.github/actions/setup
-      - run: pnpm lint
-  type-check:
-    runs-on: ubuntu-22.04
-    steps:
-      - uses: actions/checkout@v3
-      - uses: ./.github/actions/setup
-      - run: pnpm compile
+      - run: pnpm check
  validate-demo:
    runs-on: ubuntu-22.04
    steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
      - uses: ./.github/actions/setup
      - run: pnpm tsc --noEmit
        working-directory: demo
@@ -41,17 +29,18 @@ jobs:
  tests:
    runs-on: ubuntu-22.04
    steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
      - uses: ./.github/actions/setup
+      - uses: oven-sh/setup-bun@v1
      - name: pnpm test:coverage
        run: pnpm test:coverage --reporter=default --reporter=hanging-process
-      - uses: codecov/codecov-action@v3
+      - uses: codecov/codecov-action@v4
        env:
          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
  windows-tests:
    runs-on: windows-latest
    steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
      - uses: ./.github/actions/setup
      - run: pnpm test run
  template:
@@ -65,7 +54,7 @@ jobs:
          - vanilla
          - vue
    steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
      - uses: ./.github/actions/setup
      - run: pnpm pack
      - run: npm i
@@ -1,5 +1,617 @@
 # Changelog

+## v0.17.11
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.17.10...v0.17.11)
+
+### 🩹 Fixes
+
+- Resolve absolute paths from the public directory properly ([#583](https://github.com/wxt-dev/wxt/pull/583))
+
+### 📖 Documentation
+
+- Fix `zip.includeSources` example ([16fc584](https://github.com/wxt-dev/wxt/commit/16fc584))
+- Add "GitHub Custom Notifier" to homepage ([#580](https://github.com/wxt-dev/wxt/pull/580))
+
+### 🏡 Chore
+
+- Simplify virtual module setup ([#581](https://github.com/wxt-dev/wxt/pull/581))
+- Add some array utils ([#582](https://github.com/wxt-dev/wxt/pull/582))
+- Extract helper function ([d3b14af](https://github.com/wxt-dev/wxt/commit/d3b14af))
+
+### ❤️ Contributors
+
+- Qiwei Yang ([@qiweiii](http://github.com/qiweiii))
+
+## v0.17.10
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.17.9...v0.17.10)
+
+### 🚀 Enhancements
+
+- Add `dev.server.port` config ([#577](https://github.com/wxt-dev/wxt/pull/577))
+
+### 🏡 Chore
+
+- Use `@aklinker1/check` to simplify checks setup ([#550](https://github.com/wxt-dev/wxt/pull/550))
+- Refactor order of config resolution ([#578](https://github.com/wxt-dev/wxt/pull/578))
+
+### ❤️ Contributors
+
+- Zizheng Tai ([@zizhengtai](http://github.com/zizhengtai))
+
+## v0.17.9
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.17.8...v0.17.9)
+
+### 🚀 Enhancements
+
+- Add `{{mode}}` Template Variable ([#566](https://github.com/wxt-dev/wxt/pull/566))
+
+### 🩹 Fixes
+
+- Don't override `wxt.config.ts` options when CLI flags are not passed ([#567](https://github.com/wxt-dev/wxt/pull/567))
+
+### 🏡 Chore
+
+- Merge user config using `defu` ([#568](https://github.com/wxt-dev/wxt/pull/568))
+
+### ❤️ Contributors
+
+- Guillaume ([@GuiEpi](http://github.com/GuiEpi))
+
+## v0.17.8
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.17.7...v0.17.8)
+
+### 🚀 Enhancements
+
+- **analysis:** Open `stats.html` file automatically ([#564](https://github.com/wxt-dev/wxt/pull/564))
+
+### 🩹 Fixes
+
+- **init:** Better error logging when templates fail to load ([b47c150](https://github.com/wxt-dev/wxt/commit/b47c150))
+- Remove deprecated extension from Vue template ([#534](https://github.com/wxt-dev/wxt/pull/534))
+- Append option description error ([#546](https://github.com/wxt-dev/wxt/pull/546))
+- **init:** Don't overwrite existing files when initializing a new project ([#556](https://github.com/wxt-dev/wxt/pull/556))
+- **dev:** Don't crash dev mode when rebuild fails ([#565](https://github.com/wxt-dev/wxt/pull/565))
+
+### 📖 Documentation
+
+- Replace `pnpx` with `pnpm dlx` ([#527](https://github.com/wxt-dev/wxt/pull/527))
+- Update homepage demo video ([35269da](https://github.com/wxt-dev/wxt/commit/35269da))
+- Update README demo video ([#539](https://github.com/wxt-dev/wxt/pull/539))
+- Add Plex skipper to "Using WXT" section ([#541](https://github.com/wxt-dev/wxt/pull/541))
+- Add documentation for Bun.sh ([#543](https://github.com/wxt-dev/wxt/pull/543))
+- Mention adding unlisted scripts and pages to `web_accessible_resources` ([121b521](https://github.com/wxt-dev/wxt/commit/121b521))
+- Add examples for GitHub Actions ([#540](https://github.com/wxt-dev/wxt/pull/540))
+- Fixed "Reload the Extension" section ([#559](https://github.com/wxt-dev/wxt/pull/559))
+
+### 🏡 Chore
+
+- Increase unit test timeout ([d9cba55](https://github.com/wxt-dev/wxt/commit/d9cba55))
+- Increase hook timeout for Windows/NPM tests ([56b7149](https://github.com/wxt-dev/wxt/commit/56b7149))
+- Switch to seed plugin for testing ([#547](https://github.com/wxt-dev/wxt/pull/547))
+- **vue-template:** Upgrade to `vue-tsc` v2 ([#549](https://github.com/wxt-dev/wxt/pull/549))
+- Add a test covering `wxt init` in a non-empty directory ([#563](https://github.com/wxt-dev/wxt/pull/563))
+
+### ❤️ Contributors
+
+- Btea ([@btea](http://github.com/btea))
+- Vlad Fedosov ([@StyleT](http://github.com/StyleT))
+- Lpmvb ([@Lpmvb](http://github.com/Lpmvb))
+- Guillaume ([@GuiEpi](http://github.com/GuiEpi))
+- Sunshio ([@MPB-Tech](http://github.com/MPB-Tech))
+- Luca Dalli ([@lucadalli](http://github.com/lucadalli))
+
+## v0.17.7
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.17.6...v0.17.7)
+
+### 🩹 Fixes
+
+- **zip:** List `.wxt/local_modules` overrides relative to the `package.json` they're added to ([#526](https://github.com/wxt-dev/wxt/pull/526))
+
+### 🏡 Chore
+
+- Bump templates to v0.17 ([#524](https://github.com/wxt-dev/wxt/pull/524))
+- Increase test timeout for windows NPM tests ([#525](https://github.com/wxt-dev/wxt/pull/525))
+
+## v0.17.6
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.17.5...v0.17.6)
+
+### 🚀 Enhancements
+
+- Add warnings when important directories are missing ([#516](https://github.com/wxt-dev/wxt/pull/516))
+- Automatically remove top-level MV2-only or MV3-only keys ([#518](https://github.com/wxt-dev/wxt/pull/518))
+- Automatically generate `browser_action` based on `action` for MV2 ([#519](https://github.com/wxt-dev/wxt/pull/519))
+
+### 🩹 Fixes
+
+- **zip:** List all private packages correctly in a PNPM workspace ([#520](https://github.com/wxt-dev/wxt/pull/520))
+
+### 📖 Documentation
+
+- Mentions moving folders into `srcDir` ([9cd4e83](https://github.com/wxt-dev/wxt/commit/9cd4e83))
+
+### 🏡 Chore
+
+- **deps-dev:** Bump @types/react from 18.2.34 to 18.2.61 ([#510](https://github.com/wxt-dev/wxt/pull/510))
+
+## v0.17.5
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.17.4...v0.17.5)
+
+### 🚀 Enhancements
+
+- Expose package management utils under `wxt.pm` ([#502](https://github.com/wxt-dev/wxt/pull/502))
+- Download and override private packages for Firefox code review ([#507](https://github.com/wxt-dev/wxt/pull/507))
+
+### 📖 Documentation
+
+- Fix typos ([#503](https://github.com/wxt-dev/wxt/pull/503))
+- Add docs about configuring the manifest as a function ([195d2cc](https://github.com/wxt-dev/wxt/commit/195d2cc))
+- Fix CLI generation ([b754435](https://github.com/wxt-dev/wxt/commit/b754435))
+
+### 🏡 Chore
+
+- Use JSZip for `wxt zip`, enabling future features ([#501](https://github.com/wxt-dev/wxt/pull/501))
+
+### ❤️ Contributors
+
+- Btea ([@btea](http://github.com/btea))
+
+## v0.17.4
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.17.3...v0.17.4)
+
+### 🚀 Enhancements
+
+- Add basic content script to templates ([#495](https://github.com/wxt-dev/wxt/pull/495))
+- Add `ResolvedConfig.wxtModuleDir`, resolving the directory once ([#497](https://github.com/wxt-dev/wxt/pull/497))
+
+### 🩹 Fixes
+
+- Resolve the path to `node_modules/wxt` correctly ([#498](https://github.com/wxt-dev/wxt/pull/498))
+
+### 📖 Documentation
+
+- Added DocVersionRedirector to "Using WXT" section ([#492](https://github.com/wxt-dev/wxt/pull/492))
+- Fix typos ([f80fb42](https://github.com/wxt-dev/wxt/commit/f80fb42))
+- Add CRXJS to comparison page ([cb4f9aa](https://github.com/wxt-dev/wxt/commit/cb4f9aa))
+- Update comparison page ([35778f7](https://github.com/wxt-dev/wxt/commit/35778f7))
+- Update context usage ([012bd7e](https://github.com/wxt-dev/wxt/commit/012bd7e))
+- Add testing example for `ContentScriptContext` ([e1c6020](https://github.com/wxt-dev/wxt/commit/e1c6020))
+
+### 🏡 Chore
+
+- Fix tests after template change ([f9b0aa4](https://github.com/wxt-dev/wxt/commit/f9b0aa4))
+
+### ❤️ Contributors
+
+- Btea ([@btea](http://github.com/btea))
+- Leo Shklovskii <leo@thermopylae.net>
+
+## v0.17.3
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.17.2...v0.17.3)
+
+### 🚀 Enhancements
+
+- **storage:** Guarantee `storage.getItems` returns values in the same order as requested ([b5f4d8c](https://github.com/wxt-dev/wxt/commit/b5f4d8c))
+
+### 🩹 Fixes
+
+- Content scripts crash when using `storage.defineItem` ([77e6d1f](https://github.com/wxt-dev/wxt/commit/77e6d1f))
+- **storage:** Revert #478 and run migrations when item is defined and properly wait for migrations before allowing read/writes ([#487](https://github.com/wxt-dev/wxt/pull/487), [#478](https://github.com/wxt-dev/wxt/issues/478))
+
+## v0.17.2
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.17.1...v0.17.2)
+
+### 🩹 Fixes
+
+- Don't use sub-dependency binaries directly ([#482](https://github.com/wxt-dev/wxt/pull/482))
+
+## v0.17.1
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.17.0...v0.17.1)
+
+### 🩹 Fixes
+
+- Content scripts not loading in dev mode ([3fbbe2c](https://github.com/wxt-dev/wxt/commit/3fbbe2c))
+
+### 📖 Documentation
+
+- Lots of small typo fixes ([#480](https://github.com/wxt-dev/wxt/pull/480))
+
+### ❤️ Contributors
+
+- Leo Shklovskii ([@leos](https://github.com/leos))
+
+## v0.17.0
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.16.11...v0.17.0)
+
+### 🚀 Enhancements
+
+- **storage:** ⚠️  Improved support for default values on storage items ([#477](https://github.com/wxt-dev/wxt/pull/477))
+
+### 🩹 Fixes
+
+- **storage:** ⚠️  Only run migrations when the extension is updated ([#478](https://github.com/wxt-dev/wxt/pull/478))
+- Improve dev mode for content scripts registered at runtime ([#474](https://github.com/wxt-dev/wxt/pull/474))
+
+### 📖 Documentation
+
+- **storage:** Update docs ([91fc41c](https://github.com/wxt-dev/wxt/commit/91fc41c))
+
+#### ⚠️ Breaking Changes
+
+`v0.17.0` introduces several breaking changes to `wxt/storage`.
+
+First, if you were using `defineItem` with versioning and no default value, you will need to add `defaultValue: null` to the options and update the first type parameter:
+
+```ts
+// < 0.17
+const item = storage.defineItem<number>("local:count", {
+  version: ...,
+  migrations: ...,
+})
+
+// >= 0.17
+const item = storage.defineItem<number | null>("local:count", {
+  defaultValue: null,
+  version: ...,
+  migrations: ...,
+})
+```
+
+The `defaultValue` property is now required if passing in the second options argument. 
+
+If you exclude the second options argument, it will default to being nullable, as before.
+
+```ts
+const item: WxtStorageItem<number | null> = storage.defineItem<number>("local:count");
+const value: number | null = await item.getValue();
+```
+
+> If you don't use typescript, there aren't any breaking changes, this is just a type change.
+
+For storage items that are not nullable, the `watch` callback types has improved and will use the default value instead of `null` when the value is missing:
+
+```ts
+// >=0.17
+const item = storage.defineItem<number>("local:count", { defaultValue: 0 });
+item.watch((newValue: number | null, oldValue: number | null) => {
+  // ...
+});
+
+// >=0.17
+const item = storage.defineItem<number>("local:count", { defaultValue: 0 });
+item.watch((newValue: number, oldValue: number) => {
+  // ...
+});
+```
+
+You can also access the default value directly off the item:
+
+```ts
+console.log(item.defaultValue); // 0
+```
+
+The second breaking change is that migrations for versioned items only run when the extension is updated. Before, they were ran whenever the storage item was created, in any entrypoint (background, popup, content script, etc). Now, in v0.17, storage items will only run migrations when the `browser.runtime.onInstalled` event is fired with `reason = "update"` in the background. See the updated docs to make sure they run correctly: https://wxt.dev/guide/storage.html#running-migrations. TLDR: you need to import all storage items into the background entrypoint for the `onInstalled` hook to fire properly and thus run the migrations.
+
+To keep the old behavior, call the new `migrate` function to run migrations as soon as an item is defined:
+
+```ts
+const item = storage.defineItem(...);
+item.migrate();
+```
+
+## v0.16.11
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.16.10...v0.16.11)
+
+### 🩹 Fixes
+
+- Output main JS file for HTML entrypoints to chunks directory ([#473](https://github.com/wxt-dev/wxt/pull/473))
+
+### 🏡 Chore
+
+- **e2e:** Remove log ([4fda203](https://github.com/wxt-dev/wxt/commit/4fda203))
+
+### 🤖 CI
+
+- Fix codecov warning in release workflow ([7c6973f](https://github.com/wxt-dev/wxt/commit/7c6973f))
+- Upgrade `pnpm/action-setup` to v3 ([905bfc7](https://github.com/wxt-dev/wxt/commit/905bfc7))
+
+## v0.16.10
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.16.9...v0.16.10)
+
+### 🚀 Enhancements
+
+- Customize when content scripts are registered, in the manifest or at runtime ([#471](https://github.com/wxt-dev/wxt/pull/471))
+
+### 🩹 Fixes
+
+- Don't assume react when importing JSX entrypoints during build ([#470](https://github.com/wxt-dev/wxt/pull/470))
+- Respect `configFile` option ([#472](https://github.com/wxt-dev/wxt/pull/472))
+
+## v0.16.9
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.16.8...v0.16.9)
+
+### 🚀 Enhancements
+
+- Support setting side panel options in HTML file ([#468](https://github.com/wxt-dev/wxt/pull/468))
+
+### 🩹 Fixes
+
+- Fix order of ShadowRootUI hooks calling ([#459](https://github.com/wxt-dev/wxt/pull/459))
+
+### 📖 Documentation
+
+- Add wrapper div to react's `createShadowRootUi` example ([bc24ea4](https://github.com/wxt-dev/wxt/commit/bc24ea4))
+
+### 🏡 Chore
+
+- Simplify entrypoint types ([#464](https://github.com/wxt-dev/wxt/pull/464))
+
+### ❤️ Contributors
+
+- Okou ([@ookkoouu](https://github.com/ookkoouu))
+
+## v0.16.8
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.16.7...v0.16.8)
+
+### 🩹 Fixes
+
+- Watch files outside project root during development ([#454](https://github.com/wxt-dev/wxt/pull/454))
+
+### 📖 Documentation
+
+- Add loading and error states for "Who's using WXT" section ([447a48f](https://github.com/wxt-dev/wxt/commit/447a48f))
+
+## v0.16.7
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.16.6...v0.16.7)
+
+### 🚀 Enhancements
+
+- Generate ESLint globals file for auto-imports ([#450](https://github.com/wxt-dev/wxt/pull/450))
+
+### 🔥 Performance
+
+- Upgrade Vite to 5.1 ([#452](https://github.com/wxt-dev/wxt/pull/452))
+
+### 📖 Documentation
+
+- Add section about dev mode differences ([a0d1643](https://github.com/wxt-dev/wxt/commit/a0d1643))
+- Remove anchor from content script ui examples ([87a62a1](https://github.com/wxt-dev/wxt/commit/87a62a1))
+
+### 🏡 Chore
+
+- **e2e:** Use `wxt prepare` instead of `wxt build` when possible to speed up E2E tests ([#451](https://github.com/wxt-dev/wxt/pull/451))
+
+## v0.16.6
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.16.5...v0.16.6)
+
+### 🚀 Enhancements
+
+- Add option to customize the analysis artifacts output ([#431](https://github.com/wxt-dev/wxt/pull/431))
+
+### 🩹 Fixes
+
+- Use `insertBefore` on mounting content script UI ([ba85fdf](https://github.com/wxt-dev/wxt/commit/ba85fdf))
+
+### 💅 Refactors
+
+- Use `Element.prepend` on mounting UI ([295f860](https://github.com/wxt-dev/wxt/commit/295f860))
+
+### 📖 Documentation
+
+- Fix `createShadowRootUi` unmount calls ([946072f](https://github.com/wxt-dev/wxt/commit/946072f))
+
+### 🏡 Chore
+
+- Enable skipped test since it works now ([6b8dfdf](https://github.com/wxt-dev/wxt/commit/6b8dfdf))
+
+### ❤️ Contributors
+
+- Lionelhorn ([@Lionelhorn](https://github.com/Lionelhorn))
+- Okou ([@ookkoouu](https://github.com/ookkoouu))
+
+## v0.16.5
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.16.4...v0.16.5)
+
+### 🩹 Fixes
+
+- Support node 20 when running `wxt submit` ([e835502](https://github.com/wxt-dev/wxt/commit/e835502))
+
+### 📖 Documentation
+
+- Remove "coming soon" from automated publishing feature ([2b374b9](https://github.com/wxt-dev/wxt/commit/2b374b9))
+
+## v0.16.4
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.16.3...v0.16.4)
+
+### 🚀 Enhancements
+
+- Automatically convert MV3 `web_accessible_resources` to MV2 ([#423](https://github.com/wxt-dev/wxt/pull/423))
+- Add option to customize the analysis output filename ([#426](https://github.com/wxt-dev/wxt/pull/426))
+
+### 🩹 Fixes
+
+- Don't use immer for `transformManifest` ([#424](https://github.com/wxt-dev/wxt/pull/424))
+- Exclude analysis files from the build summary ([#425](https://github.com/wxt-dev/wxt/pull/425))
+
+### 🏡 Chore
+
+- Fix fake path in test data generator ([d0f1c70](https://github.com/wxt-dev/wxt/commit/d0f1c70))
+
+## v0.16.3
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.16.2...v0.16.3)
+
+### 🚀 Enhancements
+
+- Hooks ([#419](https://github.com/wxt-dev/wxt/pull/419))
+
+### 🩹 Fixes
+
+- **init:** Use `ungh` to prevent rate limits when loading templates ([37ad2c7](https://github.com/wxt-dev/wxt/commit/37ad2c7))
+
+### 📖 Documentation
+
+- Fix typo of intuitive ([#415](https://github.com/wxt-dev/wxt/pull/415))
+- Fix typo of opinionated ([#416](https://github.com/wxt-dev/wxt/pull/416))
+
+### 🏡 Chore
+
+- Add dependabot for github actions ([#404](https://github.com/wxt-dev/wxt/pull/404))
+- **deps-dev:** Bump happy-dom from 12.10.3 to 13.3.8 ([#411](https://github.com/wxt-dev/wxt/pull/411))
+- **deps-dev:** Bump typescript from 5.3.2 to 5.3.3 ([#409](https://github.com/wxt-dev/wxt/pull/409))
+- Register global `wxt` instance ([#418](https://github.com/wxt-dev/wxt/pull/418))
+
+### ❤️ Contributors
+
+- Chen Hua ([@hcljsq](https://github.com/hcljsq))
+- Florian Metz ([@Timeraa](http://github.com/Timeraa))
+
+## v0.16.2
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.16.1...v0.16.2)
+
+### 🩹 Fixes
+
+- Don't crash background service worker when using `import.meta.url` ([#402](https://github.com/wxt-dev/wxt/pull/402))
+
+## v0.16.1
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.16.0...v0.16.1)
+
+### 🩹 Fixes
+
+- Don't require config to run `wxt submit init` ([9318346](https://github.com/wxt-dev/wxt/commit/9318346))
+
+### 📖 Documentation
+
+- Add premid extension to homepage ([#399](https://github.com/wxt-dev/wxt/pull/399))
+
+### 🏡 Chore
+
+- **templates:** Upgrade to wxt `^0.16.0` ([f0b2a12](https://github.com/wxt-dev/wxt/commit/f0b2a12))
+
+### ❤️ Contributors
+
+- Florian Metz ([@Timeraa](http://github.com/Timeraa))
+
+## v0.16.0
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.15.4...v0.16.0)
+
+### 🚀 Enhancements
+
+- ⚠️  ESM background support ([#398](https://github.com/wxt-dev/wxt/pull/398))
+
+### 📖 Documentation
+
+- Document how to opt into ESM ([1e12ce2](https://github.com/wxt-dev/wxt/commit/1e12ce2))
+
+### 🏡 Chore
+
+- **deps-dev:** Bump lint-staged from 15.2.0 to 15.2.1 ([#395](https://github.com/wxt-dev/wxt/pull/395))
+- **deps-dev:** Bump p-map from 7.0.0 to 7.0.1 ([#396](https://github.com/wxt-dev/wxt/pull/396))
+- **deps-dev:** Bump @vitest/coverage-v8 from 1.0.1 to 1.2.2 ([#397](https://github.com/wxt-dev/wxt/pull/397))
+
+#### ⚠️ Breaking Changes
+
+In [#398](https://github.com/wxt-dev/wxt/pull/398), HTML pages' JS entrypoints in the output directory have been moved. Unless you're doing some kind of post-build work referencing files, you don't have to make any changes.
+
+- Before:
+   ```
+   .output/
+     <target>/
+       chunks/
+         some-shared-chunk-<hash>.js
+         popup-<hash>.js
+       popup.html
+   ```
+- After:
+   ```
+   .output/
+     <target>/
+       chunks/
+         some-shared-chunk-<hash>.js
+       popup.html
+       popup.js
+   ```
+
+This effects all HTML files, not just the Popup. The hash has been removed, and it's been moved to the root of the build target folder, not inside the `chunks/` directory. Moving files like this has not historically increased review times or triggered in-depth reviews when submitting updates to the stores.
+
+## v0.15.4
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.15.3...v0.15.4)
+
+### 🩹 Fixes
+
+- **submit:** Load `.env.submit` automatically when running `wxt submit` and `wxt submit init` ([#391](https://github.com/wxt-dev/wxt/pull/391))
+
+## v0.15.3
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.15.2...v0.15.3)
+
+### 🩹 Fixes
+
+- **dev:** Reload `<name>/index.html` entrypoints properly on save ([#390](https://github.com/wxt-dev/wxt/pull/390))
+
+## v0.15.2
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.15.1...v0.15.2)
+
+### 🚀 Enhancements
+
+- Add `submit` command ([#370](https://github.com/wxt-dev/wxt/pull/370))
+
+### 🩹 Fixes
+
+- **dev:** Resolve `script` and `link` aliases ([#387](https://github.com/wxt-dev/wxt/pull/387))
+
+### ❤️ Contributors
+
+- Nenad Novaković ([@dvlden](https://github.com/dvlden))
+
+## v0.15.1
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/v0.15.0...v0.15.1)
+
+### 🚀 Enhancements
+
+- Allow passing custom preferences to chrome, enabling dev mode on `chrome://extensions` and allowing content script sourcemaps automatically ([#384](https://github.com/wxt-dev/wxt/pull/384))
+
+### 🩹 Fixes
+
+- **security:** Upgrade to vite@5.0.12 to resolve CVE-2024-23331 ([39b76d3](https://github.com/wxt-dev/wxt/commit/39b76d3))
+
+### 📖 Documentation
+
+- Fixed doc errors on the guide/extension-api page ([#383](https://github.com/wxt-dev/wxt/pull/383))
+
+### 🏡 Chore
+
+- Fix vite version conflicts in demo extension ([98d2792](https://github.com/wxt-dev/wxt/commit/98d2792))
+
+### ❤️ Contributors
+
+- 0x7a7a ([@0x7a7a](https://github.com/0x7a7a))
+
 ## v0.15.0

 [compare changes](https://github.com/wxt-dev/wxt/compare/v0.14.7...v0.15.0)
@@ -24,12 +636,22 @@

 #### ⚠️ Breaking Changes

- **zip:** ⚠️  Add `includeSources` and rename `ignoredSources` to `excludeSources` ([#378](https://github.com/wxt-dev/wxt/pull/378))
- ⚠️  Move browser constants to `import.meta.env` ([#380](https://github.com/wxt-dev/wxt/pull/380))
+Renamed `zip.ignoredSources` to `zip.excludeSources` in [#378](https://github.com/wxt-dev/wxt/pull/378)
+
+Renamed undocumented constants for detecting the build config at runtime in [#380](https://github.com/wxt-dev/wxt/pull/380). Now documented here: https://wxt.dev/guide/multiple-browsers.html#runtime
+
+- `__BROWSER__` &rarr; `import.meta.env.BROWSER`
+- `__COMMAND__` &rarr; `import.meta.env.COMMAND`
+- `__MANIFEST_VERSION__` &rarr; `import.meta.env.MANIFEST_VERSION`
+- `__IS_CHROME__` &rarr; `import.meta.env.CHROME`
+- `__IS_FIREFOX__` &rarr; `import.meta.env.FIREFOX`
+- `__IS_SAFARI__` &rarr; `import.meta.env.SAFARI`
+- `__IS_EDGE__` &rarr; `import.meta.env.EDGE`
+- `__IS_OPERA__` &rarr; `import.meta.env.OPERA`

 ### ❤️ Contributors

- Nenad Novaković
+- Nenad Novaković ([@dvlden](https://github.com/dvlden))

 ## v0.14.7

@@ -522,7 +1144,7 @@

 ### 🏡 Chore

- Remove whitespace from genearted `.wxt` files ([#211](https://github.com/wxt-dev/wxt/pull/211))
+- Remove whitespace from generated `.wxt` files ([#211](https://github.com/wxt-dev/wxt/pull/211))
 - Upgrade templates to `wxt@^0.9.0` ([#214](https://github.com/wxt-dev/wxt/pull/214))
 - Update Vite dependency range to `^4.0.0 || ^5.0.0-0` ([f1e8084](https://github.com/wxt-dev/wxt/commit/f1e8084be89e512dde441b9197a99183c497f67d))

@@ -1030,8 +1652,8 @@
 - **deps-dev:** Bump vitest from 0.34.1 to 0.34.3 ([#99](https://github.com/wxt-dev/wxt/pull/99))
 - Increase E2E test timeout because GitHub Actions Window runner is slow ([2a0842b](https://github.com/wxt-dev/wxt/commit/2a0842b))
 - **deps-dev:** Bump vitepress from 1.0.0-rc.4 to 1.0.0-rc.10 ([#96](https://github.com/wxt-dev/wxt/pull/96))
- Fix test watcher restarting indefinetly ([2c7922c](https://github.com/wxt-dev/wxt/commit/2c7922c))
- Remove explict icon config from templates ([93bfee0](https://github.com/wxt-dev/wxt/commit/93bfee0))
+- Fix test watcher restarting indefinitely ([2c7922c](https://github.com/wxt-dev/wxt/commit/2c7922c))
+- Remove explicit icon config from templates ([93bfee0](https://github.com/wxt-dev/wxt/commit/93bfee0))
 - Use import aliases in Vue template ([#104](https://github.com/wxt-dev/wxt/pull/104))

 #### ⚠️ Breaking Changes
@@ -1091,7 +1713,7 @@
 - Branding and logo ([#60](https://github.com/wxt-dev/wxt/pull/60))
 - Simplify binary setup ([#62](https://github.com/wxt-dev/wxt/pull/62))
 - Add Solid template ([#63](https://github.com/wxt-dev/wxt/pull/63))
- Increate E2E test timeout to fix flakey test ([dfe424f](https://github.com/wxt-dev/wxt/commit/dfe424f))
+- Increase E2E test timeout to fix flakey test ([dfe424f](https://github.com/wxt-dev/wxt/commit/dfe424f))

 ### 🤖 CI

@@ -1367,7 +1989,7 @@ Initial release of WXT. Full support for production builds and initial toolkit f
 - Export and bootstrap the `/client` package ([5b07c95](https://github.com/wxt-dev/wxt/commit/5b07c95))
 - Resolve entrypoints based on filesystem ([a63f061](https://github.com/wxt-dev/wxt/commit/a63f061))
 - Separate output directories for each browser/manifest version ([f09ffbb](https://github.com/wxt-dev/wxt/commit/f09ffbb))
- Build entrypoints and output `manfiest.json` ([1e7c738](https://github.com/wxt-dev/wxt/commit/1e7c738))
+- Build entrypoints and output `manifest.json` ([1e7c738](https://github.com/wxt-dev/wxt/commit/1e7c738))
 - Automatically add CSS files to content scripts ([047ce04](https://github.com/wxt-dev/wxt/commit/047ce04))
 - Download and bundle remote URL imports ([523c7df](https://github.com/wxt-dev/wxt/commit/523c7df))
 - Generate type declarations and config for project types and auto-imports ([21debad](https://github.com/wxt-dev/wxt/commit/21debad))
@@ -108,7 +108,7 @@ Then run `npm i` again.
 To add a template, copy the vanilla template and give it a new name.

 ```sh
-cp -r templates/vailla templates/<new-template-name>
+cp -r templates/vanilla templates/<new-template-name>
 ```

 That's it. Once your template is merged, it will be available inside `wxt init` immediately. You don't need to release a new version of WXT to release a new template.
@@ -35,14 +35,14 @@

 ## Demo

-https://github.com/wxt-dev/wxt/assets/10101283/07359e53-f491-43b6-8e8f-fae94aec8063
+https://github.com/wxt-dev/wxt/assets/10101283/4d678939-1bdb-495c-9c36-3aa281d84c94

 ## Quick Start

 Bootstrap a new project:

 ```sh
-pnpx wxt@latest init <project-name>
+pnpm dlx wxt@latest init <project-name>
 ```

 Or see the [installation guide](https://wxt.dev/guide/installation.html) to get started with WXT.
@@ -55,14 +55,11 @@ Or see the [installation guide](https://wxt.dev/guide/installation.html) to get
 - 📂 File based entrypoints
 - 🚔 TypeScript
 - 🦾 Auto-imports
- ⬇️ Download and bundle remote URL imports
+- 🤖 Automated publishing
 - 🎨 Frontend framework agnostic: works with Vue, React, Svelte, etc
 - 🖍️ Quickly bootstrap a new project
 - 📏 Bundle analysis
-
-### Coming Soon
-
- 🤖 Automated publishing
+- ⬇️ Download and bundle remote URL imports

 ## Contributors

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * A alias around `publish-extension` that is always installed on the path without having to install
+ * `publish-browser-extension` as a direct dependency (like for PNPM, which doesn't link
+ * sub-dependency binaries to "node_modules/.bin")
+ */
+require('publish-browser-extension/cli');
@@ -19,7 +19,7 @@
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
-    "vitest": "^1.1.0"
+    "vitest": "^1.2.2"
  },
  "devDependencies": {
    "@types/react": "^18.2.34",
@@ -1,37 +1,42 @@
-import messages from 'public/_locales/en/messages.json';
+import messages from '~/public/_locales/en/messages.json';

-export default defineBackground(() => {
-  console.log(browser.runtime.id);
-  logId();
-  console.log({
-    browser: import.meta.env.BROWSER,
-    chrome: import.meta.env.CHROME,
-    firefox: import.meta.env.FIREFOX,
-    manifestVersion: import.meta.env.MANIFEST_VERSION,
-    messages,
-  });
+export default defineBackground({
+  // type: 'module',

-  // @ts-expect-error: should only accept entrypoints or public assets
-  browser.runtime.getURL('/');
-  browser.runtime.getURL('/background.js');
-  browser.runtime.getURL('/icon/128.png');
-  browser.runtime.getURL('/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');
+  main() {
+    console.log(browser.runtime.id);
+    logId();
+    console.log({
+      url: import.meta.url,
+      browser: import.meta.env.BROWSER,
+      chrome: import.meta.env.CHROME,
+      firefox: import.meta.env.FIREFOX,
+      manifestVersion: import.meta.env.MANIFEST_VERSION,
+      messages,
+    });

-  // @ts-expect-error: should only accept known message names
-  browser.i18n.getMessage('test');
-  browser.i18n.getMessage('prompt_for_name');
-  browser.i18n.getMessage('hello', 'Aaron');
-  browser.i18n.getMessage('bye', ['Aaron']);
-  browser.i18n.getMessage('@@extension_id');
+    // @ts-expect-error: should only accept entrypoints or public assets
+    browser.runtime.getURL('/');
+    browser.runtime.getURL('/background.js');
+    browser.runtime.getURL('/icon/128.png');
+    browser.runtime.getURL('/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');

-  console.log('WXT MODE:', {
-    MODE: import.meta.env.MODE,
-    DEV: import.meta.env.DEV,
-    PROD: import.meta.env.PROD,
-  });
+    // @ts-expect-error: should only accept known message names
+    browser.i18n.getMessage('test');
+    browser.i18n.getMessage('prompt_for_name');
+    browser.i18n.getMessage('hello', 'Aaron');
+    browser.i18n.getMessage('bye', ['Aaron']);
+    browser.i18n.getMessage('@@extension_id');

-  storage.setItem('session:startTime', Date.now());
+    console.log('WXT MODE:', {
+      MODE: import.meta.env.MODE,
+      DEV: import.meta.env.DEV,
+      PROD: import.meta.env.PROD,
+    });
+
+    storage.setItem('session:startTime', Date.now());
+  },
 });
@@ -12,7 +12,10 @@ export default defineConfig({
      },
    ],
  },
-  alias: {
-    public: 'src/public',
+  zip: {
+    downloadPackages: ['sass'],
+  },
+  analysis: {
+    open: true,
  },
 });
@@ -17,13 +17,19 @@ const chromeExtensionIds = [
  'okifoaikfmpfcamplcfjkpdnhfodpkil', // Doozy: Ai Made Easy
  'lknmjhcajhfbbglglccadlfdjbaiifig', // tl;dv - Record, Transcribe & ChatGPT for Google Meet
  'youtube中文配音/oglffgiaiekgeicdgkdlnlkhliajdlja', // Youtube中文配音
+  'agjnjboanicjcpenljmaaigopkgdnihi', // PreMiD
+  'aiakblgmlabokilgljkglggnpflljdgp', // Markdown Sticky Notes
+  'nomnkbngkijpffepcgbbofhcnafpkiep', // DocVersionRedirector
+  'ceicccfeikoipigeghddpocceifjelph', // Plex Skipper
+  'aelkipgppclpfimeamgmlonimflbhlgf', // GitHub Custom Notifier
 ];

-const { data } = useListExtensionDetails(chromeExtensionIds);
+const { data, err, isLoading } = useListExtensionDetails(chromeExtensionIds);
 const sortedExtensions = computed(() => {
  if (!data.value?.length) return [];

  return [...data.value]
+    .filter((item) => item != null)
    .map((item) => ({
      ...item,
      // Sort based on the user count weighted by the rating
@@ -48,7 +54,16 @@ function getStoreUrl(extension: ChromeExtension) {
        Battle tested and ready for production. Explore chrome extensions made
        with WXT.
      </p>
-      <ul>
+      <p v-if="isLoading" style="text-align: center; opacity: 50%">
+        Loading...
+      </p>
+      <p
+        v-else-if="err || sortedExtensions.length === 0"
+        style="text-align: center; opacity: 50%"
+      >
+        Failed to load extension details.
+      </p>
+      <ul v-else>
        <li
          v-for="extension of sortedExtensions"
          :key="extension.id"
@@ -26,6 +26,7 @@ const query = `query ${operationName}($ids:[String!]!) {
 export default function (ids: string[]) {
  const data = ref<ChromeExtension[]>();
  const err = ref<unknown>();
+  const isLoading = ref(true);

  fetch('https://queue.wxt.dev/api', {
    method: 'POST',
@@ -36,6 +37,7 @@ export default function (ids: string[]) {
    }),
  })
    .then(async (res) => {
+      isLoading.value = false;
      const {
        data: { chromeExtensions },
      } = await res.json();
@@ -43,6 +45,7 @@ export default function (ids: string[]) {
      err.value = undefined;
    })
    .catch((error) => {
+      isLoading.value = false;
      console.error(error);
      data.value = undefined;
      err.value = error;
@@ -51,5 +54,6 @@ export default function (ids: string[]) {
  return {
    data,
    err,
+    isLoading,
  };
 }
@@ -19,7 +19,7 @@ const title = 'Next-gen Web Extension Framework';
 const titleSuffix = ' – WXT';

 const description =
-  "WXT provides the best developer experience, making it quick, easy, and fun to develop chrome extensions for all browsers. With built-in utilties for building, zipping, and publishing your extension, it's easy to get started.";
+  "WXT provides the best developer experience, making it quick, easy, and fun to develop chrome extensions for all browsers. With built-in utilities for building, zipping, and publishing your extension, it's easy to get started.";
 const ogTitle = `${title}${titleSuffix}`;
 const ogUrl = 'https://wxt.dev';
 const ogImage = 'https://wxt.dev/social-preview.png';
@@ -90,6 +90,7 @@ export default defineConfig({
            { text: 'Assets', link: '/guide/assets.md' },
            { text: 'Content Script UI', link: '/guide/content-script-ui.md' },
            { text: 'Multiple Browsers', link: '/guide/multiple-browsers.md' },
+            { text: 'ES Modules', link: '/guide/esm.md' },
            { text: 'Auto-imports', link: '/guide/auto-imports.md' },
            { text: 'Vite', link: '/guide/vite.md' },
            { text: 'Remote Code', link: '/guide/remote-code.md' },
@@ -123,7 +124,7 @@ export default defineConfig({
            { text: 'Options', link: '/entrypoints/options.md' },
            { text: 'Popup', link: '/entrypoints/popup.md' },
            { text: 'Sandbox', link: '/entrypoints/sandbox.md' },
-            { text: 'Sidepanel', link: '/entrypoints/sidepanel.md' },
+            { text: 'Side Panel', link: '/entrypoints/sidepanel.md' },
            { text: 'Unlisted Pages', link: '/entrypoints/unlisted-pages.md' },
            {
              text: 'Unlisted Scripts',
@@ -32,14 +32,20 @@ export function generateCliDocs() {
        '```',
      ];

-      const commands = await Promise.all(
+      const commands = await Promise.allSettled(
        extractCommands(dev.info).map(async (command) => {
          const res = await execaCommand(`pnpm -s wxt ${command} --help`);
          const { rest: docs } = splitInfo(res.stdout);
          return [`## \`wxt ${command}\``, '```sh', docs, '```'];
        }),
      );
-      lines.push(...commands);
+      lines.push(
+        ...commands
+          .filter((res) => res.status === 'fulfilled')
+          .map(
+            (res) => (res as unknown as PromiseFulfilledResult<string>).value,
+          ),
+      );

      const text = await format(
        PREFACE +
@@ -16,7 +16,7 @@ For MV2, the background is added as a script to the background page. For MV3, th
 ## Definition

 :::warning
-The main function of the background **_CANNOT BE ASYNC_**. Event listeners must be added syncronously on background startup. If your main function returns a promise, WXT will log an error.
+The main function of the background **_CANNOT BE ASYNC_**. Event listeners must be added synchronously on background startup. If your main function returns a promise, WXT will log an error.
 :::

 ```ts
@@ -37,6 +37,9 @@ export default defineContentScript({
  // Configure how CSS is injected onto the page
  cssInjectionMode: undefined | "manifest" | "manual" | "ui",

+  // Configure how/when content script will be registered
+  registration: undefined | "manifest" | "runtime",
+
  main(ctx) {
    // Executed when content script is loaded
  },
@@ -49,9 +52,11 @@ When defining multiple content scripts, content script entrypoints that have the

 ## Context

-Old content scripts are not automatically stopped when an extension updates and reloads. Often, this leads to "Invalidated context" errors in production when a content script from an old version of your extension tries to use a extension API.
+Old content scripts are not automatically stopped when an extension updates and reloads. Often, this leads to "Invalidated context" errors in production when a content script from an old version of your extension tries to use a web extension API (ie, the `browser` or `chrome` globals).

-WXT provides a utility for managing this process: `ContentScriptContext`. An instance of this class is provided to you automatically inside the `main` function of your content script.
+WXT provides a utility for handling this process: `ContentScriptContext`. An instance of this class is provided to you automatically inside the `main` function of your content script.
+
+When your extension updates or is uninstalled, the context will become invalidated, and will trigger any `ctx.onInvalidated` listeners you add:

 ```ts
 export default defineContentScript({
@@ -62,26 +67,33 @@ export default defineContentScript({
      // ...
    });

-    // Stop fetch requests
-    fetch('...url', { signal: ctx.signal });
-
-    // Timeout utilities
+    // Timeout utilities that are automatically cleared when invalidated
    ctx.setTimeout(() => {
      // ...
    }, 5e3);
    ctx.setInterval(() => {
      // ...
    }, 60e3);
+
+    // Or add event listeners that get removed when invalidated
+    ctx.addEventListener(document, 'visibilitychange', (event) => {
+      // ...
+    });
+
+    // You can also stop fetch requests
+    fetch('...url', { signal: ctx.signal });
  },
 });
 ```

 The class extends [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) and provides other utilities for stopping a content script's logic once it becomes invalidated.

-:::tip
+:::warning
 When working with content scripts, **you should always use the `ctx` object to stop any async or future work.**

 This prevents old content scripts from interfering with new content scripts, and prevents error messages from the console in production.
+
+If you're using a framework like React, Vue, Svelte, etc., make sure you're unmounting your UI properly in the `onRemove` option of [`createShadowRootUi`](https://wxt.dev/guide/content-script-ui.html#shadow-root).
 :::

 ## CSS
@@ -2,7 +2,7 @@

 WXT can build CSS entrypoints individually. CSS entrypoints are always unlisted.

-See [Content Script CSS](/entrypoints/content-scripts#css) documentation for the recomended approach to include CSS with a content script.
+See [Content Script CSS](/entrypoints/content-scripts#css) documentation for the recommended approach to include CSS with a content script.

 :::info
 If the recommended approach doesn't work for your use case, you can use any of the filename patterns below to build the styles separate from the JS and use the [`transformManifest` hook](/api/wxt/interfaces/InlineConfig#transformmanifest) to manually add your CSS file to the manifest.
@@ -2,8 +2,10 @@

 [Chrome Docs](https://developer.chrome.com/docs/extensions/reference/sidePanel/) &bull; [Firefox Docs](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Sidebars)

+In Chrome, side panels use the "side_panel" API, while Firefox uses the "sidebar_action" API.
+
 :::warning
-Chrome added support for sidepanels in Manifest V3, they are not available in Manfiest V2.
+Chrome added support for sidepanels in Manifest V3, they are not available in Manifest V2.
 :::

 ## Filenames
@@ -25,7 +27,17 @@ Chrome added support for sidepanels in Manifest V3, they are not available in Ma
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Title</title>
+    <title>Default Side Panel Title</title>
+    <meta
+      name="manifest.default_icon"
+      content="{
+        16: '/icon-16.png',
+        24: '/icon-24.png',
+        ...
+      }"
+    />
+    <meta name="manifest.open_at_install" content="true|false" />
+    <meta name="manifest.browser_style" content="true|false" />
    <!-- Set include/exclude if the page should be removed from some builds -->
    <meta name="manifest.include" content="['chrome', ...]" />
    <meta name="manifest.exclude" content="['chrome', ...]" />
@@ -2,6 +2,8 @@

 HTML pages that are bundled and shipped with the extension, but are not included in the manifest.

+If you plan on using the page in an iframe, don't forget to add the page to [`web_accessible_resources`](https://developer.chrome.com/docs/extensions/reference/manifest/web-accessible-resources).
+
 ### Examples

 - Onboarding
@@ -2,7 +2,7 @@

 TypeScript files that are bundled and shipped with the extension, but are not included in the manifest.

-You are responsible for loading/running these scripts where needed.
+You are responsible for loading/running these scripts where needed. If necessary, don't forget to add the script and/or any related stylesheets to [`web_accessible_resources`](https://developer.chrome.com/docs/extensions/reference/manifest/web-accessible-resources).

 ## Filenames

@@ -65,7 +65,7 @@ import { defineConfig } from 'wxt';

 export default defineConfig({
  imports: {
-    // Add auto-imports for vue fuctions like createApp, ref, computed, watch, toRaw, etc...
+    // Add auto-imports for vue functions like createApp, ref, computed, watch, toRaw, etc...
    presets: ['vue'],
  },
 });
@@ -1,46 +1,47 @@
 # Compare

-Lets compare the features of WXT vs [Plasmo](https://docs.plasmo.com/framework), another web extension framework.
+Lets compare the features of WXT vs [Plasmo](https://docs.plasmo.com/framework) (another web extension framework) and [CRXJS](https://crxjs.dev/vite-plugin) (the most popular bundler plugin).

 ## Overview

-| Features                                             |             WXT             |                  Plasmo                  |
-| ---------------------------------------------------- | :-------------------------: | :--------------------------------------: |
-| Supports all browsers                                |             ✅              |                    ✅                    |
-| MV2 Support                                          |             ✅              |                    ✅                    |
-| MV3 Support                                          |             ✅              |                    ✅                    |
-| Create Extension ZIPs                                |             ✅              |                    ✅                    |
-| Create Firefox Sources ZIP                           |             ✅              |                    ❌                    |
-| First-class TypeScript support                       |             ✅              |                    ✅                    |
-| File based entrypoint discovery                      |             ✅              |                    ✅                    |
-| Inline entrypoint config                             |             ✅              |                    ✅                    |
-| Auto-imports                                         |             ✅              |                    ❌                    |
-| Supports all frontend frameworks                     |             ✅              |      🟡 Only React, Vue, and Svelte      |
-| Framework specific entrypoints (like `Popup.tsx`)    |   🟡 `.html` `.ts` `.tsx`   | ✅ `.html` `.ts` `.tsx` `.vue` `.svelte` |
-| Automated publishing                                 |       🟡 Coming soon        |                    ✅                    |
-| Remote Code Bundling (Google Analytics)              |             ✅              |                    ✅                    |
+| Features                                             |             WXT             |                  Plasmo                  |                                  CRXJS                                  |
+| ---------------------------------------------------- | :-------------------------: | :--------------------------------------: | :---------------------------------------------------------------------: |
+| Supports all browsers                                |             ✅              |                    ✅                    | ❌ See [#56](https://github.com/crxjs/chrome-extension-tools/issues/56) |
+| MV2 Support                                          |             ✅              |                    ✅                    |                          🟡 Either MV2 or MV3                           |
+| MV3 Support                                          |             ✅              |                    ✅                    |                          🟡 Either MV2 or MV3                           |
+| Create Extension ZIPs                                |             ✅              |                    ✅                    |                                   ❌                                    |
+| Create Firefox Sources ZIP                           |             ✅              |                    ❌                    |                                   ❌                                    |
+| First-class TypeScript support                       |             ✅              |                    ✅                    |                                   ✅                                    |
+| Entrypoint discovery                                 |         File based          |                File based                |                                   ❌                                    |
+| Inline entrypoint config                             |             ✅              |                    ✅                    |                             Manifest based                              |
+| Auto-imports                                         |             ✅              |                    ❌                    |                                   ❌                                    |
+| Supports all frontend frameworks                     |             ✅              |      🟡 Only React, Vue, and Svelte      |                                   ✅                                    |
+| Framework specific entrypoints (like `Popup.tsx`)    |   🟡 `.html` `.ts` `.tsx`   | ✅ `.html` `.ts` `.tsx` `.vue` `.svelte` |                                   ❌                                    |
+| Automated publishing                                 |             ✅              |                    ✅                    |                                   ❌                                    |
+| Remote Code Bundling (Google Analytics)              |             ✅              |                    ✅                    |                                   ❌                                    |
 | <strong style="opacity: 50%">Dev Mode</strong>       |                             |                                          |
-| `.env` Files                                         |             ✅              |                    ✅                    |
-| Opens browser and install extension                  |             ✅              |                    ❌                    |
-| HMR for UIs                                          |             ✅              |              🟡 React only               |
-| Reload HTML Files on Change                          |             ✅              |       🟡 Reloads entire extension        |
-| Reload Content Scripts on Change                     |             ✅              |       🟡 Reloads entire extension        |
-| Reload Background on Change                          | 🟡 Reloads entire extension |       🟡 Reloads entire extension        |
-| <strong style="opacity: 50%">Built-in Utils</strong> |                             |                                          |
-| Storage                                              |             ✅              |                    ✅                    |
-| Messaging                                            |       🟡 Coming soon        |                    ✅                    |
-| Content Script UI                                    |             ✅              |                    ✅                    |
+| `.env` Files                                         |             ✅              |                    ✅                    |                                   ✅                                    |
+| Opens browser and install extension                  |             ✅              |                    ❌                    |                                   ❌                                    |
+| HMR for UIs                                          |             ✅              |              🟡 React only               |                                   ✅                                    |
+| Reload HTML Files on Change                          |             ✅              |       🟡 Reloads entire extension        |                                   ✅                                    |
+| Reload Content Scripts on Change                     |             ✅              |       🟡 Reloads entire extension        |                                   ✅                                    |
+| Reload Background on Change                          | 🟡 Reloads entire extension |       🟡 Reloads entire extension        |                       🟡 Reloads entire extension                       |
+| Respects Content Script `run_at`                     |             ✅              |                    ✅                    |                 ❌ ESM-style loaders run asynchronously                 |
+| <strong style="opacity: 50%">Built-in Utils</strong> |                             |                                          |                                                                         |
+| Storage                                              |             ✅              |                    ✅                    |                                   ❌                                    |
+| Messaging                                            |             ❌              |                    ✅                    |                                   ❌                                    |
+| Content Script UI                                    |             ✅              |                    ✅                    |                                   ❌                                    |

-## Dev Mode
+## Why use WXT?

-WXT's main goal is improving the development experience (DX) of creating web extensions. There are two things WXT does differently:
+WXT's main goal is improving the development experience (DX) of creating web extensions, while not sacrificing support. There are two things WXT does differently:

 1. Automatically opens a browser with the extension installed when starting development
 2. Reload each part of the extension individually rather than reloading the entire extension

 Opening a browser automatically makes it super easy to start and stop development without having to manually load the extension in your browser.

-Reloading each part of the extension individually improves your iteration speed while developing UIs. This is because reloading the entire extension on every change will close the popup and any tabs open to an extension page, like options. If you save a file associated with a UI and a content script while working on the UI, it will randomly close because it needed to reload the extension when the content script changed. This interupts your development flow and is really annoying.
+Reloading each part of the extension individually improves your iteration speed while developing UIs. This is because reloading the entire extension on every change will close the popup and any tabs open to an extension page, like options. If you save a file associated with a UI and a content script while working on the UI, it will randomly close because it needed to reload the extension when the content script changed. This interrupts your development flow and is really annoying.

 WXT solves this problem by reloading HTML pages and content scripts individually (when possible) to keep your UIs open while you develop them. This is a MV3 feature, so if you're developing a MV2 extension, you'll get the same dev experience as Plasmo.

@@ -1,6 +1,6 @@
 # Configuration

-WXT's behavior can be configured via the `wxt.config.ts` file. In this file, you can add Vite plugins, change the directory strucutre of your project, and set fields on your `manifest.json`.
+WXT's behavior can be configured via the `wxt.config.ts` file. In this file, you can add Vite plugins, change the directory structure of your project, and set fields on your `manifest.json`.

 ## Config File

@@ -26,7 +26,6 @@ export default defineContentScript({
  main(ctx) {
    const ui = createIntegratedUi(ctx, {
      position: 'inline',
-      anchor: '#anchor',
      onMount: (container) => {
        // Append children to the container
        const app = document.createElement('p');
@@ -52,7 +51,6 @@ export default defineContentScript({
  main(ctx) {
    const ui = createIntegratedUi(ctx, {
      position: 'inline',
-      anchor: '#anchor',
      onMount: (container) => {
        // Create the app and mount it to the UI container
        const app = createApp(App);
@@ -82,7 +80,6 @@ export default defineContentScript({
  main(ctx) {
    const ui = createIntegratedUi(ctx, {
      position: 'inline',
-      anchor: '#anchor',
      onMount: (container) => {
        // Create a root on the UI container and render a component
        const root = ReactDOM.createRoot(container);
@@ -111,7 +108,6 @@ export default defineContentScript({
  main(ctx) {
    const ui = createIntegratedUi(ctx, {
      position: 'inline',
-      anchor: '#anchor',
      onMount: (container) => {
        // Create the Svelte app inside the UI container
        const app = new App({
@@ -141,7 +137,6 @@ export default defineContentScript({
  main(ctx) {
    const ui = createIntegratedUi(ctx, {
      position: 'inline',
-      anchor: '#anchor',
      onMount: (container) => {
        // Render your app to the UI container
        const unmount = render(() => <div>...</div>, container);
@@ -162,7 +157,7 @@ export default defineContentScript({

 See the [API Reference](/api/wxt/client/functions/createIntegratedUi) for the complete list of options.

-You can control how CSS is injected for an integrated content script UI with the [`cssInjectionMode`](/api/wxt/interfaces/ContentScriptBaseDefinition#cssinjectionmode) property. Usually, you'll want to leave it as `"manifest"`, the default, so the UI inherits its style from the website's CSS.
+You can control how CSS is injected for an integrated content script UI with the [`cssInjectionMode`](/api/wxt/interfaces/BaseContentScriptEntrypointOptions#cssinjectionmode) property. Usually, you'll want to leave it as `"manifest"`, the default, so the UI inherits its style from the website's CSS.

 ## Shadow Root

@@ -173,7 +168,7 @@ WXT's [`createShadowRootUi`](/api/wxt/client/functions/createShadowRootUi) abstr
 To use `createShadowRootUi`, follow these steps:

 1. Import your CSS file at the top of your content script
-2. Set [`cssInjectionMode: "ui"`](/api/wxt/interfaces/ContentScriptBaseDefinition#cssinjectionmode) inside `defineContentScript`
+2. Set [`cssInjectionMode: "ui"`](/api/wxt/interfaces/BaseContentScriptEntrypointOptions#cssinjectionmode) inside `defineContentScript`
 3. Define your UI with `createShadowRootUi()`
 4. Mount the UI so it is visible to users

@@ -192,7 +187,6 @@ export default defineContentScript({
    // 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
@@ -223,7 +217,6 @@ export default defineContentScript({
    // 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
@@ -233,7 +226,7 @@ export default defineContentScript({
      },
      onRemove: (app) => {
        // Unmount the app when the UI is removed
-        app.unmount();
+        app?.unmount();
      },
    });

@@ -259,16 +252,19 @@ export default defineContentScript({
    const ui = await createShadowRootUi(ctx, {
      name: 'example-ui',
      position: 'inline',
-      anchor: '#anchor',
      onMount: (container) => {
+        // Container is a body, and React warns when creating a root on the body, so create a wrapper div
+        const app = document.createElement('div');
+        container.append(app);
+
        // Create a root on the UI container and render a component
-        const root = ReactDOM.createRoot(container);
+        const root = ReactDOM.createRoot(app);
        root.render(<App />);
        return root;
      },
      onRemove: (root) => {
        // Unmount the root when the UI is removed
-        root.unmount();
+        root?.unmount();
      },
    });

@@ -293,7 +289,6 @@ export default defineContentScript({
    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({
@@ -303,7 +298,7 @@ export default defineContentScript({
      },
      onRemove: (app) => {
        // Destroy the app when the UI is removed
-        app.$destroy();
+        app?.$destroy();
      },
    });

@@ -328,14 +323,13 @@ export default defineContentScript({
    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();
+        unmount?.();
      },
    });

@@ -374,7 +368,7 @@ WXT provides a helper function, [`createIframeUi`](/api/wxt/client/functions/cre
     </body>
   </html>
   ```
-1. Add the page to the manifest's `web_accessible_resouces`
+1. Add the page to the manifest's `web_accessible_resources`
   ```ts
   // wxt.config.ts
   export default defineConfig({
@@ -398,7 +392,6 @@ WXT provides a helper function, [`createIframeUi`](/api/wxt/client/functions/cre
       // Define the UI
       const ui = await createIframeUi(ctx, {
         page: '/example-iframe.html',
-         anchor: '#anchor',
         position: 'inline',
         onMount: (wrapper, iframe) => {
           // Add styles to the iframe like width
@@ -13,6 +13,24 @@ WXT's main goal is providing the best DX it possibly can. When running your exte
 | `wxt.config.ts`     |     |                       |                  | 🟡 See [#10](https://github.com/wxt-dev/wxt/issues/10) |
 | `web-ext.config.ts` |     |                       |                  | 🟡 See [#10](https://github.com/wxt-dev/wxt/issues/10) |

+## Dev Mode vs Production Builds
+
+There are some notable differences between the development and production versions of an extension. During development:
+
+1. **Content scripts are not listed in the `manifest.json`** when targeting MV3. Instead, the [`scripting`](https://developer.chrome.com/docs/extensions/reference/api/scripting) permission is used to register content scripts at runtime so they can be reloaded individually.
+
+   To get the list of content scripts during development, run the following in the background's console:
+
+   ```ts
+   await chrome.scripting.getRegisteredContentScripts();
+   ```
+
+2. **The CSP is modified to allow loading scripts from the dev server**. Make sure you're using Chrome v110 or above for HMR to work.
+
+3. If you don't include a background script/service worker, one will be created to perform various tasks in dev mode, mostly related to reloading different parts of the extension on change.
+
+For production builds, none of the above modifications will be applied, and you're extension/manifest will only include what you have defined.
+
 ## Configure Browser Startup

 WXT uses [`web-ext` by Mozilla](https://github.com/mozilla/web-ext) to automatically open a browser with the extension installed. You can configure the runner's behavior via the [`runner`](/api/wxt/interfaces/InlineConfig#runner) option, or in a separate gitignored file, `web-ext.config.ts`.
@@ -41,7 +59,7 @@ export default defineRunnerConfig({

 ### Browser Binaries

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

 ```ts
 // ~/web-ext.config.ts
@@ -81,8 +99,18 @@ For a full list of options, see the [API Reference](/api/wxt/interfaces/Extensio

 Normally, to manually reload an extension, you have to visit `chrome://extensions` and click the reload button for your extension.

-When running `wxt` command to start the dev server, WXT adds a keyboard shortcut, `ctrl+E` for Windows/Linux and `cmd+E` for Mac, that reloads the extension when pressed, without visiting `chrome://extensions`.
+When running `wxt` command to start the dev server, WXT adds a keyboard shortcut `Alt+R`, that reloads the extension when pressed, without visiting `chrome://extensions`. This can also be customized or disabled:

-:::note
+```ts [wxt.config.ts]
+import { defineConfig } from 'wxt';
+
+export default defineConfig({
+  dev: {
+    reloadCommand: 'Alt+T', // false, to disable
+  },
+});
+```
+
+:::info
 This shortcut is only available during development, and is not be added to your extension when running `wxt build` or `wxt-zip`.
 :::
@@ -58,7 +58,7 @@ See [`/entrypoints` folder](/entrypoints/background) documentation for a full li

 ## Entrypoint Options

-Some entrypoints, like content scripts, actions, or the background, can recieve additional options.
+Some entrypoints, like content scripts, actions, or the background, can receive additional options.

 In HTML files, options are listed as `meta` tags:

@@ -114,11 +114,11 @@ WXT 0.14.1
 [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.
+This throws an error because WXT needs to import each entrypoint during the build process to extract its definition (containing the `match`, `runAt`, `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.
+When importing your entrypoint to get its definition, the file is imported in a **_node environment_**, and doesn't have access to the `window`, `chrome`, or `browser` globals a web extension usually 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.

 :::

@@ -126,7 +126,7 @@ When importing your entrypoint to get its definition, the file is imported in a
 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:
+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 literal values when defining an entrypoint instead of importing them:

 ```ts
 import { GOOGLE_MATCHES } from '~/utils/match-patterns'; // [!code --]
@@ -0,0 +1,38 @@
+# ES Modules
+
+Configure entrypoints to use ESM at runtime.
+
+Currently, ESM entrypoints are opt-in, so you must configure each entrypoint with that in mind.
+
+## HTML Pages <Badge type="warning" text="≥0.0.1" />
+
+In general, you should always make HTML pages import ESM scripts, unless you need to support old browsers.
+
+To make a script ESM, add `type="module"`:
+
+<!-- prettier-ignore -->
+```html
+<script src="./main.ts"></script> <!-- [!code --] -->
+<script src="./main.ts" type="module"></script> <!-- [!code ++] -->
+```
+
+## Background <Badge type="warning" text="≥0.16.0" />
+
+In your background script, set `type: "module"`:
+
+```ts
+export default defineBackground({
+  type: 'module', // !code ++
+  main() {
+    // ...
+  },
+});
+```
+
+:::warning
+Only MV3 support ESM background scripts/service workers. When targeting MV2, the `type` option is ignored and the background is always bundled into a single file as IIFE.
+:::
+
+## Content Scripts
+
+Coming soon. Follow [Content Script ESM Support #357](https://github.com/wxt-dev/wxt/issues/357) for updates.
@@ -57,21 +57,19 @@ Here's a basic request/response example:
 // popup/main.ts
 const res = await browser.runtime.sendMessage('ping');

-console.log('res'); // "pong"
+console.log(res); // "pong"
 ```

 ```ts
 // background.ts
 export default defineBackground(() => {
-  browser.runtime.onMessage.addEventListener(
-    (message, sender, sendResponse) => {
-      console.log(message); // "ping"
+  browser.runtime.onMessage.addListener((message, sender, sendResponse) => {
+    console.log(message); // "ping"

-      // Wait 1 second and respond with "pong"
-      setTimeout(() => sendResponse('pong'), 1000);
-      return true;
-    },
-  );
+    // Wait 1 second and respond with "pong"
+    setTimeout(() => sendResponse('pong'), 1000);
+    return true;
+  });
 });
 ```

@@ -7,13 +7,17 @@ Bootstrap a new project, start from scratch, or [migrate an existing project](/g
 :::code-group

 ```sh [pnpm]
-pnpx wxt@latest init <project-name>
+pnpm dlx wxt@latest init <project-name>
 ```

 ```sh [npm]
 npx wxt@latest init <project-name>
 ```

+```sh [bun]
+bunx wxt@latest init <project-name>
+```
+
 :::

 There are several starting templates available.
@@ -55,6 +59,12 @@ cd project-name
 yarn init
 ```

+```sh [bun]
+mkdir project-name
+cd project-name
+bun init
+```
+
 :::

 Then install `wxt`:
@@ -73,6 +83,10 @@ npm i --save-dev wxt
 yarn add --dev wxt
 ```

+```sh [bun]
+bun add --dev wxt
+```
+
 :::

 Add your first entrypoint:
@@ -102,7 +116,7 @@ Finally, add scripts to your `package.json`:

 ## Migrate an Existing Project

-Before starting the migration, it is recommended to run `pnpx wxt@latest init` to see what a basic project looks like. Once you have an understanding of how WXT projects are structured, you're ready to convert the project, using the initialized project as a reference.
+Before starting the migration, it is recommended to run `pnpm dlx wxt@latest init` to see what a basic project looks like. Once you have an understanding of how WXT projects are structured, you're ready to convert the project, using the initialized project as a reference.

 Migrating a project to WXT comes down to a few steps:

@@ -133,7 +147,7 @@ The dev command will build the extension for development, open the browser, and
 When running the dev command, WXT will make several changes to your `manifest.json` to improve your development experience:

 - If missing, add a background script/service worker to enable fast reloads
- Add serveral `permissions` and `host_permissions` to enable HMR and fast reloads
+- Add several `permissions` and `host_permissions` to enable HMR and fast reloads
 - Modify the CSP to allow connections with the dev server
 - Remove `content_scripts` and register them at runtime so they can be easily reloaded when you save a file

@@ -145,5 +159,6 @@ If you're an experienced web extension developer and think the dev manifest look
 You're ready to build your web extension!

 - Learn how to [add entrypoints](./entrypoints) like the popup, options page, or content scripts
+- Configure your entrypoints to [use ESM](./esm) at runtime
 - [Configure WXT](./configuration) by creating a `wxt.config.ts` file
- Checkout [example projects](https://github.com/wxt-dev/wxt-examples) to see how to perfom common tasks with WXT
+- Checkout [example projects](https://github.com/wxt-dev/wxt-examples) to see how to perform common tasks with WXT
@@ -7,7 +7,7 @@ head:

 # Introduction

-WXT is a free and open source framework for building web extensions in an conventional, intuative, and safe way **_for all browsers_**.
+WXT is a free and open source framework for building web extensions in an conventional, intuitive, and safe way **_for all browsers_**.

 WXT is based of [Nuxt](https://nuxt.com), and aims to provide the same great DX with TypeScript, auto-imports, and an opinionated project structure.

@@ -15,12 +15,12 @@ WXT is based of [Nuxt](https://nuxt.com), and aims to provide the same great DX

 ## Conventions

-WXT is an optionated framework. This helps keep projects consistent and easy to pick up.
+WXT is an opinionated framework. This helps keep projects consistent and easy to pick up.

 - **Generated manifest**: Based on your project's file structure
 - **Entrypoint configuration**: Configure entrypoints from the same file they're declare in
 - **Type-safety is a priority**: Out-of-the-box TypeScript support with improved browser API typing
- **Simple output file structure**: Ouptut file paths minimize the path at runtime
+- **Simple output file structure**: Output file paths minimize the path at runtime

 ## Development

@@ -1,3 +1,7 @@
+---
+outline: deep
+---
+
 # Manifest.json

 The manifest.json is generated at build-time based on files in the `entrypoints/` directory and `wxt.config.ts`.
@@ -20,11 +24,11 @@ export default defineConfig({
 });
 ```

-## `name`
+### `name`

 If not provided via the `manifest` config, the [manifest's `name`](https://developer.chrome.com/docs/extensions/mv3/manifest/name/) defaults to your package.json's `name` property.

-## `version` and `version_name`
+### `version` and `version_name`

 The [manifest's `version` and `version_name`](https://developer.chrome.com/docs/extensions/mv3/manifest/version/) properties are based on the `version` field listed in your `package.json` or `wxt.config.ts`.

@@ -33,7 +37,7 @@ The [manifest's `version` and `version_name`](https://developer.chrome.com/docs/

 If a version is not found, a warning is logged and the version defaults to `"0.0.0"`.

-### Example
+#### Example

 ```json
 // package.json
@@ -50,7 +54,7 @@ If a version is not found, a warning is logged and the version defaults to `"0.0
 }
 ```

-## `icons`
+### `icons`

 By default, WXT will discover icons in your [`public` directory](/guide/assets#public-directory) and use them for the [manifest's `icons`](https://developer.chrome.com/docs/extensions/mv3/manifest/icons/).

@@ -83,7 +87,7 @@ export default defineConfig({
 });
 ```

-## `permissions`
+### `permissions`

 [Permissions](https://developer.chrome.com/docs/extensions/reference/permissions/) must be listed in the manifest config.

@@ -125,3 +129,109 @@ export default defineConfig({
 See the official localization examples for more details:

 <ExampleList tag="i18n" />
+
+## Per-Manifest Version Config
+
+WXT applies several transformations to your manifest to simplify managing both MV2 and MV3 keys in your `wxt.config.ts` file:
+
+1. Top level MV2-only or MV3-only keys are stripped from the final manifest when targeting the other manifest version
+2. Some keys, are automatically converted between versions when possible:
+   - Define `web_accessible_resources` in it's MV3 style and it will be converted to the MV2 style automatically
+   - `action` will automatically be converted to `browser_action` for MV3. To use `page_action` instead, add both `action` and `page_action` entries to your manifest
+
+For example, a `wxt.config.ts` file that looks like this:
+
+```ts
+import { defineConfig } from 'wxt';
+
+export default defineConfig({
+  mainfest: {
+    action: {
+      default_title: 'Some Title',
+    },
+    web_accessible_resources: [
+      {
+        matches: ['*://*.google.com/*'],
+        resources: ['icon/*.png'],
+      },
+    ],
+  },
+});
+```
+
+Will be output differently for each manifest version:
+
+:::code-group
+
+```json [MV2]
+{
+  "manifest_version": 2,
+  // ...
+  "browser_action": {
+    "default_title": "Some Title"
+  },
+  "web_accessible_resources": ["icon/*.png"]
+}
+```
+
+```json [MV3]
+{
+  "manifest_version": 3,
+  // ...
+  "action": {
+    "default_title": "Some Title"
+  },
+  "web_accessible_resources": [
+    {
+      "matches": ["*://*.google.com/*"],
+      "resources": ["icon/*.png"]
+    }
+  ]
+}
+```
+
+:::
+
+:::tip
+If this isn't enough control for your use-case, remember you can use a function for the `manifest` key and generate it however you'd like, or you can use the `build:manifestGenerated` hook to apply additional transformations.
+:::
+
+## Per-Browser Configuration
+
+The `manifest` field can be a function. If you are building and extension for multiple browsers, and need to modify the manifest per browser, using a function instead of an object is very useful.
+
+```ts
+export default defineConfig({
+  manifest: ({ browser, manifestVersion, mode, command }) => {
+    return {
+      // Your manifest
+    };
+  },
+});
+```
+
+:::info
+The first argument is of type `ConfigEnv`. See the [API reference](/api/wxt/interfaces/ConfigEnv) for info about each property.
+:::
+
+For example, say you use OAuth, and you need to provide a different `oauth.client_id` for each browser:
+
+```ts
+const clientIds = {
+  chrome: '<your-chrome-client-id>',
+  edge: '<your-edge-client-id>',
+  firefox: '<your-firefox-client-id>',
+  opera: '<your-opera-client-id>',
+};
+
+export default defineConfig({
+  manifest: ({ browser }) => ({
+    oauth: {
+      client_id: clientIds[browser],
+      scopes: [
+        // ...
+      ],
+    },
+  }),
+});
+```
@@ -12,7 +12,7 @@ Always start by generating a new vanilla project and merging it into your projec

 ```sh
 cd path/to/your/project
-pnpx wxt@latest init example-wxt --template vanilla
+pnpm dlx wxt@latest init example-wxt --template vanilla
 ```

 In general, you'll need to:
@@ -32,7 +32,7 @@ Every project is different, so there's no one-solution-fits-all to migrating you

 ## Popular Tools/Frameworks

-Here's specific steps for other popuplar frameworks/build tools.
+Here's specific steps for other popular frameworks/build tools.

 ### `vite-plugin-web-extension`

@@ -1,6 +1,6 @@
 # Multiple Browsers

-You can build an extension for any combination of browser and manifest verison. Different browsers and manifest versions support different APIs and entrypoints, so be sure to check that your extension functions as expected for each target.
+You can build an extension for any combination of browser and manifest version. Different browsers and manifest versions support different APIs and entrypoints, so be sure to check that your extension functions as expected for each target.

 Separate build targets are written to their own output directories:

@@ -45,7 +45,7 @@ wxt --mv2
 wxt build --mv2
 ```

-When the `-b --browser` flag is not passed, it defaults to `chrome`. So here, we're targetting MV2 for Chrome.
+When the `-b --browser` flag is not passed, it defaults to `chrome`. So here, we're targeting MV2 for Chrome.

 ## Customizing Entrypoints

@@ -116,7 +116,7 @@ Only `defineBackground` and `defineContentScript` support per-browser options ri
 To determine the browser or manifest version at runtime, you can use any of the below variables:

 - `import.meta.env.BROWSER`: A string, the target browser, usually equal to the `--browser` flag
- `import.meta.env.MANIFEST_VERSION`: A number, either `2` or `3`, depending on the manifest version targetted
+- `import.meta.env.MANIFEST_VERSION`: A number, either `2` or `3`, depending on the manifest version targeted
 - `import.meta.env.CHROME`: A boolean equivalent to `import.meta.env.BROWSER === "chrome"`
 - `import.meta.env.FIREFOX`: A boolean equivalent to `import.meta.env.BROWSER === "firefox"`
 - `import.meta.env.EDGE`: A boolean equivalent to `import.meta.env.BROWSER === "edge"`
@@ -1,106 +1,127 @@
+---
+outline: deep
+---
+
 # Publishing

-WXT offers several utilities that simplify the publishing process.
+WXT will help you ZIP your extensions and submit them to the stores for review.

 ## First Time Publishing

-If you're publishing an extension to a store for the first time, you must manually navigate the process. Each store has unique steps and requirements that you need to familiarize yourself with.
+If you're publishing an extension to a store for the first time, you must manually navigate the process. WXT doesn't help you create listings, each store has unique steps and requirements that you need to familiarize yourself with.

-Each store requires that a ZIP file be uploaded. You can generate these using the `wxt zip` command:
+For specific details about each store, see the stores sections below.
+
+- [Chrome Web Store](#chrome-web-store)
+- [Firefox Addon Store](#firefox-addon-store)
+- [Edge Addons](#edge-addons)
+
+## Automation
+
+WXT provides two commands to help automate the release process:
+
+- `wxt submit`: Submit new versions of your extension for review (and publish them automatically once approved)
+- `wxt submit init`: Help setup all the required secrets and options for the `wxt submit` command
+
+To get started, run `wxt submit init` and follow the prompts. Once finished, you should have a `.env.submit` file! WXT will use this file to submit your updates.
+
+> In CI, make sure you add all the environment variables to the submit step.
+
+To release an update, build all the ZIPs you plan on releasing:

 ```sh
 wxt zip
 wxt zip -b firefox
-# etc
 ```

-Generated ZIP files are stored in the `.output` directory.
+Then run the `wxt submit` command, passing in all the ZIP files you want to release. In this case, we'll do a release for all 3 major stores: Chrome Web Store, Edge Addons, and Firefox Addons Store.

-## Automation
+If it's your first time running the command, you'll want to test your secrets by passing the `--dry-run` flag:

-To automate releasing updates, use the [`publish-browser-extension`](https://www.npmjs.com/package/publish-browser-extension) package.
+```sh
+wxt submit --dry-run \
+  --chrome-zip .output/<your-extension>-<version>-chrome.zip \
+  --firefox-zip .output/<your-extension>-<version>-firefox.zip --firefox-sources-zip .output/<your-extension>-<version>-sources.zip \
+  --edge-zip .output/<your-extension>-<version>-chrome.zip
+```

-:::info
-🚧 WXT plans to eventually incorporate the `publish-browser-extension` package into its own `wxt submit` command.
+If the dry run passes, remove the flag and do the actual release:
+
+```sh
+wxt submit \
+  --chrome-zip .output/<your-extension>-<version>-chrome.zip \
+  --firefox-zip .output/<your-extension>-<version>-firefox.zip --firefox-sources-zip .output/<your-extension>-<version>-sources.zip \
+  --edge-zip .output/<your-extension>-<version>-chrome.zip
+```
+
+:::tip
+If you only need to release to a single store, only pass that store's ZIP flag.
 :::

-1. Install the necessary dependencies:
-
-   ```sh
-   pnpm add -D publish-browser-extension env-cmd
-   ```
-
-2. Add scripts to your `package.json` file:
-
-   ```json
-   {
-     "scripts": {
-       "submit": "env-cmd -f .env.submit -- publish-extension",
-       "submit:dry": "env-cmd -f .env.submit -- publish-extension --dry-run"
-     }
-   }
-   ```
-
-3. Create a `.env.submit` file and include the code below. If you're not publishing to certain stores, simply ignore their respective variables.
-
-   ```txt
-   CHROME_EXTENSION_ID=""
-   CHROME_CLIENT_ID=""
-   CHROME_CLIENT_SECRET=""
-   CHROME_REFRESH_TOKEN=""
-
-   FIREFOX_EXTENSION_ID=""
-   FIREFOX_JWT_ISSUER=""
-   FIREFOX_JWT_SECRET=""
-
-   EDGE_PRODUCT_ID=""
-   EDGE_CLIENT_ID=""
-   EDGE_CLIENT_SECRET=""
-   EDGE_ACCESS_TOKEN_URL=""
-   ```
-
-   > Each value will be filled in during the next step.
-
-4. Run `npx publish-extension --help` for assistance with filling out all the values. Insert the obtained values within the double quotes.
-
-5. ZIP all the targets you plan to publish, in this case Chrome and Firefox.
-
-   ```sh
-   wxt zip
-   wxt zip -b firefox
-   ```
-
-6. Test your credentials by running the `submit:dry` command:
-
-   ```sh
-   pnpm submit:dry \
-     --chrome-zip .output/your-extension-X.Y.Z-chrome.zip \
-     --firefox-zip .output/your-extension-X.Y.Z-firefox.zip \
-     --firefox-sources-zip .output/your-extension-X.Y.Z-sources.zip \
-     --edge-zip .output/your-extension-X.Y.Z-chrome.zip
-   ```
-
-7. Upload and submit your extension for review:
-
-   ```sh
-   pnpm submit \
-     --chrome-zip .output/your-extension-X.Y.Z-chrome.zip \
-     --firefox-zip .output/your-extension-X.Y.Z-firefox.zip \
-     --firefox-sources-zip .output/your-extension-X.Y.Z-sources.zip \
-     --edge-zip .output/your-extension-X.Y.Z-chrome.zip
-   ```
+:::tip
+See the [Firefox Addon Store](#firefox-addon-store) section for more details about the `--firefox-sources-zip` option.
+:::

 ## GitHub Action

-Here's an example of a GitHub Action to automate submiting new versions of your extension for review. Ensure that you've added all required secrets used in the workflow to the repo's settings.
+Here's an example of a GitHub Action that submits new versions of an extension for review. Ensure that you've added all required secrets used in the workflow to the repo's settings.

 ```yml
-# TODO
+name: Release
+
+on:
+  workflow_dispatch:
+
+jobs:
+  submit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v3
+        with:
+          version: 'latest'
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Zip extensions
+        run: |
+          pnpm zip
+          pnpm zip:firefox
+
+      - name: Submit to stores
+        run: |
+          pnpm wxt submit \
+            --chrome-zip .output/*-chrome.zip \
+            --firefox-zip .output/*-firefox.zip --firefox-sources-zip .output/*-sources.zip
+        env:
+          CHROME_EXTENSION_ID: ${{ secrets.CHROME_EXTENSION_ID }}
+          CHROME_CLIENT_ID: ${{ secrets.CHROME_CLIENT_ID }}
+          CHROME_CLIENT_SECRET: ${{ secrets.CHROME_CLIENT_SECRET }}
+          CHROME_REFRESH_TOKEN: ${{ secrets.CHROME_REFRESH_TOKEN }}
+          FIREFOX_EXTENSION_ID: ${{ secrets.FIREFOX_EXTENSION_ID }}
+          FIREFOX_JWT_ISSUER: ${{ secrets.FIREFOX_JWT_ISSUER }}
+          FIREFOX_JWT_SECRET: ${{ secrets.FIREFOX_JWT_SECRET }}
 ```

-## Chrome Web Store
+The action above lays the foundation for a basic workflow, including `zip` and `submit` steps. To further enhance your GitHub Action and delve into more complex scenarios, consider exploring the following examples from real projects. They introduce advanced features such as version management, changelog generation, and GitHub releases, tailored for different needs:

-✅ Automated &bull; [Developer Dashboard](https://chrome.google.com/webstore/developer/dashboard) &bull; [Publishing Docs](https://developer.chrome.com/docs/webstore/publish/)
+- [`aklinker1/github-better-line-counts`](https://github.com/aklinker1/github-better-line-counts/blob/main/.github/workflows/submit.yml) - Conventional commits, automated version bump and changelog generation, triggered manually, optional dry run for testing
+- [`GuiEpi/plex-skipper`](https://github.com/GuiEpi/plex-skipper/blob/main/.github/workflows/deploy.yml) - Triggered automatically when `package.json` version is changed, creates and uploads artifacts to GitHub release.
+
+> These examples are designed to provide clear insights and are a good starting point for customizing your own workflows. Feel free to explore and adapt them to your project needs.
+
+## Stores
+
+### Chrome Web Store
+
+> ✅ Supported &bull; [Developer Dashboard](https://chrome.google.com/webstore/developer/dashboard) &bull; [Publishing Docs](https://developer.chrome.com/docs/webstore/publish/)

 To create a ZIP for Chrome:

@@ -108,15 +129,15 @@ To create a ZIP for Chrome:
 wxt zip
 ```

-## Firefox Addon Store
+### Firefox Addon Store

-✅ Automated &bull; [Developer Dashboard](https://addons.mozilla.org/developers/) &bull; [Publishing Docs](https://extensionworkshop.com/documentation/publish/submitting-an-add-on/)
+> ✅ Supported &bull; [Developer Dashboard](https://addons.mozilla.org/developers/) &bull; [Publishing Docs](https://extensionworkshop.com/documentation/publish/submitting-an-add-on/)

 Firefox requires you to upload a ZIP of your source code. This allows them to rebuild your extension and review the code in a readable way. More details can be found in [Firefox's docs](https://extensionworkshop.com/documentation/publish/source-code-submission/).

-WXT and `publish-browser-extension` both fully support generating and automatically submitting a source code ZIP.
+WXT fully supports generating and automatically submitting a source code ZIP.

-When you run `wxt zip -b firefox`, your sources are zipped into the `.output` directory along with your built extension. WXT is configured to exclude certain files such as config files, hidden files, and tests. However, it's important to manually check the ZIP to ensure it only contains the files necessary to rebuild your extension.
+When you run `wxt zip -b firefox`, your sources are zipped into the `.output` directory alongside the extension. WXT will automatically exclude certain files such as config files, hidden files, and tests. However, it's important to manually check the ZIP to ensure it only contains the files necessary to rebuild your extension.

 To customize which files are zipped, add the `zip` option to your config file.

@@ -150,24 +171,63 @@ yarn
 yarn zip:firefox
 ```

+```sh [bun]
+bun i
+bun zip:firefox
+```
+
+:::
+
+Make sure the build output is the exact same when running `wxt build -b firefox` in your main project and inside the zipped sources.
+
+:::warning
+If you use a `.env` files, they can effect the chunk hashes in the output directory. Either delete the .env file before running `wxt zip -b firefox`, or include it in your sources zip with the [`zip.includeSources`](/api/wxt/interfaces/InlineConfig#includesources) option. Be careful to not include any secrets in your `.env` files.
+
+See Issue [#377](https://github.com/wxt-dev/wxt/issues/377) for more details.
 :::

 Ensure that you have a `README.md` or `SOURCE_CODE_REVIEW.md` file with the above commands so that the Firefox team knows how to build your extension.

-## Safari
+#### Private Packages

-🚧 Not automated at this time
+If you use private packages and you don't want to provide your auth token to the Firefox team during the review process, you can use `zip.downloadPackages` to download any private packages and include them in the zip.
+
+```ts
+// wxt.config.ts
+export default defineConfig({
+  zip: {
+    downloadPackages: [
+      '@mycompany/some-package',
+      //...
+    ],
+  },
+});
+```
+
+Depending on your package manager, the `package.json` in the sources zip will be modified to use the downloaded dependencies via the `overrides` or `resolutions` field.

 :::warning
-🚧 WXT does not currently support automated publishing for Safari. Safari extensions require a native MacOS or iOS app wrapper, which WXT cannot create at this time. For now, if you want to publish to Safari, follow this guide:
-
-https://developer.apple.com/documentation/safariservices/safari_web_extensions/distributing_your_safari_web_extension
-
+WXT uses the command `npm pack <package-name>` to download the package. That means regardless of your package manager, you need to properly setup a `.npmrc` file. NPM and PNPM both respect `.npmrc` files, but Yarn and Bun have their own ways of authorizing private registries, so you'll need to add an `.npmrc` file.
 :::

-## Edge Addons
+### Safari

-✅ Automated &bull; [Developer Dashboard](https://aka.ms/PartnerCenterLogin) &bull; [Publishing Docs](https://learn.microsoft.com/en-us/microsoft-edge/extensions-chromium/publish/publish-extension)
+> 🚧 Not supported yet
+
+WXT does not currently support automated publishing for Safari. Safari extensions require a native MacOS or iOS app wrapper, which WXT does not create yet. For now, if you want to publish to Safari, follow this guide:
+
+- [Converting a web extension for Safari](https://developer.apple.com/documentation/safariservices/safari_web_extensions/converting_a_web_extension_for_safari) - "Convert your existing extension to a Safari web extension using Xcode’s command-line tool."
+
+When running the `safari-web-extension-converter` CLI tool, pass the `.output/safari-mv2` or `.output/safari-mv3` directory, not your source code directory.
+
+```sh
+pnpm wxt build -b safari
+xcrun safari-web-extension-converter .output/safari-mv2
+```
+
+### Edge Addons
+
+> ✅ Supported &bull; [Developer Dashboard](https://aka.ms/PartnerCenterLogin) &bull; [Publishing Docs](https://learn.microsoft.com/en-us/microsoft-edge/extensions-chromium/publish/publish-extension)

 No need to create a specific ZIP for Edge. If you're already publishing to the Chrome Web Store, you can reuse your Chrome ZIP.

@@ -1,3 +1,7 @@
+---
+outline: deep
+---
+
 # Storage API

 WXT provides a simplified API to replace the `browser.storage.*` APIs. Use the `storage` auto-import from `wxt/storage` or import it manually to get started:
@@ -35,6 +39,8 @@ await storage.watch<number>(
 await storage.getMeta<{ v: number }>('local:installDate');
 ```

+For a full list of methods available, see the [API reference](/api/wxt/storage/interfaces/WxtStorage).
+
 ## Watchers

 To listen for storage changes, use the `storage.watch` function. It lets you setup a listener for a single key:
@@ -58,7 +64,7 @@ unwatch();

 `wxt/storage` also supports setting metadata for keys, stored at `key + "$"`. Metadata is a collection of properties associated with a key. It might be a version number, last modified date, etc.

-[Other than versioning](#versioning-and-migrations), you are responsible for managing a field's metadata:
+[Other than versioning](#versioning), you are responsible for managing a field's metadata:

 ```ts
 await Promise.all([
@@ -116,7 +122,9 @@ const unwatch = showChangelogOnUpdate.watch(() => {
 });
 ```

-### Versioning and Migrations
+For a full list of properties and methods available, see the [API reference](/api/wxt/storage/interfaces/WxtStorageItem).
+
+### Versioning

 You can add versioning to storage items if you expect them to grow or change over time. When defining the first version of an item, start with version 1.

@@ -252,3 +260,7 @@ export const ignoredWebsites = storage.defineItem<IgnoredWebsiteV2[]>( // [!code
 ```

 :::
+
+### Running Migrations
+
+As soon as `storage.defineItem` is called, WXT checks if migrations need to be ran, and if so, runs them. Calls to get or update the storage item's value or metadata (`getValue`, `setValue`, `removeValue`, `getMeta`, etc) will automatically wait for the migration process to finish before actually reading or writing values.
@@ -6,7 +6,7 @@ title: Next-gen Web Extension Framework
 hero:
  name: WXT
  text: Next-gen Web Extension Framework
-  tagline: An open source tool that makes Chrome Extension devlopment faster than ever before.
+  tagline: An open source tool that makes Chrome Extension development faster than ever before.
  image:
    src: /hero-logo.svg
    alt: WXT
@@ -47,11 +47,9 @@ features:
    details: Nuxt-like auto-imports to speed up development.
    link: /guide/auto-imports
    linkText: Read docs
-  - icon: ⬇️
-    title: Bundle Remote Code
-    details: Downloads and bundles remote code imported from URLs.
-    link: /guide/remote-code
-    linkText: Read docs
+  - icon: 🤖
+    title: Automated Publishing
+    details: Automatically zip, upload, submit, and publish extensions.
  - icon: 🎨
    title: Frontend Framework Agnostic
    details: Works with any front-end framework with a Vite plugin.
@@ -64,20 +62,22 @@ features:
    linkText: See templates
  - icon: 📏
    title: Bundle Analysis
-    details: Tools for analyizing the final extension bundle and minimizing your extension's size.
-  - icon: 🤖
-    title: Automated Publishing
-    details: 'Coming soon. Automatically zip, upload, and release extensions.'
+    details: Tools for analyzing the final extension bundle and minimizing your extension's size.
+  - icon: ⬇️
+    title: Bundle Remote Code
+    details: Downloads and bundles remote code imported from URLs.
+    link: /guide/remote-code
+    linkText: Read docs
 ---

-<section class="vp-doc">
+<section class="vp-doc" style="padding: 0 48px">
  <div class="container">
    <h2>Put <span style="color: var(--vp-c-brand-1)">Developer Experience</span> First</h2>
    <p>
      WXT's simplifies the chrome extension development process by providing tools for zipping and publishing, the best-in-class dev mode, an opinionated project structure, and more. Iterate faster, develop features not build scripts, and use everything the JS ecosystem has to offer.
    </p>
    <div style="margin: auto; width: 100%; max-width: 900px; text-align: center">
-      <video src="https://github.com/wxt-dev/wxt/assets/10101283/b32e6766-ec11-45a4-9677-226ee4718e1c" controls></video>
+      <video src="https://github.com/wxt-dev/wxt/assets/10101283/4d678939-1bdb-495c-9c36-3aa281d84c94" controls></video>
      <br />
      <small>
        And who doesn't appreciate a beautiful CLI?
@@ -0,0 +1,120 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { TestProject } from '../utils';
+import { resetBundleIncrement } from '~/core/builders/vite/plugins';
+import open from 'open';
+
+vi.mock('open');
+const openMock = vi.mocked(open);
+
+vi.mock('ci-info', () => ({
+  isCI: false,
+}));
+
+describe('Analysis', () => {
+  beforeEach(() => {
+    resetBundleIncrement();
+  });
+
+  it('should output a stats.html with no part files by default', async () => {
+    const project = new TestProject();
+    project.addFile('entrypoints/popup.html');
+    project.addFile('entrypoints/options.html');
+    project.addFile(
+      'entrypoints/background.ts',
+      'export default defineBackground(() => {});',
+    );
+
+    await project.build({
+      analysis: {
+        enabled: true,
+      },
+    });
+
+    expect(await project.fileExists('stats.html')).toBe(true);
+    expect(await project.fileExists('.output/chrome-mv3/stats-0.json')).toBe(
+      false,
+    );
+  });
+
+  it('should save part files when requested', async () => {
+    const project = new TestProject();
+    project.addFile('entrypoints/popup.html');
+    project.addFile('entrypoints/options.html');
+    project.addFile(
+      'entrypoints/background.ts',
+      'export default defineBackground(() => {});',
+    );
+
+    await project.build({
+      analysis: {
+        enabled: true,
+        keepArtifacts: true,
+      },
+    });
+
+    expect(await project.fileExists('stats.html')).toBe(true);
+    expect(await project.fileExists('stats-0.json')).toBe(true);
+    expect(await project.fileExists('stats-1.json')).toBe(true);
+  });
+
+  it('should support customizing the stats output directory', async () => {
+    const project = new TestProject();
+    project.addFile('entrypoints/popup.html');
+    project.addFile('entrypoints/options.html');
+    project.addFile(
+      'entrypoints/background.ts',
+      'export default defineBackground(() => {});',
+    );
+
+    await project.build({
+      analysis: {
+        enabled: true,
+        outputFile: 'stats/bundle.html',
+      },
+    });
+
+    expect(await project.fileExists('stats/bundle.html')).toBe(true);
+  });
+
+  it('should place artifacts next to the custom output file', async () => {
+    const project = new TestProject();
+    project.addFile('entrypoints/popup.html');
+    project.addFile('entrypoints/options.html');
+    project.addFile(
+      'entrypoints/background.ts',
+      'export default defineBackground(() => {});',
+    );
+
+    await project.build({
+      analysis: {
+        enabled: true,
+        outputFile: 'stats/bundle.html',
+        keepArtifacts: true,
+      },
+    });
+
+    expect(await project.fileExists('stats/bundle.html')).toBe(true);
+    expect(await project.fileExists('stats/bundle-0.json')).toBe(true);
+    expect(await project.fileExists('stats/bundle-1.json')).toBe(true);
+  });
+
+  it('should open the stats in the browser when requested', async () => {
+    const project = new TestProject();
+    project.addFile('entrypoints/popup.html');
+    project.addFile('entrypoints/options.html');
+    project.addFile(
+      'entrypoints/background.ts',
+      'export default defineBackground(() => {});',
+    );
+
+    await project.build({
+      analysis: {
+        enabled: true,
+        open: true,
+      },
+    });
+
+    expect(openMock).toBeCalledTimes(1);
+    expect(openMock).toBeCalledWith(project.resolvePath('stats.html'));
+  });
+});
@@ -7,7 +7,7 @@ describe('Auto Imports', () => {
      const project = new TestProject();
      project.addFile('entrypoints/popup.html', `<html></html>`);

-      await project.build();
+      await project.prepare();

      expect(await project.serializeFile('.wxt/types/imports.d.ts'))
        .toMatchInlineSnapshot(`
@@ -38,7 +38,7 @@ describe('Auto Imports', () => {
      const project = new TestProject();
      project.addFile('entrypoints/popup.html', `<html></html>`);

-      await project.build();
+      await project.prepare();

      expect(await project.serializeFile('.wxt/wxt.d.ts'))
        .toMatchInlineSnapshot(`
@@ -63,7 +63,7 @@ describe('Auto Imports', () => {
      });
      project.addFile('entrypoints/popup.html', `<html></html>`);

-      await project.build();
+      await project.prepare();

      expect(await project.fileExists('.wxt/types/imports.d.ts')).toBe(false);
    });
@@ -75,7 +75,7 @@ describe('Auto Imports', () => {
      });
      project.addFile('entrypoints/popup.html', `<html></html>`);

-      await project.build();
+      await project.prepare();

      expect(
        await project.serializeFile('.wxt/wxt.d.ts'),
@@ -93,4 +93,82 @@ describe('Auto Imports', () => {
      );
    });
  });
+
+  describe('eslintrc', () => {
+    it('should output the globals list for ESLint to consume', async () => {
+      const project = new TestProject();
+      project.addFile('entrypoints/popup.html', `<html></html>`);
+
+      await project.prepare({
+        imports: {
+          eslintrc: {
+            enabled: true,
+          },
+        },
+      });
+
+      expect(await project.serializeFile('.wxt/eslintrc-auto-import.json'))
+        .toMatchInlineSnapshot(`
+          ".wxt/eslintrc-auto-import.json
+          ----------------------------------------
+          {
+            "globals": {
+              "ContentScriptContext": true,
+              "InvalidMatchPattern": true,
+              "MatchPattern": true,
+              "browser": true,
+              "createIframeUi": true,
+              "createIntegratedUi": true,
+              "createShadowRootUi": true,
+              "defineBackground": true,
+              "defineConfig": true,
+              "defineContentScript": true,
+              "defineUnlistedScript": true,
+              "fakeBrowser": true,
+              "storage": true
+            }
+          }
+          "
+        `);
+    });
+
+    it('should allow customizing the output', async () => {
+      const project = new TestProject();
+      project.addFile('entrypoints/popup.html', `<html></html>`);
+
+      await project.prepare({
+        imports: {
+          eslintrc: {
+            enabled: true,
+            filePath: project.resolvePath('example.json'),
+            globalsPropValue: 'readonly',
+          },
+        },
+      });
+
+      expect(await project.serializeFile('example.json'))
+        .toMatchInlineSnapshot(`
+          "example.json
+          ----------------------------------------
+          {
+            "globals": {
+              "ContentScriptContext": "readonly",
+              "InvalidMatchPattern": "readonly",
+              "MatchPattern": "readonly",
+              "browser": "readonly",
+              "createIframeUi": "readonly",
+              "createIntegratedUi": "readonly",
+              "createShadowRootUi": "readonly",
+              "defineBackground": "readonly",
+              "defineConfig": "readonly",
+              "defineContentScript": "readonly",
+              "defineUnlistedScript": "readonly",
+              "fakeBrowser": "readonly",
+              "storage": "readonly"
+            }
+          }
+          "
+        `);
+    });
+  });
 });
@@ -0,0 +1,99 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { TestProject } from '../utils';
+import { WxtHooks } from '~/types';
+
+const hooks: WxtHooks = {
+  ready: vi.fn(),
+  'build:before': vi.fn(),
+  'build:done': vi.fn(),
+  'build:manifestGenerated': vi.fn(),
+  'entrypoints:resolved': vi.fn(),
+  'entrypoints:grouped': vi.fn(),
+};
+
+function expectHooksToBeCalled(called: Record<keyof WxtHooks, boolean>) {
+  Object.keys(hooks).forEach((key) => {
+    const hookName = key as keyof WxtHooks;
+    const times = called[hookName] ? 1 : 0;
+    expect(
+      hooks[hookName],
+      `Expected "${hookName}" to be called ${times} time(s)`,
+    ).toBeCalledTimes(called[hookName] ? 1 : 0);
+  });
+}
+
+describe('Hooks', () => {
+  beforeEach(() => {
+    Object.values(hooks).forEach((fn) => fn.mockReset());
+  });
+
+  it('prepare should call hooks', async () => {
+    const project = new TestProject();
+    project.addFile('entrypoints/popup.html', '<html></html>');
+
+    await project.prepare({ hooks });
+
+    expectHooksToBeCalled({
+      ready: true,
+      'build:before': false,
+      'build:done': false,
+      'build:manifestGenerated': false,
+      'entrypoints:grouped': false,
+      'entrypoints:resolved': true,
+    });
+  });
+
+  it('build should call hooks', async () => {
+    const project = new TestProject();
+    project.addFile('entrypoints/popup.html', '<html></html>');
+
+    await project.build({ hooks });
+
+    expectHooksToBeCalled({
+      ready: true,
+      'build:before': true,
+      'build:done': true,
+      'build:manifestGenerated': true,
+      'entrypoints:grouped': true,
+      'entrypoints:resolved': true,
+    });
+  });
+
+  it('zip should call hooks', async () => {
+    const project = new TestProject();
+    project.addFile('entrypoints/popup.html', '<html></html>');
+
+    await project.zip({ hooks });
+
+    expectHooksToBeCalled({
+      ready: true,
+      'build:before': true,
+      'build:done': true,
+      'build:manifestGenerated': true,
+      'entrypoints:grouped': true,
+      'entrypoints:resolved': true,
+    });
+  });
+
+  it('server.start should call hooks', async () => {
+    const project = new TestProject();
+    project.addFile('entrypoints/popup.html', '<html></html>');
+
+    const server = await project.startServer({
+      hooks,
+      runner: {
+        disabled: true,
+      },
+    });
+    await server.stop();
+
+    expectHooksToBeCalled({
+      ready: true,
+      'build:before': true,
+      'build:done': true,
+      'build:manifestGenerated': true,
+      'entrypoints:grouped': true,
+      'entrypoints:resolved': true,
+    });
+  });
+});
@@ -2,6 +2,7 @@ import { describe, it, expect } from 'vitest';
 import { TestProject } from '../utils';
 import { execaCommand } from 'execa';
 import glob from 'fast-glob';
+import { mkdir, writeJson } from 'fs-extra';

 describe('Init command', () => {
  it('should download and create a template', async () => {
@@ -25,6 +26,7 @@ describe('Init command', () => {
        "assets/vue.svg",
        "components/HelloWorld.vue",
        "entrypoints/background.ts",
+        "entrypoints/content.ts",
        "entrypoints/popup/App.vue",
        "entrypoints/popup/index.html",
        "entrypoints/popup/main.ts",
@@ -41,4 +43,17 @@ describe('Init command', () => {
      ]
    `);
  });
+
+  it('should throw an error if the directory is not empty', async () => {
+    const project = new TestProject();
+    await mkdir(project.root);
+    await writeJson(project.resolvePath('package.json'), {});
+
+    await expect(() =>
+      execaCommand(`pnpm -s wxt init ${project.root} -t vue --pm npm`, {
+        env: { ...process.env, CI: 'true' },
+        stdio: 'ignore',
+      }),
+    ).rejects.toThrowError('Command failed with exit code 1:');
+  });
 });
@@ -227,4 +227,169 @@ describe('Output Directory Structure', () => {
      true,
    );
  });
+
+  it('should generate ESM background script when type=module', async () => {
+    const project = new TestProject();
+    project.addFile(
+      'utils/log.ts',
+      `export function logHello(name: string) {
+        console.log(\`Hello \${name}!\`);
+      }`,
+    );
+    project.addFile(
+      'entrypoints/background.ts',
+      `export default defineBackground({
+        type: "module",
+        main() {
+          logHello("background");
+        },
+      })`,
+    );
+    project.addFile(
+      'entrypoints/popup/index.html',
+      `<html>
+        <head>
+          <script type="module" src="./main.ts"></script>
+        </head>
+      </html>`,
+    );
+    project.addFile('entrypoints/popup/main.ts', `logHello('popup')`);
+
+    await project.build({
+      experimental: {
+        // Simplify the build output for comparison
+        includeBrowserPolyfill: false,
+      },
+      vite: () => ({
+        build: {
+          // Make output for snapshot readible
+          minify: false,
+        },
+      }),
+    });
+
+    expect(await project.serializeFile('.output/chrome-mv3/background.js'))
+      .toMatchInlineSnapshot(`
+        ".output/chrome-mv3/background.js
+        ----------------------------------------
+        import { l as logHello } from "./chunks/log-bezs0tt4.js";
+        function defineBackground(arg) {
+          if (typeof arg === "function")
+            return { main: arg };
+          return arg;
+        }
+        const definition = defineBackground({
+          type: "module",
+          main() {
+            logHello("background");
+          }
+        });
+        chrome;
+        function print(method, ...args) {
+          return;
+        }
+        var logger = {
+          debug: (...args) => print(console.debug, ...args),
+          log: (...args) => print(console.log, ...args),
+          warn: (...args) => print(console.warn, ...args),
+          error: (...args) => print(console.error, ...args)
+        };
+        try {
+          const res = definition.main();
+          if (res instanceof Promise) {
+            console.warn(
+              "The background's main() function return a promise, but it must be synchronous"
+            );
+          }
+        } catch (err) {
+          logger.error("The background crashed on startup!");
+          throw err;
+        }
+        "
+      `);
+  });
+
+  it('should generate IIFE background script when type=undefined', async () => {
+    const project = new TestProject();
+    project.addFile(
+      'utils/log.ts',
+      `export function logHello(name: string) {
+          console.log(\`Hello \${name}!\`);
+        }`,
+    );
+    project.addFile(
+      'entrypoints/background.ts',
+      `export default defineBackground({
+          main() {
+            logHello("background");
+          },
+        })`,
+    );
+    project.addFile(
+      'entrypoints/popup/index.html',
+      `<html>
+          <head>
+            <script type="module" src="./main.ts"></script>
+          </head>
+        </html>`,
+    );
+    project.addFile('entrypoints/popup/main.ts', `logHello('popup')`);
+
+    await project.build({
+      experimental: {
+        // Simplify the build output for comparison
+        includeBrowserPolyfill: false,
+      },
+      vite: () => ({
+        build: {
+          // Make output for snapshot readible
+          minify: false,
+        },
+      }),
+    });
+
+    expect(await project.serializeFile('.output/chrome-mv3/background.js'))
+      .toMatchInlineSnapshot(`
+        ".output/chrome-mv3/background.js
+        ----------------------------------------
+        (function() {
+          "use strict";
+          function defineBackground(arg) {
+            if (typeof arg === "function")
+              return { main: arg };
+            return arg;
+          }
+          function logHello(name) {
+            console.log(\`Hello \${name}!\`);
+          }
+          const definition = defineBackground({
+            main() {
+              logHello("background");
+            }
+          });
+          chrome;
+          function print(method, ...args) {
+            return;
+          }
+          var logger = {
+            debug: (...args) => print(console.debug, ...args),
+            log: (...args) => print(console.log, ...args),
+            warn: (...args) => print(console.warn, ...args),
+            error: (...args) => print(console.error, ...args)
+          };
+          try {
+            const res = definition.main();
+            if (res instanceof Promise) {
+              console.warn(
+                "The background's main() function return a promise, but it must be synchronous"
+              );
+            }
+          } catch (err) {
+            logger.error("The background crashed on startup!");
+            throw err;
+          }
+        })();
+        "
+      `);
+  });
 });
@@ -6,7 +6,7 @@ describe('TypeScript Project', () => {
    const project = new TestProject();
    project.addFile('entrypoints/unlisted.html');

-    await project.build();
+    await project.prepare();

    const output = await project.serializeFile('.wxt/types/globals.d.ts');
    expect(output).toMatchInlineSnapshot(`
@@ -38,7 +38,7 @@ describe('TypeScript Project', () => {
    project.addFile('entrypoints/options.html');
    project.addFile('entrypoints/sandbox.html');

-    await project.build();
+    await project.prepare();

    const output = await project.serializeFile('.wxt/types/paths.d.ts');
    expect(output).toMatchInlineSnapshot(`
@@ -103,7 +103,7 @@ describe('TypeScript Project', () => {
      },
    });

-    await project.build();
+    await project.prepare();

    const output = await project.serializeFile('.wxt/types/i18n.d.ts');
    expect(output).toMatchInlineSnapshot(`
@@ -225,7 +225,7 @@ describe('TypeScript Project', () => {
    const project = new TestProject();
    project.addFile('entrypoints/unlisted.html');

-    await project.build();
+    await project.prepare();

    const output = await project.serializeFile('.wxt/wxt.d.ts');
    expect(output).toMatchInlineSnapshot(`
@@ -245,7 +245,7 @@ describe('TypeScript Project', () => {
    const project = new TestProject();
    project.addFile('entrypoints/unlisted.html');

-    await project.build();
+    await project.prepare();

    const output = await project.serializeFile('.wxt/tsconfig.json');
    expect(output).toMatchInlineSnapshot(`
@@ -289,7 +289,7 @@ describe('TypeScript Project', () => {
      srcDir: 'src',
    });

-    await project.build();
+    await project.prepare();

    const output = await project.serializeFile('.wxt/tsconfig.json');
    expect(output).toMatchInlineSnapshot(`
@@ -337,7 +337,7 @@ describe('TypeScript Project', () => {
      },
    });

-    await project.build();
+    await project.prepare();

    const output = await project.serializeFile('.wxt/tsconfig.json');
    expect(output).toMatchInlineSnapshot(`
@@ -107,4 +107,29 @@ describe('User Config', () => {
    });
    expect(withoutPolyfill).not.toBe(withPolyfill);
  });
+
+  it('should respect changing config files', async () => {
+    const project = new TestProject();
+    project.addFile(
+      'src/entrypoints/background.ts',
+      `export default defineBackground(
+        () => console.log('Hello background'),
+      );`,
+    );
+    project.addFile(
+      'test.config.ts',
+      `import { defineConfig } from 'wxt';
+      
+      export default defineConfig({
+        outDir: ".custom-output",
+        srcDir: "src",
+      });`,
+    );
+
+    await project.build({ configFile: 'test.config.ts' });
+
+    expect(
+      await project.fileExists('.custom-output/chrome-mv3/background.js'),
+    ).toBe(true);
+  });
 });
@@ -0,0 +1,99 @@
+import { describe, expect, it } from 'vitest';
+import { TestProject } from '../utils';
+import extract from 'extract-zip';
+import { execaCommand } from 'execa';
+import { readFile, writeFile } from 'fs-extra';
+
+process.env.WXT_PNPM_IGNORE_WORKSPACE = 'true';
+
+describe('Zipping', () => {
+  it('should download packages and produce a valid build when zipping sources', async () => {
+    const project = new TestProject({
+      name: 'test',
+      version: '1.0.0',
+      dependencies: {
+        flatten: '1.0.3',
+      },
+    });
+    project.addFile(
+      'entrypoints/background.ts',
+      'export default defineBackground(() => {});',
+    );
+    const unzipDir = project.resolvePath('.output/test-1.0.0-sources');
+    const sourcesZip = project.resolvePath('.output/test-1.0.0-sources.zip');
+
+    await project.zip({
+      browser: 'firefox',
+      zip: { downloadPackages: ['flatten'] },
+    });
+    expect(await project.fileExists('.output/')).toBe(true);
+
+    await extract(sourcesZip, { dir: unzipDir });
+    // Update package json wxt path
+    const packageJsonPath = project.resolvePath(unzipDir, 'package.json');
+    const packageJson = JSON.parse(await readFile(packageJsonPath, 'utf-8'));
+    packageJson.dependencies.wxt = '../../../../..';
+    await writeFile(
+      packageJsonPath,
+      JSON.stringify(packageJson, null, 2),
+      'utf-8',
+    );
+
+    // Build zipped extension
+    await expect(
+      execaCommand('pnpm i --ignore-workspace --frozen-lockfile false', {
+        cwd: unzipDir,
+      }),
+    ).resolves.toMatchObject({ exitCode: 0 });
+    await expect(
+      execaCommand('pnpm wxt build -b firefox', { cwd: unzipDir }),
+    ).resolves.toMatchObject({ exitCode: 0 });
+
+    await expect(project.fileExists(unzipDir, '.output')).resolves.toBe(true);
+    expect(
+      await project.serializeFile(
+        project.resolvePath(unzipDir, 'package.json'),
+      ),
+    ).toMatchInlineSnapshot(`
+      ".output/test-1.0.0-sources/package.json
+      ----------------------------------------
+      {
+        "name": "test",
+        "description": "Example description",
+        "version": "1.0.0",
+        "dependencies": {
+          "wxt": "../../../../..",
+          "flatten": "1.0.3"
+        },
+        "resolutions": {
+          "flatten@1.0.3": "file://./.wxt/local_modules/flatten-1.0.3.tgz"
+        }
+      }"
+    `);
+  });
+
+  it('should correctly apply template variables for zip file names based on provided config', async () => {
+    const project = new TestProject({
+      name: 'test',
+      version: '1.0.0',
+    });
+    project.addFile(
+      'entrypoints/background.ts',
+      'export default defineBackground(() => {});',
+    );
+    const artifactZip = '.output/test-1.0.0-firefox-development.zip';
+    const sourcesZip = '.output/test-1.0.0-development-sources.zip';
+
+    await project.zip({
+      browser: 'firefox',
+      mode: 'development',
+      zip: {
+        artifactTemplate: '{{name}}-{{version}}-{{browser}}-{{mode}}.zip',
+        sourcesTemplate: '{{name}}-{{version}}-{{mode}}-sources.zip',
+      },
+    });
+
+    expect(await project.fileExists(artifactZip)).toBe(true);
+    expect(await project.fileExists(sourcesZip)).toBe(true);
+  });
+});
@@ -2,7 +2,14 @@ import { dirname, join, relative, resolve } from 'path';
 import fs from 'fs-extra';
 import glob from 'fast-glob';
 import { execaCommand } from 'execa';
-import { InlineConfig, UserConfig, build } from '../src';
+import {
+  InlineConfig,
+  UserConfig,
+  build,
+  createServer,
+  prepare,
+  zip,
+} from '../src';
 import { normalizePath } from '../src/core/utils/paths';
 import merge from 'lodash.merge';

@@ -63,15 +70,41 @@ export class TestProject {
    if (filename === 'wxt.config.ts') this.config = {};
  }

-  /**
-   * Write the files to the test directory install dependencies, and build the project.
-   */
+  async prepare(config: InlineConfig = {}) {
+    await this.writeProjectToDisk();
+    await prepare({ ...config, root: this.root });
+  }
+
  async build(config: InlineConfig = {}) {
+    await this.writeProjectToDisk();
+    await build({ ...config, root: this.root });
+  }
+
+  async zip(config: InlineConfig = {}) {
+    await this.writeProjectToDisk();
+    await zip({ ...config, root: this.root });
+  }
+
+  async startServer(config: InlineConfig = {}) {
+    await this.writeProjectToDisk();
+    const server = await createServer({ ...config, root: this.root });
+    await server.start();
+    return server;
+  }
+
+  /**
+   * Call `path.resolve` relative to the project's root directory.
+   */
+  resolvePath(...path: string[]): string {
+    return resolve(this.root, ...path);
+  }
+
+  private async writeProjectToDisk() {
    if (this.config == null) this.setConfigFileConfig();

    for (const file of this.files) {
      const [name, content] = file;
-      const filePath = resolve(this.root, name);
+      const filePath = this.resolvePath(name);
      const fileDir = dirname(filePath);
      await fs.ensureDir(fileDir);
      await fs.writeFile(filePath, content ?? '', 'utf-8');
@@ -80,7 +113,6 @@ export class TestProject {
    await execaCommand('pnpm --ignore-workspace i --ignore-scripts', {
      cwd: this.root,
    });
-    await build({ ...config, root: this.root });
  }

  /**
@@ -115,13 +147,13 @@ export class TestProject {
    ignoreContentsOfFilenames?: string[],
  ): Promise<string> {
    const outputFiles = await glob('**/*', {
-      cwd: resolve(this.root, dir),
+      cwd: this.resolvePath(dir),
      ignore: ['**/node_modules', '**/.output'],
    });
    outputFiles.sort();
    const fileContents = [];
    for (const file of outputFiles) {
-      const path = resolve(this.root, dir, file);
+      const path = this.resolvePath(dir, file);
      const isContentIgnored = !!ignoreContentsOfFilenames?.find(
        (ignoredFile) => normalizePath(path).endsWith(ignoredFile),
      );
@@ -131,25 +163,25 @@ export class TestProject {
  }

  /**
-   * @param path An abosolute path to a file or a path relative to the root.
+   * @param path An absolute path to a file or a path relative to the root.
   * @param ignoreContents An optional boolean that, when true, causes this function to not print
   *                       the file contents.
   */
  async serializeFile(path: string, ignoreContents?: boolean): Promise<string> {
-    const absolutePath = resolve(this.root, path);
+    const absolutePath = this.resolvePath(path);
    return [
      normalizePath(relative(this.root, absolutePath)),
      ignoreContents ? '<contents-ignored>' : await fs.readFile(absolutePath),
    ].join(`\n${''.padEnd(40, '-')}\n`);
  }

-  fileExists(path: string): Promise<boolean> {
-    return fs.exists(resolve(this.root, path));
+  fileExists(...path: string[]): Promise<boolean> {
+    return fs.exists(this.resolvePath(...path));
  }

  async getOutputManifest(
    path: string = '.output/chrome-mv3/manifest.json',
  ): Promise<any> {
-    return await fs.readJson(resolve(this.root, path));
+    return await fs.readJson(this.resolvePath(path));
  }
 }
@@ -1,7 +1,7 @@
 {
  "name": "wxt",
  "type": "module",
-  "version": "0.15.0",
+  "version": "0.17.11",
  "description": "Next gen framework for developing web extensions",
  "engines": {
    "node": ">=18",
@@ -30,7 +30,10 @@
    "bin",
    "dist"
  ],
-  "bin": "./bin/wxt.mjs",
+  "bin": {
+    "wxt": "./bin/wxt.mjs",
+    "wxt-publish-extension": "./bin/wxt-publish-extension.cjs"
+  },
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
@@ -82,16 +85,11 @@
    }
  },
  "scripts": {
-    "wxt": "tsx src/cli.ts",
+    "wxt": "tsx src/cli/index.ts",
    "build": "tsx scripts/build.ts",
-    "format": "prettier --write .",
-    "format:check": "prettier --check .",
-    "lint": "run-p -c -s lint:*",
-    "lint:eslint": "echo 'ESLint: TODO'",
-    "lint:package": "publint",
-    "compile": "run-s -c compile:*",
-    "compile:wxt": "tsc --noEmit",
-    "compile:virtual": "tsc --noEmit -p src/virtual",
+    "check": "run-s -c check:*",
+    "check:default": "check",
+    "check:tsc-virtual": "tsc --noEmit -p src/virtual",
    "test": "vitest",
    "test:coverage": "vitest run --coverage.enabled \"--coverage.include=src/**\" \"--coverage.exclude=src/core/utils/testing/**\" \"--coverage.exclude=**/*.d.ts\"",
    "prepare": "simple-git-hooks",
@@ -103,6 +101,7 @@
    "sync-releases": "pnpx changelogen@latest gh release"
  },
  "dependencies": {
+    "@aklinker1/rollup-plugin-visualizer": "5.12.0",
    "@types/webextension-polyfill": "^0.10.5",
    "@webext-core/fake-browser": "^1.3.1",
    "@webext-core/isolated-element": "^1.1.1",
@@ -111,6 +110,7 @@
    "c12": "^1.5.1",
    "cac": "^6.7.14",
    "chokidar": "^3.5.3",
+    "ci-info": "^4.0.0",
    "consola": "^3.2.3",
    "defu": "^6.1.3",
    "dequal": "^2.0.3",
@@ -120,26 +120,28 @@
    "fs-extra": "^11.1.1",
    "get-port": "^7.0.0",
    "giget": "^1.1.3",
-    "immer": "^10.0.3",
+    "hookable": "^5.5.3",
    "is-wsl": "^3.0.0",
    "jiti": "^1.21.0",
    "json5": "^2.2.3",
+    "jszip": "^3.10.1",
    "linkedom": "^0.16.1",
-    "manage-path": "^2.0.0",
    "minimatch": "^9.0.3",
    "natural-compare": "^1.4.0",
    "normalize-path": "^3.0.0",
+    "nypm": "^0.3.6",
+    "open": "^10.1.0",
    "ora": "^7.0.1",
    "picocolors": "^1.0.0",
    "prompts": "^2.4.2",
-    "rollup-plugin-visualizer": "^5.9.2",
+    "publish-browser-extension": "^2.1.3",
    "unimport": "^3.4.0",
-    "vite": "^5.0.0",
-    "web-ext-run": "^0.1.2",
-    "webextension-polyfill": "^0.10.0",
-    "zip-dir": "^2.0.0"
+    "vite": "^5.1.3",
+    "web-ext-run": "^0.2.0",
+    "webextension-polyfill": "^0.10.0"
  },
  "devDependencies": {
+    "@aklinker1/check": "^1.1.1",
    "@faker-js/faker": "^8.3.1",
    "@types/fs-extra": "^11.0.4",
    "@types/lodash.merge": "^4.6.9",
@@ -149,7 +151,8 @@
    "@types/prompts": "^2.4.9",
    "@vitest/coverage-v8": "^1.0.1",
    "execa": "^8.0.1",
-    "happy-dom": "^12.10.3",
+    "extract-zip": "^2.0.1",
+    "happy-dom": "^13.3.8",
    "lint-staged": "^15.2.0",
    "lodash.merge": "^4.6.2",
    "npm-run-all": "^4.1.5",
@@ -164,8 +167,9 @@
    "typedoc-vitepress-theme": "1.0.0-next.3",
    "typescript": "^5.3.2",
    "vitepress": "1.0.0-rc.34",
-    "vitest": "^1.1.0",
+    "vitest": "^1.2.2",
    "vitest-mock-extended": "^1.3.1",
+    "vitest-plugin-random-seed": "^1.0.2",
    "vue": "^3.3.10"
  },
  "packageManager": "pnpm@8.6.3",
@@ -8,6 +8,10 @@ import { consola } from 'consola';
 import pMap from 'p-map';
 import os from 'node:os';
 import path from 'node:path';
+import {
+  virtualModuleNames,
+  virtualEntrypointModuleNames,
+} from '~/core/utils/virtual-modules';

 const spinnerText = 'Building WXT';
 const spinner = ora(spinnerText).start();
@@ -20,12 +24,7 @@ const preset = {
  dts: true,
  silent: true,
  sourcemap: false,
-  external: [
-    'virtual:user-unlisted-script',
-    'virtual:user-content-script-isolated-world',
-    'virtual:user-content-script-main-world',
-    'virtual:user-background',
-  ],
+  external: virtualEntrypointModuleNames.map((name) => `virtual:user-${name}`),
 } satisfies tsup.Options;

 function spinnerPMap(configs: tsup.Options[]) {
@@ -74,17 +73,13 @@ const config: tsup.Options[] = [
  },
  {
    ...preset,
-    entry: {
-      'virtual/background-entrypoint': 'src/virtual/background-entrypoint.ts',
-      'virtual/content-script-isolated-world-entrypoint':
-        'src/virtual/content-script-isolated-world-entrypoint.ts',
-      'virtual/content-script-main-world-entrypoint':
-        'src/virtual/content-script-main-world-entrypoint.ts',
-      'virtual/mock-browser': 'src/virtual/mock-browser.ts',
-      'virtual/reload-html': 'src/virtual/reload-html.ts',
-      'virtual/unlisted-script-entrypoint':
-        'src/virtual/unlisted-script-entrypoint.ts',
-    },
+    entry: virtualModuleNames.reduce<Record<string, string>>(
+      (acc, moduleName) => {
+        acc[`virtual/${moduleName}`] = `src/virtual/${moduleName}.ts`;
+        return acc;
+      },
+      {},
+    ),
    format: ['esm'],
    splitting: false,
    dts: false,
@@ -94,7 +89,7 @@ const config: tsup.Options[] = [
  {
    ...preset,
    entry: {
-      cli: 'src/cli.ts',
+      cli: 'src/cli/index.ts',
    },
    format: ['esm'],
    banner: {
@@ -1,7 +1,15 @@
 import { fakeBrowser } from '@webext-core/fake-browser';
-import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { describe, it, expect, beforeEach, vi, expectTypeOf } from 'vitest';
 import { browser } from '~/browser';
-import { storage } from '~/storage';
+import { WxtStorageItem, storage } from '~/storage';
+
+/**
+ * This works because fakeBrowser is synchronous, and is will finish any number of chained
+ * calls within a single tick of the event loop, ie: a timeout of 0.
+ */
+async function waitForMigrations() {
+  return new Promise((res) => setTimeout(res));
+}

 describe('Storage Utils', () => {
  beforeEach(() => {
@@ -68,10 +76,7 @@ describe('Storage Utils', () => {

          const actual = await storage.getItems(params);

-          expect(actual).toHaveLength(3);
-          expected.forEach((item) => {
-            expect(actual).toContainEqual(item);
-          });
+          expect(actual).toEqual(expected);
        });
      });

@@ -384,417 +389,466 @@ describe('Storage Utils', () => {
          expect(cb).not.toBeCalled();
        });
      });
-
-      describe('defineItem', () => {
-        describe('versioning', () => {
-          /**
-           * This works because fakeBrowser is syncrounous, and is will finish any number of chained
-           * calls within a single tick of the event loop, ie: a timeout of 0.
-           */
-          async function waitForMigrations() {
-            return new Promise((res) => setTimeout(res));
-          }
-
-          it('should migrate values to the latest when a version upgrade is detected', async () => {
-            await fakeBrowser.storage[storageArea].set({
-              count: 2,
-              count$: { v: 1 },
-            });
-            const migrateToV2 = vi.fn((oldCount) => oldCount * 2);
-            const migrateToV3 = vi.fn((oldCount) => oldCount * 3);
-
-            const item = storage.defineItem<number, { v: number }>(
-              `${storageArea}:count`,
-              {
-                version: 3,
-                migrations: {
-                  2: migrateToV2,
-                  3: migrateToV3,
-                },
-              },
-            );
-            await waitForMigrations();
-
-            const actualValue = await item.getValue();
-            const actualMeta = await item.getMeta();
-
-            expect(actualValue).toEqual(12);
-            expect(actualMeta).toEqual({ v: 3 });
-
-            expect(migrateToV2).toBeCalledTimes(1);
-            expect(migrateToV2).toBeCalledWith(2);
-
-            expect(migrateToV3).toBeCalledTimes(1);
-            expect(migrateToV3).toBeCalledWith(4);
-          });
-
-          it("should not run migrations if the value doesn't exist yet", async () => {
-            const migrateToV2 = vi.fn((oldCount) => oldCount * 2);
-            const migrateToV3 = vi.fn((oldCount) => oldCount * 3);
-
-            const item = storage.defineItem<number, { v: number }>(
-              `${storageArea}:count`,
-              {
-                version: 3,
-                migrations: {
-                  2: migrateToV2,
-                  3: migrateToV3,
-                },
-              },
-            );
-            await waitForMigrations();
-
-            const actualValue = await item.getValue();
-            const actualMeta = await item.getMeta();
-
-            expect(actualValue).toBeNull();
-            expect(actualMeta).toEqual({});
-
-            expect(migrateToV2).not.toBeCalled();
-            expect(migrateToV3).not.toBeCalled();
-          });
-
-          it('should run the v2 migration when converting an unversioned item to a versioned one', async () => {
-            await fakeBrowser.storage[storageArea].set({
-              count: 2,
-            });
-            const migrateToV2 = vi.fn((oldCount) => oldCount * 2);
-
-            const item = storage.defineItem<number, { v: number }>(
-              `${storageArea}:count`,
-              {
-                version: 2,
-                migrations: {
-                  2: migrateToV2,
-                },
-              },
-            );
-            await waitForMigrations();
-
-            const actualValue = await item.getValue();
-            const actualMeta = await item.getMeta();
-
-            expect(actualValue).toEqual(4);
-            expect(actualMeta).toEqual({ v: 2 });
-
-            expect(migrateToV2).toBeCalledTimes(1);
-            expect(migrateToV2).toBeCalledWith(2);
-          });
-
-          it('Should not run old migrations if the version is unchanged', async () => {
-            await fakeBrowser.storage[storageArea].set({
-              count: 2,
-              count$: { v: 3 },
-            });
-            const migrateToV2 = vi.fn((oldCount) => oldCount * 2);
-            const migrateToV3 = vi.fn((oldCount) => oldCount * 3);
-
-            storage.defineItem<number, { v: number }>(`${storageArea}:count`, {
-              version: 3,
-              migrations: {
-                2: migrateToV2,
-                3: migrateToV3,
-              },
-            });
-            await waitForMigrations();
-
-            expect(migrateToV2).not.toBeCalled();
-            expect(migrateToV3).not.toBeCalled();
-          });
-
-          it('should skip missing migration functions', async () => {
-            await fakeBrowser.storage[storageArea].set({
-              count: 2,
-              count$: { v: 0 },
-            });
-            const migrateToV1 = vi.fn((oldCount) => oldCount * 1);
-            const migrateToV3 = vi.fn((oldCount) => oldCount * 3);
-
-            const item = storage.defineItem<number, { v: number }>(
-              `${storageArea}:count`,
-              {
-                version: 3,
-                migrations: {
-                  1: migrateToV1,
-                  3: migrateToV3,
-                },
-              },
-            );
-            await waitForMigrations();
-
-            const actualValue = await item.getValue();
-            const actualMeta = await item.getMeta();
-
-            expect(actualValue).toEqual(6);
-            expect(actualMeta).toEqual({ v: 3 });
-
-            expect(migrateToV1).toBeCalledTimes(1);
-            expect(migrateToV1).toBeCalledWith(2);
-
-            expect(migrateToV3).toBeCalledTimes(1);
-            expect(migrateToV3).toBeCalledWith(2);
-          });
-
-          it('should throw an error if the new version is less than the previous version', async () => {
-            const prevVersion = 2;
-            const nextVersion = 1;
-            await fakeBrowser.storage[storageArea].set({
-              count: 0,
-              count$: { v: prevVersion },
-            });
-
-            const item = storage.defineItem(`${storageArea}:count`, {
-              version: nextVersion,
-            });
-
-            // @ts-expect-error: _migrationsCompleted is returned, but untyped
-            await expect(item._migrationsCompleted).rejects.toThrow(
-              'version downgrade detected',
-            );
-          });
-        });
-
-        describe('getValue', () => {
-          it('should return the value from storage', async () => {
-            const expected = 2;
-            const item = storage.defineItem<number>(`${storageArea}:count`);
-            await fakeBrowser.storage[storageArea].set({ count: expected });
-
-            const actual = await item.getValue();
-
-            expect(actual).toBe(expected);
-          });
-
-          it('should return null if missing', async () => {
-            const item = storage.defineItem<number>(`${storageArea}:count`);
-
-            const actual = await item.getValue();
-
-            expect(actual).toBeNull();
-          });
-
-          it('should return the provided default value if missing', async () => {
-            const expected = 0;
-            const item = storage.defineItem(`${storageArea}:count`, {
-              defaultValue: expected,
-            });
-
-            const actual = await item.getValue();
-
-            expect(actual).toEqual(expected);
-          });
-        });
-
-        describe('getMeta', () => {
-          it('should return the value from storage at key+$', async () => {
-            const expected = { v: 2 };
-            const item = storage.defineItem<number, { v: number }>(
-              `${storageArea}:count`,
-            );
-            await fakeBrowser.storage[storageArea].set({ count$: expected });
-
-            const actual = await item.getMeta();
-
-            expect(actual).toBe(expected);
-          });
-
-          it('should return an empty object if missing', async () => {
-            const expected = {};
-            const item = storage.defineItem<number, { v: number }>(
-              `${storageArea}:count`,
-            );
-
-            const actual = await item.getMeta();
-
-            expect(actual).toEqual(expected);
-          });
-        });
-
-        describe('setValue', () => {
-          it('should set the value in storage', async () => {
-            const expected = 1;
-            const item = storage.defineItem<number>(`${storageArea}:count`);
-
-            await item.setValue(expected);
-            const actual = await item.getValue();
-
-            expect(actual).toBe(expected);
-          });
-
-          it.each([undefined, null])(
-            'should remove the value in storage when %s is passed in',
-            async (value) => {
-              const item = storage.defineItem<number>(`${storageArea}:count`);
-
-              // @ts-expect-error: undefined is not assignable to null, but we're testing that case on purpose
-              await item.setValue(value);
-              const actual = await item.getValue();
-
-              expect(actual).toBeNull();
-            },
-          );
-        });
-
-        describe('setMeta', () => {
-          it('should set metadata at key+$', async () => {
-            const expected = { date: Date.now() };
-            const item = storage.defineItem<number, { date: number }>(
-              `${storageArea}:count`,
-            );
-
-            await item.setMeta(expected);
-            const actual = await item.getMeta();
-
-            expect(actual).toEqual(expected);
-          });
-
-          it('should add to metadata if already present', async () => {
-            const existing = { v: 2 };
-            const newFields = { date: Date.now() };
-            const expected = { ...existing, ...newFields };
-            const item = storage.defineItem<
-              number,
-              { date: number; v: number }
-            >(`${storageArea}:count`);
-            await fakeBrowser.storage[storageArea].set({
-              count$: existing,
-            });
-
-            await item.setMeta(newFields);
-            const actual = await item.getMeta();
-
-            expect(actual).toEqual(expected);
-          });
-        });
-
-        describe('removeValue', () => {
-          it('should remove the key from storage', async () => {
-            const item = storage.defineItem(`${storageArea}:count`);
-            await fakeBrowser.storage[storageArea].set({ count: 456 });
-
-            await item.removeValue();
-            const actual = await item.getValue();
-
-            expect(actual).toBeNull();
-          });
-
-          it('should not remove the metadata by default', async () => {
-            const item = storage.defineItem(`${storageArea}:count`);
-            const expected = { v: 1 };
-            await fakeBrowser.storage[storageArea].set({
-              count$: expected,
-              count: 3,
-            });
-
-            await item.removeValue();
-            const actual = await item.getMeta();
-
-            expect(actual).toEqual(expected);
-          });
-
-          it('should remove the metadata when requested', async () => {
-            const item = storage.defineItem(`${storageArea}:count`);
-            await fakeBrowser.storage[storageArea].set({
-              count$: { v: 1 },
-              count: 3,
-            });
-
-            await item.removeValue({ removeMeta: true });
-            const actual = await item.getMeta();
-
-            expect(actual).toEqual({});
-          });
-        });
-
-        describe('removeMeta', () => {
-          it('should remove all metadata', async () => {
-            const item = storage.defineItem<number, { v: number }>(
-              `${storageArea}:count`,
-            );
-            await fakeBrowser.storage[storageArea].set({ count$: { v: 4 } });
-
-            await item.removeMeta();
-            const actual = await item.getMeta();
-
-            expect(actual).toEqual({});
-          });
-
-          it('should only remove specific properties', async () => {
-            const item = storage.defineItem<number, { v: number; d: number }>(
-              `${storageArea}:count`,
-            );
-            await fakeBrowser.storage[storageArea].set({
-              count$: { v: 4, d: Date.now() },
-            });
-
-            await item.removeMeta(['d']);
-            const actual = await item.getMeta();
-
-            expect(actual).toEqual({ v: 4 });
-          });
-        });
-
-        describe('watch', () => {
-          it("should not trigger if the changed key is different from the item's key", async () => {
-            const item = storage.defineItem(`${storageArea}:key`);
-            const cb = vi.fn();
-
-            item.watch(cb);
-            await storage.setItem(`${storageArea}:not-the-key`, '123');
-
-            expect(cb).not.toBeCalled();
-          });
-
-          it("should not trigger if the value doesn't change", async () => {
-            const item = storage.defineItem(`${storageArea}:key`);
-            const cb = vi.fn();
-            const value = '123';
-
-            await item.setValue(value);
-            item.watch(cb);
-            await item.setValue(value);
-
-            expect(cb).not.toBeCalled();
-          });
-
-          it('should call the callback when the value changes', async () => {
-            const item = storage.defineItem(`${storageArea}:key`);
-            const cb = vi.fn();
-            const newValue = '123';
-            const oldValue = null;
-
-            item.watch(cb);
-            await item.setValue(newValue);
-
-            expect(cb).toBeCalledTimes(1);
-            expect(cb).toBeCalledWith(newValue, oldValue);
-          });
-
-          it('should remove the listener when calling the returned function', async () => {
-            const item = storage.defineItem(`${storageArea}:key`);
-            const cb = vi.fn();
-
-            const unwatch = item.watch(cb);
-            unwatch();
-            await item.setValue('123');
-
-            expect(cb).not.toBeCalled();
-          });
-        });
-
-        describe('unwatch', () => {
-          it('should remove all watch listeners', async () => {
-            const item = storage.defineItem(`${storageArea}:key`);
-            const cb = vi.fn();
-
-            item.watch(cb);
-            storage.unwatch();
-            await item.setValue('123');
-
-            expect(cb).not.toBeCalled();
-          });
-        });
-      });
    },
  );
+
+  describe('defineItem', () => {
+    describe('versioning', () => {
+      it('should migrate values to the latest when a version upgrade is detected', async () => {
+        await fakeBrowser.storage.local.set({
+          count: 2,
+          count$: { v: 1 },
+        });
+        const migrateToV2 = vi.fn((oldCount) => oldCount * 2);
+        const migrateToV3 = vi.fn((oldCount) => oldCount * 3);
+
+        const item = storage.defineItem<number, { v: number }>(`local:count`, {
+          defaultValue: 0,
+          version: 3,
+          migrations: {
+            2: migrateToV2,
+            3: migrateToV3,
+          },
+        });
+        await waitForMigrations();
+
+        const actualValue = await item.getValue();
+        const actualMeta = await item.getMeta();
+
+        expect(actualValue).toEqual(12);
+        expect(actualMeta).toEqual({ v: 3 });
+
+        expect(migrateToV2).toBeCalledTimes(1);
+        expect(migrateToV2).toBeCalledWith(2);
+
+        expect(migrateToV3).toBeCalledTimes(1);
+        expect(migrateToV3).toBeCalledWith(4);
+      });
+
+      it("should not run migrations if the value doesn't exist yet", async () => {
+        const migrateToV2 = vi.fn((oldCount) => oldCount * 2);
+        const migrateToV3 = vi.fn((oldCount) => oldCount * 3);
+
+        const item = storage.defineItem<number, { v: number }>(`local:count`, {
+          defaultValue: 0,
+          version: 3,
+          migrations: {
+            2: migrateToV2,
+            3: migrateToV3,
+          },
+        });
+        await waitForMigrations();
+
+        const actualValue = await item.getValue();
+        const actualMeta = await item.getMeta();
+
+        expect(actualValue).toEqual(0);
+        expect(actualMeta).toEqual({});
+
+        expect(migrateToV2).not.toBeCalled();
+        expect(migrateToV3).not.toBeCalled();
+      });
+
+      it('should run the v2 migration when converting an unversioned item to a versioned one', async () => {
+        await fakeBrowser.storage.local.set({
+          count: 2,
+        });
+        const migrateToV2 = vi.fn((oldCount) => oldCount * 2);
+
+        const item = storage.defineItem<number, { v: number }>(`local:count`, {
+          defaultValue: 0,
+          version: 2,
+          migrations: {
+            2: migrateToV2,
+          },
+        });
+        await waitForMigrations();
+
+        const actualValue = await item.getValue();
+        const actualMeta = await item.getMeta();
+
+        expect(actualValue).toEqual(4);
+        expect(actualMeta).toEqual({ v: 2 });
+
+        expect(migrateToV2).toBeCalledTimes(1);
+        expect(migrateToV2).toBeCalledWith(2);
+      });
+
+      it('should not run old migrations if the version is unchanged', async () => {
+        await fakeBrowser.storage.local.set({
+          count: 2,
+          count$: { v: 3 },
+        });
+        const migrateToV2 = vi.fn((oldCount) => oldCount * 2);
+        const migrateToV3 = vi.fn((oldCount) => oldCount * 3);
+
+        storage.defineItem<number, { v: number }>(`local:count`, {
+          defaultValue: 0,
+          version: 3,
+          migrations: {
+            2: migrateToV2,
+            3: migrateToV3,
+          },
+        });
+        await waitForMigrations();
+
+        expect(migrateToV2).not.toBeCalled();
+        expect(migrateToV3).not.toBeCalled();
+      });
+
+      it('should skip missing migration functions', async () => {
+        await fakeBrowser.storage.local.set({
+          count: 2,
+          count$: { v: 0 },
+        });
+        const migrateToV1 = vi.fn((oldCount) => oldCount * 1);
+        const migrateToV3 = vi.fn((oldCount) => oldCount * 3);
+
+        const item = storage.defineItem<number, { v: number }>(`local:count`, {
+          defaultValue: 0,
+          version: 3,
+          migrations: {
+            1: migrateToV1,
+            3: migrateToV3,
+          },
+        });
+        await waitForMigrations();
+
+        const actualValue = await item.getValue();
+        const actualMeta = await item.getMeta();
+
+        expect(actualValue).toEqual(6);
+        expect(actualMeta).toEqual({ v: 3 });
+
+        expect(migrateToV1).toBeCalledTimes(1);
+        expect(migrateToV1).toBeCalledWith(2);
+
+        expect(migrateToV3).toBeCalledTimes(1);
+        expect(migrateToV3).toBeCalledWith(2);
+      });
+
+      it('should throw an error if the new version is less than the previous version', async () => {
+        const prevVersion = 2;
+        const nextVersion = 1;
+        await fakeBrowser.storage.local.set({
+          count: 0,
+          count$: { v: prevVersion },
+        });
+
+        const item = storage.defineItem(`local:count`, {
+          defaultValue: 0,
+          version: nextVersion,
+        });
+        await waitForMigrations();
+
+        await expect(item.migrate()).rejects.toThrow(
+          'Version downgrade detected (v2 -> v1) for "local:count"',
+        );
+      });
+    });
+
+    describe('getValue', () => {
+      it('should return the value from storage', async () => {
+        const expected = 2;
+        const item = storage.defineItem<number>(`local:count`);
+        await fakeBrowser.storage.local.set({ count: expected });
+
+        const actual = await item.getValue();
+
+        expect(actual).toBe(expected);
+      });
+
+      it('should return null if missing', async () => {
+        const item = storage.defineItem<number>(`local:count`);
+
+        const actual = await item.getValue();
+
+        expect(actual).toBeNull();
+      });
+
+      it('should return the provided default value if missing', async () => {
+        const expected = 0;
+        const item = storage.defineItem(`local:count`, {
+          defaultValue: expected,
+        });
+
+        const actual = await item.getValue();
+
+        expect(actual).toEqual(expected);
+      });
+    });
+
+    describe('getMeta', () => {
+      it('should return the value from storage at key+$', async () => {
+        const expected = { v: 2 };
+        const item = storage.defineItem<number, { v: number }>(`local:count`);
+        await fakeBrowser.storage.local.set({ count$: expected });
+
+        const actual = await item.getMeta();
+
+        expect(actual).toBe(expected);
+      });
+
+      it('should return an empty object if missing', async () => {
+        const expected = {};
+        const item = storage.defineItem<number, { v: number }>(`local:count`);
+
+        const actual = await item.getMeta();
+
+        expect(actual).toEqual(expected);
+      });
+    });
+
+    describe('setValue', () => {
+      it('should set the value in storage', async () => {
+        const expected = 1;
+        const item = storage.defineItem<number>(`local:count`);
+
+        await item.setValue(expected);
+        const actual = await item.getValue();
+
+        expect(actual).toBe(expected);
+      });
+
+      it.each([undefined, null])(
+        'should remove the value in storage when %s is passed in',
+        async (value) => {
+          const item = storage.defineItem<number>(`local:count`);
+
+          // @ts-expect-error: undefined is not assignable to null, but we're testing that case on purpose
+          await item.setValue(value);
+          const actual = await item.getValue();
+
+          expect(actual).toBeNull();
+        },
+      );
+    });
+
+    describe('setMeta', () => {
+      it('should set metadata at key+$', async () => {
+        const expected = { date: Date.now() };
+        const item = storage.defineItem<number, { date: number }>(
+          `local:count`,
+        );
+
+        await item.setMeta(expected);
+        const actual = await item.getMeta();
+
+        expect(actual).toEqual(expected);
+      });
+
+      it('should add to metadata if already present', async () => {
+        const existing = { v: 2 };
+        const newFields = { date: Date.now() };
+        const expected = { ...existing, ...newFields };
+        const item = storage.defineItem<number, { date: number; v: number }>(
+          `local:count`,
+        );
+        await fakeBrowser.storage.local.set({
+          count$: existing,
+        });
+
+        await item.setMeta(newFields);
+        const actual = await item.getMeta();
+
+        expect(actual).toEqual(expected);
+      });
+    });
+
+    describe('removeValue', () => {
+      it('should remove the key from storage', async () => {
+        const item = storage.defineItem(`local:count`);
+        await fakeBrowser.storage.local.set({ count: 456 });
+
+        await item.removeValue();
+        const actual = await item.getValue();
+
+        expect(actual).toBeNull();
+      });
+
+      it('should not remove the metadata by default', async () => {
+        const item = storage.defineItem(`local:count`);
+        const expected = { v: 1 };
+        await fakeBrowser.storage.local.set({
+          count$: expected,
+          count: 3,
+        });
+
+        await item.removeValue();
+        const actual = await item.getMeta();
+
+        expect(actual).toEqual(expected);
+      });
+
+      it('should remove the metadata when requested', async () => {
+        const item = storage.defineItem(`local:count`);
+        await fakeBrowser.storage.local.set({
+          count$: { v: 1 },
+          count: 3,
+        });
+
+        await item.removeValue({ removeMeta: true });
+        const actual = await item.getMeta();
+
+        expect(actual).toEqual({});
+      });
+    });
+
+    describe('removeMeta', () => {
+      it('should remove all metadata', async () => {
+        const item = storage.defineItem<number, { v: number }>(`local:count`);
+        await fakeBrowser.storage.local.set({ count$: { v: 4 } });
+
+        await item.removeMeta();
+        const actual = await item.getMeta();
+
+        expect(actual).toEqual({});
+      });
+
+      it('should only remove specific properties', async () => {
+        const item = storage.defineItem<number, { v: number; d: number }>(
+          `local:count`,
+        );
+        await fakeBrowser.storage.local.set({
+          count$: { v: 4, d: Date.now() },
+        });
+
+        await item.removeMeta(['d']);
+        const actual = await item.getMeta();
+
+        expect(actual).toEqual({ v: 4 });
+      });
+    });
+
+    describe('watch', () => {
+      it("should not trigger if the changed key is different from the item's key", async () => {
+        const item = storage.defineItem(`local:key`);
+        const cb = vi.fn();
+
+        item.watch(cb);
+        await storage.setItem(`local:not-the-key`, '123');
+
+        expect(cb).not.toBeCalled();
+      });
+
+      it("should not trigger if the value doesn't change", async () => {
+        const item = storage.defineItem(`local:key`);
+        const cb = vi.fn();
+        const value = '123';
+
+        await item.setValue(value);
+        item.watch(cb);
+        await item.setValue(value);
+
+        expect(cb).not.toBeCalled();
+      });
+
+      it('should call the callback when the value changes', async () => {
+        const item = storage.defineItem(`local:key`);
+        const cb = vi.fn();
+        const newValue = '123';
+        const oldValue = null;
+
+        item.watch(cb);
+        await item.setValue(newValue);
+
+        expect(cb).toBeCalledTimes(1);
+        expect(cb).toBeCalledWith(newValue, oldValue);
+      });
+
+      it('should use the default value for the newValue when the item is removed', async () => {
+        const defaultValue = 'default';
+        const item = storage.defineItem<string>(`local:key`, {
+          defaultValue,
+        });
+        const cb = vi.fn();
+        const oldValue = '123';
+        await item.setValue(oldValue);
+
+        item.watch(cb);
+        await item.removeValue();
+
+        expect(cb).toBeCalledTimes(1);
+        expect(cb).toBeCalledWith(defaultValue, oldValue);
+      });
+
+      it("should use the default value for the oldItem when the item didn't exist in storage yet", async () => {
+        const defaultValue = 'default';
+        const item = storage.defineItem<string>(`local:key`, {
+          defaultValue,
+        });
+        const cb = vi.fn();
+        const newValue = '123';
+        await item.removeValue();
+
+        item.watch(cb);
+        await item.setValue(newValue);
+
+        expect(cb).toBeCalledTimes(1);
+        expect(cb).toBeCalledWith(newValue, defaultValue);
+      });
+
+      it('should remove the listener when calling the returned function', async () => {
+        const item = storage.defineItem(`local:key`);
+        const cb = vi.fn();
+
+        const unwatch = item.watch(cb);
+        unwatch();
+        await item.setValue('123');
+
+        expect(cb).not.toBeCalled();
+      });
+    });
+
+    describe('unwatch', () => {
+      it('should remove all watch listeners', async () => {
+        const item = storage.defineItem(`local:key`);
+        const cb = vi.fn();
+
+        item.watch(cb);
+        storage.unwatch();
+        await item.setValue('123');
+
+        expect(cb).not.toBeCalled();
+      });
+    });
+
+    describe('defaultValue', () => {
+      it('should return the default value when provided', () => {
+        const defaultValue = 123;
+        const item = storage.defineItem(`local:test`, {
+          defaultValue,
+        });
+
+        expect(item.defaultValue).toBe(defaultValue);
+      });
+
+      it('should return null when not provided', () => {
+        const item = storage.defineItem<number>(`local:test`);
+
+        expect(item.defaultValue).toBeNull();
+      });
+    });
+
+    describe('types', () => {
+      it('should define a nullable value when options are not passed', () => {
+        const item = storage.defineItem<number>(`local:test`);
+        expectTypeOf(item).toEqualTypeOf<WxtStorageItem<number | null, {}>>();
+      });
+
+      it('should define a non-null value when options are passed with a nullish default value', () => {
+        const item = storage.defineItem(`local:test`, {
+          defaultValue: 123,
+        });
+        expectTypeOf(item).toEqualTypeOf<WxtStorageItem<number, {}>>();
+      });
+
+      it('should define a nullable value when options are passed with null default value', () => {
+        const item = storage.defineItem<number | null>(`local:test`, {
+          defaultValue: null,
+        });
+        expectTypeOf(item).toEqualTypeOf<WxtStorageItem<number | null, {}>>();
+      });
+    });
+  });
 });
@@ -51,7 +51,7 @@ export type {
  Identity,
  Idle,
  Management,
-  Manifest,
+  Manifest, // TODO: Export custom manifest types that are valid for both Chrome and Firefox.
  ContextMenus,
  Menus,
  NetworkStatus,
@@ -1,29 +1,29 @@
 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 { 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');
+vi.mock('~/core/build');
 const buildMock = vi.mocked(build);

-vi.mock('../core/create-server');
+vi.mock('~/core/create-server');
 const createServerMock = vi.mocked(createServer);

-vi.mock('../core/zip');
+vi.mock('~/core/zip');
 const zipMock = vi.mocked(zip);

-vi.mock('../core/prepare');
+vi.mock('~/core/prepare');
 const prepareMock = vi.mocked(prepare);

-vi.mock('../core/clean');
+vi.mock('~/core/clean');
 const cleanMock = vi.mocked(clean);

-vi.mock('../core/initialize');
+vi.mock('~/core/initialize');
 const initializeMock = vi.mocked(initialize);

 consola.wrapConsole();
@@ -34,6 +34,10 @@ function mockArgv(...args: string[]) {
  process.argv = ['/bin/node', 'bin/wxt.mjs', ...args];
 }

+async function importCli() {
+  await import('~/cli');
+}
+
 describe('CLI', () => {
  beforeEach(() => {
    vi.resetModules();
@@ -44,14 +48,14 @@ describe('CLI', () => {
  describe('dev', () => {
    it('should not pass any config when no flags are passed', async () => {
      mockArgv();
-      await import('../cli');
+      await importCli();

      expect(createServerMock).toBeCalledWith({});
    });

    it('should respect passing a custom root', async () => {
      mockArgv('path/to/root');
-      await import('../cli');
+      await importCli();

      expect(createServerMock).toBeCalledWith({
        root: 'path/to/root',
@@ -60,7 +64,7 @@ describe('CLI', () => {

    it('should respect a custom config file', async () => {
      mockArgv('-c', './path/to/config.ts');
-      await import('../cli');
+      await importCli();

      expect(createServerMock).toBeCalledWith({
        configFile: './path/to/config.ts',
@@ -69,7 +73,7 @@ describe('CLI', () => {

    it('should respect passing a custom mode', async () => {
      mockArgv('-m', 'development');
-      await import('../cli');
+      await importCli();

      expect(createServerMock).toBeCalledWith({
        mode: 'development',
@@ -78,7 +82,7 @@ describe('CLI', () => {

    it('should respect passing a custom browser', async () => {
      mockArgv('-b', 'firefox');
-      await import('../cli');
+      await importCli();

      expect(createServerMock).toBeCalledWith({
        browser: 'firefox',
@@ -87,7 +91,7 @@ describe('CLI', () => {

    it('should pass correct filtered entrypoints', async () => {
      mockArgv('-e', 'popup', '-e', 'options');
-      await import('../cli');
+      await importCli();

      expect(createServerMock).toBeCalledWith({
        filterEntrypoints: ['popup', 'options'],
@@ -96,7 +100,7 @@ describe('CLI', () => {

    it('should respect passing --mv2', async () => {
      mockArgv('--mv2');
-      await import('../cli');
+      await importCli();

      expect(createServerMock).toBeCalledWith({
        manifestVersion: 2,
@@ -105,16 +109,30 @@ describe('CLI', () => {

    it('should respect passing --mv3', async () => {
      mockArgv('--mv3');
-      await import('../cli');
+      await importCli();

      expect(createServerMock).toBeCalledWith({
        manifestVersion: 3,
      });
    });

+    it('should respect passing --port', async () => {
+      const expectedPort = 3100;
+      mockArgv('--port', String(expectedPort));
+      await importCli();
+
+      expect(createServerMock).toBeCalledWith({
+        dev: {
+          server: {
+            port: expectedPort,
+          },
+        },
+      });
+    });
+
    it('should respect passing --debug', async () => {
      mockArgv('--debug');
-      await import('../cli');
+      await importCli();

      expect(createServerMock).toBeCalledWith({
        debug: true,
@@ -125,14 +143,14 @@ describe('CLI', () => {
  describe('build', () => {
    it('should not pass any config when no flags are passed', async () => {
      mockArgv('build');
-      await import('../cli');
+      await importCli();

      expect(buildMock).toBeCalledWith({});
    });

    it('should respect passing a custom root', async () => {
      mockArgv('build', 'path/to/root');
-      await import('../cli');
+      await importCli();

      expect(buildMock).toBeCalledWith({
        root: 'path/to/root',
@@ -141,7 +159,7 @@ describe('CLI', () => {

    it('should respect a custom config file', async () => {
      mockArgv('build', '-c', './path/to/config.ts');
-      await import('../cli');
+      await importCli();

      expect(buildMock).toBeCalledWith({
        configFile: './path/to/config.ts',
@@ -150,7 +168,7 @@ describe('CLI', () => {

    it('should respect passing a custom mode', async () => {
      mockArgv('build', '-m', 'development');
-      await import('../cli');
+      await importCli();

      expect(buildMock).toBeCalledWith({
        mode: 'development',
@@ -159,7 +177,7 @@ describe('CLI', () => {

    it('should respect passing a custom browser', async () => {
      mockArgv('build', '-b', 'firefox');
-      await import('../cli');
+      await importCli();

      expect(buildMock).toBeCalledWith({
        browser: 'firefox',
@@ -168,7 +186,7 @@ describe('CLI', () => {

    it('should pass correct filtered entrypoints', async () => {
      mockArgv('build', '-e', 'popup', '-e', 'options');
-      await import('../cli');
+      await importCli();

      expect(buildMock).toBeCalledWith({
        filterEntrypoints: ['popup', 'options'],
@@ -177,7 +195,7 @@ describe('CLI', () => {

    it('should respect passing --mv2', async () => {
      mockArgv('build', '--mv2');
-      await import('../cli');
+      await importCli();

      expect(buildMock).toBeCalledWith({
        manifestVersion: 2,
@@ -186,7 +204,7 @@ describe('CLI', () => {

    it('should respect passing --mv3', async () => {
      mockArgv('build', '--mv3');
-      await import('../cli');
+      await importCli();

      expect(buildMock).toBeCalledWith({
        manifestVersion: 3,
@@ -195,7 +213,7 @@ describe('CLI', () => {

    it('should include analysis in the build', async () => {
      mockArgv('build', '--analyze');
-      await import('../cli');
+      await importCli();

      expect(buildMock).toBeCalledWith({
        analysis: {
@@ -206,7 +224,7 @@ describe('CLI', () => {

    it('should respect passing --debug', async () => {
      mockArgv('build', '--debug');
-      await import('../cli');
+      await importCli();

      expect(buildMock).toBeCalledWith({
        debug: true,
@@ -217,14 +235,14 @@ describe('CLI', () => {
  describe('zip', () => {
    it('should not pass any config when no flags are passed', async () => {
      mockArgv('zip');
-      await import('../cli');
+      await importCli();

      expect(zipMock).toBeCalledWith({});
    });

    it('should respect passing a custom root', async () => {
      mockArgv('zip', 'path/to/root');
-      await import('../cli');
+      await importCli();

      expect(zipMock).toBeCalledWith({
        root: 'path/to/root',
@@ -233,7 +251,7 @@ describe('CLI', () => {

    it('should respect a custom config file', async () => {
      mockArgv('zip', '-c', './path/to/config.ts');
-      await import('../cli');
+      await importCli();

      expect(zipMock).toBeCalledWith({
        configFile: './path/to/config.ts',
@@ -242,7 +260,7 @@ describe('CLI', () => {

    it('should respect passing a custom mode', async () => {
      mockArgv('zip', '-m', 'development');
-      await import('../cli');
+      await importCli();

      expect(zipMock).toBeCalledWith({
        mode: 'development',
@@ -251,7 +269,7 @@ describe('CLI', () => {

    it('should respect passing a custom browser', async () => {
      mockArgv('zip', '-b', 'firefox');
-      await import('../cli');
+      await importCli();

      expect(zipMock).toBeCalledWith({
        browser: 'firefox',
@@ -260,7 +278,7 @@ describe('CLI', () => {

    it('should respect passing --mv2', async () => {
      mockArgv('zip', '--mv2');
-      await import('../cli');
+      await importCli();

      expect(zipMock).toBeCalledWith({
        manifestVersion: 2,
@@ -269,7 +287,7 @@ describe('CLI', () => {

    it('should respect passing --mv3', async () => {
      mockArgv('zip', '--mv3');
-      await import('../cli');
+      await importCli();

      expect(zipMock).toBeCalledWith({
        manifestVersion: 3,
@@ -278,7 +296,7 @@ describe('CLI', () => {

    it('should respect passing --debug', async () => {
      mockArgv('zip', '--debug');
-      await import('../cli');
+      await importCli();

      expect(zipMock).toBeCalledWith({
        debug: true,
@@ -289,14 +307,14 @@ describe('CLI', () => {
  describe('prepare', () => {
    it('should not pass any config when no flags are passed', async () => {
      mockArgv('prepare');
-      await import('../cli');
+      await importCli();

      expect(prepareMock).toBeCalledWith({});
    });

    it('should respect passing a custom root', async () => {
      mockArgv('prepare', 'path/to/root');
-      await import('../cli');
+      await importCli();

      expect(prepareMock).toBeCalledWith({
        root: 'path/to/root',
@@ -305,7 +323,7 @@ describe('CLI', () => {

    it('should respect a custom config file', async () => {
      mockArgv('prepare', '-c', './path/to/config.ts');
-      await import('../cli');
+      await importCli();

      expect(prepareMock).toBeCalledWith({
        configFile: './path/to/config.ts',
@@ -314,7 +332,7 @@ describe('CLI', () => {

    it('should respect passing --debug', async () => {
      mockArgv('prepare', '--debug');
-      await import('../cli');
+      await importCli();

      expect(prepareMock).toBeCalledWith({
        debug: true,
@@ -325,14 +343,14 @@ describe('CLI', () => {
  describe('clean', () => {
    it('should not pass any config when no flags are passed', async () => {
      mockArgv('clean');
-      await import('../cli');
+      await importCli();

      expect(cleanMock).toBeCalledWith(undefined);
    });

    it('should respect passing a custom root', async () => {
      mockArgv('clean', 'path/to/root');
-      await import('../cli');
+      await importCli();

      expect(cleanMock).toBeCalledWith('path/to/root');
    });
@@ -341,14 +359,14 @@ describe('CLI', () => {
  describe('init', () => {
    it('should not pass any options when no flags are passed', async () => {
      mockArgv('init');
-      await import('../cli');
+      await importCli();

      expect(initializeMock).toBeCalledWith({});
    });

    it('should respect the provided folder', async () => {
      mockArgv('init', 'path/to/folder');
-      await import('../cli');
+      await importCli();

      expect(initializeMock).toBeCalledWith({
        directory: 'path/to/folder',
@@ -357,7 +375,7 @@ describe('CLI', () => {

    it('should respect passing --template', async () => {
      mockArgv('init', '-t', 'vue');
-      await import('../cli');
+      await importCli();

      expect(initializeMock).toBeCalledWith({
        template: 'vue',
@@ -366,7 +384,7 @@ describe('CLI', () => {

    it('should respect passing --pm', async () => {
      mockArgv('init', '--pm', 'pnpm');
-      await import('../cli');
+      await importCli();

      expect(initializeMock).toBeCalledWith({
        packageManager: 'pnpm',
@@ -0,0 +1,103 @@
+import { CAC, Command } from 'cac';
+import consola, { LogLevels } from 'consola';
+import { filterTruthy, toArray } from '~/core/utils/arrays';
+import { printHeader } from '~/core/utils/log';
+import { formatDuration } from '~/core/utils/time';
+import { ValidationError } from '~/core/utils/validation';
+import { registerWxt } from '~/core/wxt';
+
+/**
+ * Wrap an action handler to add a timer, error handling, and maybe enable debug mode.
+ */
+export function wrapAction(
+  cb: (
+    ...args: any[]
+  ) => void | { isOngoing?: boolean } | Promise<void | { isOngoing?: boolean }>,
+  options?: {
+    disableFinishedLog?: boolean;
+  },
+) {
+  return async (...args: any[]) => {
+    // Enable consola's debug mode globally at the start of all commands when the `--debug` flag is
+    // passed
+    const isDebug = !!args.find((arg) => arg?.debug);
+    if (isDebug) {
+      consola.level = LogLevels.debug;
+    }
+
+    const startTime = Date.now();
+    try {
+      printHeader();
+
+      const status = await cb(...args);
+
+      if (!status?.isOngoing && !options?.disableFinishedLog)
+        consola.success(
+          `Finished in ${formatDuration(Date.now() - startTime)}`,
+        );
+    } catch (err) {
+      consola.fail(
+        `Command failed after ${formatDuration(Date.now() - startTime)}`,
+      );
+      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
+ */
+export function getArrayFromFlags<T>(
+  flags: any,
+  name: string,
+): T[] | undefined {
+  const array = toArray<T | undefined>(flags[name]);
+  const result = filterTruthy(array);
+  return result.length ? result : undefined;
+}
+
+const aliasCommandNames = new Set<string>();
+/**
+ * @param base Command to add this one to
+ * @param name The command name to add
+ * @param alias The CLI tool being aliased
+ * @param bin The CLI tool binary name. Usually the same as the alias
+ * @param docsUrl URL to the docs for the aliased CLI tool
+ */
+export function createAliasedCommand(
+  base: CAC,
+  name: string,
+  alias: string,
+  bin: string,
+  docsUrl: string,
+) {
+  const aliasedCommand = base
+    .command(name, `Alias for ${alias} (${docsUrl})`)
+    .allowUnknownOptions()
+    .action(async () => {
+      try {
+        await registerWxt('build');
+
+        const args = process.argv.slice(
+          process.argv.indexOf(aliasedCommand.name) + 1,
+        );
+        const { execa } = await import('execa');
+        await execa(bin, args, {
+          stdio: 'inherit',
+        });
+      } catch {
+        // Let the other aliased CLI log errors, just exit
+        process.exit(1);
+      }
+    });
+  aliasCommandNames.add(aliasedCommand.name);
+}
+export function isAliasedCommand(command: Command | undefined): boolean {
+  return !!command && aliasCommandNames.has(command.name);
+}
@@ -1,17 +1,12 @@
 import cac from 'cac';
-import { version } from '~/version';
 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';
+import {
+  createAliasedCommand,
+  getArrayFromFlags,
+  wrapAction,
+} from './cli-utils';

 const cli = cac('wxt');
-cli.help();
-cli.version(version);

 cli.option('--debug', 'enable debug mode');

@@ -21,6 +16,7 @@ cli
  .option('-c, --config <file>', 'use specified config file')
  .option('-m, --mode <mode>', 'set env mode')
  .option('-b, --browser <browser>', 'specify a browser')
+  .option('-p, --port <port>', 'specify a port for the dev server')
  .option(
    '-e, --filter-entrypoint <entrypoint>',
    'only build specific entrypoints',
@@ -40,6 +36,14 @@ cli
        configFile: flags.config,
        debug: flags.debug,
        filterEntrypoints: getArrayFromFlags(flags, 'filterEntrypoint'),
+        dev:
+          flags.port == null
+            ? undefined
+            : {
+                server: {
+                  port: parseInt(flags.port),
+                },
+              },
      });
      await server.start();
      return { isOngoing: true };
@@ -62,6 +66,7 @@ cli
  .option('--mv3', 'target manifest v3')
  .option('--mv2', 'target manifest v2')
  .option('--analyze', 'visualize extension bundle')
+  .option('--analyze-open', 'automatically open stats.html in browser')
  .action(
    wrapAction(async (root, flags) => {
      await build({
@@ -71,7 +76,12 @@ cli
        manifestVersion: flags.mv3 ? 3 : flags.mv2 ? 2 : undefined,
        configFile: flags.config,
        debug: flags.debug,
-        analysis: flags.analyze ? { enabled: true } : undefined,
+        analysis: flags.analyze
+          ? {
+              enabled: true,
+              open: flags.analyzeOpen,
+            }
+          : undefined,
        filterEntrypoints: getArrayFromFlags(flags, 'filterEntrypoint'),
      });
    }),
@@ -140,57 +150,13 @@ cli
    ),
  );

-cli.parse(process.argv);
+// SUBMIT
+createAliasedCommand(
+  cli,
+  'submit',
+  'publish-extension',
+  'wxt-publish-extension',
+  'https://www.npmjs.com/publish-browser-extension',
+);

-/**
- * Wrap an action handler to add a timer, error handling, and maybe enable debug mode.
- */
-function wrapAction(
-  cb: (
-    ...args: any[]
-  ) => void | { isOngoing?: boolean } | Promise<void | { isOngoing?: boolean }>,
-  options?: {
-    disableFinishedLog?: boolean;
-  },
-) {
-  return async (...args: any[]) => {
-    // Enable consola's debug mode globally at the start of all commands when the `--debug` flag is
-    // passed
-    const isDebug = !!args.find((arg) => arg?.debug);
-    if (isDebug) {
-      consola.level = LogLevels.debug;
-    }
-
-    const startTime = Date.now();
-    try {
-      printHeader();
-
-      const status = await cb(...args);
-
-      if (!status?.isOngoing && !options?.disableFinishedLog)
-        consola.success(
-          `Finished in ${formatDuration(Date.now() - startTime)}`,
-        );
-    } catch (err) {
-      consola.fail(
-        `Command failed after ${formatDuration(Date.now() - startTime)}`,
-      );
-      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;
-}
+export default cli;
@@ -0,0 +1,19 @@
+import cli from './commands';
+import { version } from '~/version';
+import { isAliasedCommand } from './cli-utils';
+
+// TODO: Remove. See https://github.com/wxt-dev/wxt/issues/277
+process.env.VITE_CJS_IGNORE_WARNING = 'true';
+
+// Grab the command that we're trying to run
+cli.parse(process.argv, { run: false });
+
+// If it's not an alias, add the help and version options, then parse again
+if (!isAliasedCommand(cli.matchedCommand)) {
+  cli.help();
+  cli.version(version);
+  cli.parse(process.argv, { run: false });
+}
+
+// Run the alias or command
+await cli.runMatchedCommand();
@@ -10,6 +10,29 @@ import { createLocationWatcher } from './location-watcher';
 *
 * It also provides several utilities like `ctx.setTimeout` and `ctx.setInterval` that should be used in
 * content scripts instead of `window.setTimeout` or `window.setInterval`.
+ *
+ * To create context for testing, you can use the class's constructor:
+ *
+ * ```ts
+ * import { ContentScriptContext } from 'wxt/client';
+ *
+ * test("storage listener should be removed when context is invalidated", () => {
+ *   const ctx = new ContentScriptContext('test');
+ *   const item = storage.defineItem("local:count", { defaultValue: 0 });
+ *   const watcher = vi.fn();
+ *
+ *   const unwatch = item.watch(watcher);
+ *   ctx.onInvalidated(unwatch); // Listen for invalidate here
+ *
+ *   await item.setValue(1);
+ *   expect(watcher).toBeCalledTimes(1);
+ *   expect(watcher).toBeCalledWith(1, 0);
+ *
+ *   ctx.notifyInvalidated(); // Use this function to invalidate the context
+ *   await item.setValue(2);
+ *   expect(watcher).toBeCalledTimes(1);
+ * });
+ * ```
 */
 export class ContentScriptContext implements AbortController {
  private static SCRIPT_STARTED_MESSAGE_TYPE = 'wxt:content-script-started';
@@ -367,7 +367,7 @@ describe('Content Script UIs', () => {
      });
    });

-    describe.todo('after', () => {
+    describe('after', () => {
      it('should append the UI after the anchor', () => {
        const ui = createIntegratedUi(ctx, {
          position: 'inline',
@@ -119,19 +119,18 @@ export async function createShadowRootUi<TMounted>(
  let mounted: TMounted;

  const mount = () => {
-    // Mount UI inside shadow root
-    mounted = options.onMount(uiContainer, shadow, shadowHost);
-
    // Add shadow root element to DOM
    mountUi(shadowHost, options);
    applyPosition(shadowHost, shadow.querySelector('html'), options);
+    // Mount UI inside shadow root
+    mounted = options.onMount(uiContainer, shadow, shadowHost);
  };

  const remove = () => {
-    // Detatch shadow root from DOM
-    shadowHost.remove();
    // Cleanup mounted state
    options.onRemove?.(mounted);
+    // Detatch shadow root from DOM
+    shadowHost.remove();
    // Remove children from uiContainer
    while (uiContainer.lastChild)
      uiContainer.removeChild(uiContainer.lastChild);
@@ -211,20 +210,16 @@ function mountUi(
      anchor.append(root);
      break;
    case 'first':
-      if (anchor.firstChild) {
-        anchor.insertBefore(root, anchor.firstChild);
-      } else {
-        anchor.append(root);
-      }
+      anchor.prepend(root);
      break;
    case 'replace':
      anchor.replaceWith(root);
      break;
    case 'after':
-      anchor.replaceWith(anchor, root);
+      anchor.parentElement?.insertBefore(root, anchor.nextElementSibling);
      break;
    case 'before':
-      anchor.replaceWith(root, anchor);
+      anchor.parentElement?.insertBefore(root, anchor);
      break;
    default:
      options.append(anchor, root);
@@ -207,7 +207,7 @@ export interface ContentScriptAnchoredOptions {
   * 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
+   * - `"first"` - Add the UI as the first 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
@@ -1,5 +1,6 @@
 import { BuildOutput, InlineConfig } from '~/types';
-import { getInternalConfig, internalBuild } from './utils/building';
+import { internalBuild } from './utils/building';
+import { registerWxt } from './wxt';

 /**
 * Bundles the extension for production. Returns a promise of the build result. Discovers the `wxt.config.ts` file in
@@ -15,6 +16,7 @@ import { getInternalConfig, internalBuild } from './utils/building';
 * })
 */
 export async function build(config?: InlineConfig): Promise<BuildOutput> {
-  const internalConfig = await getInternalConfig(config ?? {}, 'build');
-  return await internalBuild(internalConfig);
+  await registerWxt('build', config);
+
+  return await internalBuild();
 }
@@ -2,20 +2,24 @@ import type * as vite from 'vite';
 import {
  BuildStepOutput,
  Entrypoint,
-  InlineConfig,
-  InternalConfig,
-  UserConfig,
-  VirtualEntrypointType,
+  ResolvedConfig,
  WxtBuilder,
  WxtBuilderServer,
+  WxtDevServer,
 } from '~/types';
 import * as wxtPlugins from './plugins';
-import { getEntrypointBundlePath } from '~/core/utils/entrypoints';
+import {
+  getEntrypointBundlePath,
+  isHtmlEntrypoint,
+} from '~/core/utils/entrypoints';
+import {
+  VirtualEntrypointType,
+  VirtualModuleId,
+} from '~/core/utils/virtual-modules';

 export async function createViteBuilder(
-  inlineConfig: InlineConfig,
-  userConfig: UserConfig,
-  wxtConfig: Omit<InternalConfig, 'builder'>,
+  wxtConfig: ResolvedConfig,
+  server?: WxtDevServer,
 ): Promise<WxtBuilder> {
  const vite = await import('vite');

@@ -23,14 +27,7 @@ export async function createViteBuilder(
   * Returns the base vite config shared by all builds based on the inline and user config.
   */
  const getBaseConfig = async () => {
-    const resolvedInlineConfig =
-      (await inlineConfig.vite?.(wxtConfig.env)) ?? {};
-    const resolvedUserConfig = (await userConfig.vite?.(wxtConfig.env)) ?? {};
-
-    const config: vite.InlineConfig = vite.mergeConfig(
-      resolvedUserConfig,
-      resolvedInlineConfig,
-    );
+    const config: vite.InlineConfig = await wxtConfig.vite(wxtConfig.env);

    config.root = wxtConfig.root;
    config.configFile = false;
@@ -38,6 +35,8 @@ export async function createViteBuilder(
    config.mode = wxtConfig.mode;

    config.build ??= {};
+    config.publicDir = wxtConfig.publicDir;
+    config.build.copyPublicDir = false;
    config.build.outDir = wxtConfig.outDir;
    config.build.emptyOutDir = false;
    // Disable minification for the dev command
@@ -52,20 +51,18 @@ export async function createViteBuilder(
    config.plugins ??= [];
    config.plugins.push(
      wxtPlugins.download(wxtConfig),
-      wxtPlugins.devHtmlPrerender(wxtConfig),
+      wxtPlugins.devHtmlPrerender(wxtConfig, server),
      wxtPlugins.unimport(wxtConfig),
-      wxtPlugins.virtualEntrypoint('background', wxtConfig),
-      wxtPlugins.virtualEntrypoint('content-script-isolated-world', wxtConfig),
-      wxtPlugins.virtualEntrypoint('content-script-main-world', wxtConfig),
-      wxtPlugins.virtualEntrypoint('unlisted-script', wxtConfig),
-      wxtPlugins.devServerGlobals(wxtConfig),
+      wxtPlugins.resolveVirtualModules(wxtConfig),
+      wxtPlugins.devServerGlobals(wxtConfig, server),
      wxtPlugins.tsconfigPaths(wxtConfig),
      wxtPlugins.noopBackground(),
      wxtPlugins.globals(wxtConfig),
      wxtPlugins.excludeBrowserPolyfill(wxtConfig),
+      wxtPlugins.defineImportMeta(),
    );
    if (wxtConfig.analysis.enabled) {
-      config.plugins.push(wxtPlugins.bundleAnalysis());
+      config.plugins.push(wxtPlugins.bundleAnalysis(wxtConfig));
    }

    return config;
@@ -75,23 +72,7 @@ export async function createViteBuilder(
   * Return the basic config for building an entrypoint in [lib mode](https://vitejs.dev/guide/build.html#library-mode).
   */
  const getLibModeConfig = (entrypoint: Entrypoint): vite.InlineConfig => {
-    let virtualEntrypointType: VirtualEntrypointType | undefined;
-    switch (entrypoint.type) {
-      case 'background':
-      case 'unlisted-script':
-        virtualEntrypointType = entrypoint.type;
-        break;
-      case 'content-script':
-        virtualEntrypointType =
-          entrypoint.options.world === 'MAIN'
-            ? 'content-script-main-world'
-            : 'content-script-isolated-world';
-        break;
-    }
-    const entry = virtualEntrypointType
-      ? `virtual:wxt-${virtualEntrypointType}?${entrypoint.inputPath}`
-      : entrypoint.inputPath;
-
+    const entry = getRollupEntry(entrypoint);
    const plugins: NonNullable<vite.UserConfig['plugins']> = [
      wxtPlugins.entrypointGroupGlobals(entrypoint),
    ];
@@ -148,6 +129,9 @@ export async function createViteBuilder(
   * Return the basic config for building multiple entrypoints in [multi-page mode](https://vitejs.dev/guide/build.html#multi-page-app).
   */
  const getMultiPageConfig = (entrypoints: Entrypoint[]): vite.InlineConfig => {
+    const htmlEntrypoints = new Set(
+      entrypoints.filter(isHtmlEntrypoint).map((e) => e.name),
+    );
    return {
      mode: wxtConfig.mode,
      plugins: [
@@ -157,14 +141,18 @@ export async function createViteBuilder(
      build: {
        rollupOptions: {
          input: entrypoints.reduce<Record<string, string>>((input, entry) => {
-            input[entry.name] = entry.inputPath;
+            input[entry.name] = getRollupEntry(entry);
            return input;
          }, {}),
          output: {
            // Include a hash to prevent conflicts
            chunkFileNames: 'chunks/[name]-[hash].js',
-            // Include a hash to prevent conflicts
-            entryFileNames: 'chunks/[name]-[hash].js',
+            entryFileNames: ({ name }) => {
+              // HTML main JS files go in the chunks folder
+              if (htmlEntrypoints.has(name)) return 'chunks/[name]-[hash].js';
+              // Scripts are output in the root folder
+              return '[name].js';
+            },
            // We can't control the "name", so we need a hash to prevent conflicts
            assetFileNames: 'assets/[name]-[hash].[ext]',
          },
@@ -263,3 +251,29 @@ function getBuildOutputChunks(
  if (Array.isArray(result)) return result.flatMap(({ output }) => output);
  return result.output;
 }
+
+/**
+ * Returns the input module ID (virtual or real file) for an entrypoint. The returned string should
+ * be passed as an input to rollup.
+ */
+function getRollupEntry(entrypoint: Entrypoint): string {
+  let virtualEntrypointType: VirtualEntrypointType | undefined;
+  switch (entrypoint.type) {
+    case 'background':
+    case 'unlisted-script':
+      virtualEntrypointType = entrypoint.type;
+      break;
+    case 'content-script':
+      virtualEntrypointType =
+        entrypoint.options.world === 'MAIN'
+          ? 'content-script-main-world'
+          : 'content-script-isolated-world';
+      break;
+  }
+
+  if (virtualEntrypointType) {
+    const moduleId: VirtualModuleId = `virtual:wxt-${virtualEntrypointType}-entrypoint`;
+    return `${moduleId}?${entrypoint.inputPath}`;
+  }
+  return entrypoint.inputPath;
+}
@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'vitest';
+import { Window } from 'happy-dom';
+import { pointToDevServer } from '../devHtmlPrerender';
+import {
+  fakeDevServer,
+  fakeResolvedConfig,
+} from '~/core/utils/testing/fake-objects';
+import { normalizePath } from '~/core/utils/paths';
+import { resolve } from 'node:path';
+
+describe('Dev HTML Prerender Plugin', () => {
+  describe('pointToDevServer', () => {
+    it.each([
+      // File paths should be resolved
+      ['style.css', 'http://localhost:5173/entrypoints/popup/style.css'],
+      ['./style.css', 'http://localhost:5173/entrypoints/popup/style.css'],
+      ['../style.css', 'http://localhost:5173/entrypoints/style.css'],
+      ['~/assets/style.css', 'http://localhost:5173/assets/style.css'],
+      ['~~/assets/style.css', 'http://localhost:5173/assets/style.css'],
+      ['~local/style.css', 'http://localhost:5173/style.css'],
+      ['~absolute/style.css', 'http://localhost:5173/assets/style.css'],
+      ['~file', 'http://localhost:5173/example.css'],
+      // Absolute paths are loaded with the `/@fs/` base path
+      [
+        '~outside/test.css',
+        `http://localhost:5173/@fs${
+          process.platform === 'win32'
+            ? '/' + normalizePath(resolve('/some/non-root/test.css')) // "/D:/some/non-root/test.css"
+            : '/some/non-root/test.css'
+        }`,
+      ],
+      // URLs should not be changed
+      ['https://example.com/style.css', 'https://example.com/style.css'],
+    ])('should transform "%s" into "%s"', (input, expected) => {
+      const { document } = new Window({
+        url: 'http://localhost',
+      });
+      const root = '/some/root';
+      const config = fakeResolvedConfig({
+        root,
+        alias: {
+          '~local': '.',
+          '~absolute': `${root}/assets`,
+          '~file': `${root}/example.css`,
+          '~outside': `${root}/../non-root`,
+          '~~': root,
+          '~': root,
+        },
+      });
+      const server = fakeDevServer({
+        hostname: 'localhost',
+        port: 5173,
+        origin: 'http://localhost:5173',
+      });
+      const id = root + '/entrypoints/popup/index.html';
+
+      document.head.innerHTML = `<link rel="stylesheet" href="${input}" />`;
+      pointToDevServer(config, server, id, document as any, 'link', 'href');
+
+      const actual = document.querySelector('link')!;
+      expect(actual.getAttribute('href')).toBe(expected);
+    });
+  });
+});
@@ -1,12 +1,25 @@
 import type * as vite from 'vite';
-import { visualizer } from 'rollup-plugin-visualizer';
+import { visualizer } from '@aklinker1/rollup-plugin-visualizer';
+import { ResolvedConfig } from '~/types';
+import path from 'node:path';

 let increment = 0;

-export function bundleAnalysis(): vite.Plugin {
+export function bundleAnalysis(
+  config: Omit<ResolvedConfig, 'builder'>,
+): vite.Plugin {
  return visualizer({
-    emitFile: true,
    template: 'raw-data',
-    filename: `stats-${increment++}.json`,
-  }) as vite.Plugin;
+    filename: path.resolve(
+      config.analysis.outputDir,
+      `${config.analysis.outputName}-${increment++}.json`,
+    ),
+  });
+}
+
+/**
+ * @deprecated FOR TESTING ONLY.
+ */
+export function resetBundleIncrement() {
+  increment = 0;
 }
@@ -1,5 +1,5 @@
 import type * as vite from 'vite';
-import { Entrypoint, InternalConfig } from '~/types';
+import { Entrypoint, ResolvedConfig } from '~/types';
 import { getEntrypointBundlePath } from '~/core/utils/entrypoints';

 /**
@@ -14,7 +14,7 @@ import { getEntrypointBundlePath } from '~/core/utils/entrypoints';
 */
 export function cssEntrypoints(
  entrypoint: Entrypoint,
-  config: Omit<InternalConfig, 'builder'>,
+  config: Omit<ResolvedConfig, 'builder'>,
 ): vite.Plugin {
  return {
    name: 'wxt:css-entrypoint',
@@ -0,0 +1,19 @@
+/**
+ * Overrides definitions for `import.meta.*`
+ *
+ * - `import.meta.url`: Without this, background service workers crash trying to access
+ *   `document.location`, see https://github.com/wxt-dev/wxt/issues/392
+ */
+export function defineImportMeta() {
+  return {
+    name: 'wxt:define',
+    config() {
+      return {
+        define: {
+          // This works for all extension contexts, including background service worker
+          'import.meta.url': 'self.location.href',
+        },
+      };
+    },
+  };
+}
@@ -1,8 +1,9 @@
 import type * as vite from 'vite';
-import { InternalConfig } from '~/types';
+import { ResolvedConfig, WxtDevServer } from '~/types';
 import { getEntrypointName } from '~/core/utils/entrypoints';
 import { parseHTML } from 'linkedom';
-import { dirname, isAbsolute, relative, resolve } from 'node:path';
+import { dirname, relative, resolve } from 'node:path';
+import { normalizePath } from '~/core/utils/paths';

 // Cache the preamble script for all devHtmlPrerender plugins, not just one
 let reactRefreshPreamble = '';
@@ -11,12 +12,13 @@ let reactRefreshPreamble = '';
 * Pre-renders the HTML entrypoints when building the extension to connect to the dev server.
 */
 export function devHtmlPrerender(
-  config: Omit<InternalConfig, 'builder'>,
+  config: Omit<ResolvedConfig, 'builder'>,
+  server: WxtDevServer | undefined,
 ): vite.PluginOption {
  const htmlReloadId = '@wxt/reload-html';
  const resolvedHtmlReloadId = resolve(
-    config.root,
-    'node_modules/wxt/dist/virtual/reload-html.js',
+    config.wxtModuleDir,
+    'dist/virtual/reload-html.js',
  );
  const virtualReactRefreshId = '@wxt/virtual-react-refresh';
  const resolvedVirtualReactRefreshId = '\0' + virtualReactRefreshId;
@@ -37,7 +39,6 @@ export function devHtmlPrerender(
      // Convert scripts like src="./main.tsx" -> src="http://localhost:3000/entrypoints/popup/main.tsx"
      // before the paths are replaced with their bundled path
      transform(code, id) {
-        const server = config.server;
        if (
          config.command !== 'serve' ||
          server == null ||
@@ -47,25 +48,10 @@ export function devHtmlPrerender(

        const { document } = parseHTML(code);

-        const pointToDevServer = (
-          querySelector: string,
-          attr: string,
-        ): void => {
-          document.querySelectorAll(querySelector).forEach((element) => {
-            const src = element.getAttribute(attr);
-            if (!src) return;
-
-            if (isAbsolute(src)) {
-              element.setAttribute(attr, server.origin + src);
-            } else if (src.startsWith('.')) {
-              const abs = resolve(dirname(id), src);
-              const pathname = relative(config.root, abs);
-              element.setAttribute(attr, `${server.origin}/${pathname}`);
-            }
-          });
-        };
-        pointToDevServer('script[type=module]', 'src');
-        pointToDevServer('link[rel=stylesheet]', 'href');
+        const _pointToDevServer = (querySelector: string, attr: string) =>
+          pointToDevServer(config, server, id, document, querySelector, attr);
+        _pointToDevServer('script[type=module]', 'src');
+        _pointToDevServer('link[rel=stylesheet]', 'href');

        // Add a script to add page reloading
        const reloader = document.createElement('script');
@@ -82,7 +68,6 @@ export function devHtmlPrerender(

      // Pass the HTML through the dev server to add dev-mode specific code
      async transformIndexHtml(html, ctx) {
-        const server = config.server;
        if (config.command !== 'serve' || server == null) return;

        const originalUrl = `${server.origin}${ctx.path}`;
@@ -146,3 +131,63 @@ export function devHtmlPrerender(
    },
  ];
 }
+
+export function pointToDevServer(
+  config: Omit<ResolvedConfig, 'builder'>,
+  server: WxtDevServer,
+  id: string,
+  document: Document,
+  querySelector: string,
+  attr: string,
+) {
+  document.querySelectorAll(querySelector).forEach((element) => {
+    const src = element.getAttribute(attr);
+    if (!src || isUrl(src)) return;
+
+    let resolvedAbsolutePath: string | undefined;
+
+    // Check if src uses a project alias
+    const matchingAlias = Object.entries(config.alias).find(([key]) =>
+      src.startsWith(key),
+    );
+    if (matchingAlias) {
+      // Matches a import alias
+      const [alias, replacement] = matchingAlias;
+      resolvedAbsolutePath = resolve(
+        config.root,
+        src.replace(alias, replacement),
+      );
+    } else {
+      // Some file path relative to the HTML file
+      resolvedAbsolutePath = resolve(dirname(id), src);
+    }
+
+    // Apply the final file path
+    if (resolvedAbsolutePath) {
+      const relativePath = normalizePath(
+        relative(config.root, resolvedAbsolutePath),
+      );
+
+      if (relativePath.startsWith('.')) {
+        // Outside the config.root directory, serve the absolute path
+        let path = normalizePath(resolvedAbsolutePath);
+        // Add "/" to start of windows paths ("D:/some/path" -> "/D:/some/path")
+        if (!path.startsWith('/')) path = '/' + path;
+        element.setAttribute(attr, `${server.origin}/@fs${path}`);
+      } else {
+        // Inside the project, use relative path
+        const url = new URL(relativePath, server.origin);
+        element.setAttribute(attr, url.href);
+      }
+    }
+  });
+}
+
+function isUrl(str: string): boolean {
+  try {
+    new URL(str);
+    return true;
+  } catch {
+    return false;
+  }
+}
@@ -1,22 +1,23 @@
 import { Plugin } from 'vite';
-import { InternalConfig } from '~/types';
+import { ResolvedConfig, WxtDevServer } from '~/types';

 /**
 * Defines global constants about the dev server. Helps scripts connect to the server's web socket.
 */
 export function devServerGlobals(
-  config: Omit<InternalConfig, 'builder'>,
+  config: Omit<ResolvedConfig, 'builder'>,
+  server: WxtDevServer | undefined,
 ): Plugin {
  return {
    name: 'wxt:dev-server-globals',
    config() {
-      if (config.server == null || config.command == 'build') return;
+      if (server == null || config.command == 'build') return;

      return {
        define: {
          __DEV_SERVER_PROTOCOL__: JSON.stringify('ws:'),
-          __DEV_SERVER_HOSTNAME__: JSON.stringify(config.server.hostname),
-          __DEV_SERVER_PORT__: JSON.stringify(config.server.port),
+          __DEV_SERVER_HOSTNAME__: JSON.stringify(server.hostname),
+          __DEV_SERVER_PORT__: JSON.stringify(server.port),
        },
      };
    },
@@ -1,5 +1,5 @@
 import { Plugin } from 'vite';
-import { InternalConfig } from '~/types';
+import { ResolvedConfig } from '~/types';
 import { fetchCached } from '~/core/utils/network';

 /**
@@ -9,7 +9,7 @@ import { fetchCached } from '~/core/utils/network';
 * @example
 * import "url:https://google-tagmanager.com/gtag?id=XYZ";
 */
-export function download(config: Omit<InternalConfig, 'builder'>): Plugin {
+export function download(config: Omit<ResolvedConfig, 'builder'>): Plugin {
  return {
    name: 'wxt:download',
    resolveId(id) {
@@ -1,4 +1,4 @@
-import { InternalConfig } from '~/types';
+import { ResolvedConfig } from '~/types';
 import type * as vite from 'vite';

 /**
@@ -7,7 +7,7 @@ import type * as vite from 'vite';
 * virtual module.
 */
 export function excludeBrowserPolyfill(
-  config: Omit<InternalConfig, 'builder'>,
+  config: Omit<ResolvedConfig, 'builder'>,
 ): vite.Plugin {
  const virtualId = 'virtual:wxt-webextension-polyfill-disabled';

@@ -1,9 +1,9 @@
 import type * as vite from 'vite';
-import { InternalConfig } from '~/types';
+import { ResolvedConfig } from '~/types';
 import { getGlobals } from '~/core/utils/globals';

 export function globals(
-  config: Omit<InternalConfig, 'builder'>,
+  config: Omit<ResolvedConfig, 'builder'>,
 ): vite.PluginOption {
  return {
    name: 'wxt:globals',
@@ -3,7 +3,7 @@ export * from './devServerGlobals';
 export * from './download';
 export * from './multipageMove';
 export * from './unimport';
-export * from './virtualEntrypoint';
+export * from './resolveVirtualModules';
 export * from './tsconfigPaths';
 export * from './noopBackground';
 export * from './cssEntrypoints';
@@ -12,3 +12,4 @@ export * from './globals';
 export * from './webextensionPolyfillMock';
 export * from './excludeBrowserPolyfill';
 export * from './entrypointGroupGlobals';
+export * from './defineImportMeta';
@@ -1,5 +1,5 @@
 import type * as vite from 'vite';
-import { Entrypoint, InternalConfig } from '~/types';
+import { Entrypoint, ResolvedConfig } from '~/types';
 import { dirname, extname, resolve, join } from 'node:path';
 import { getEntrypointBundlePath } from '~/core/utils/entrypoints';
 import fs, { ensureDir } from 'fs-extra';
@@ -20,7 +20,7 @@ import { normalizePath } from '~/core/utils/paths';
 */
 export function multipageMove(
  entrypoints: Entrypoint[],
-  config: Omit<InternalConfig, 'builder'>,
+  config: Omit<ResolvedConfig, 'builder'>,
 ): vite.Plugin {
  return {
    name: 'wxt:multipage-move',
@@ -0,0 +1,41 @@
+import { Plugin } from 'vite';
+import { ResolvedConfig } from '~/types';
+import { normalizePath } from '~/core/utils/paths';
+import {
+  VirtualModuleId,
+  virtualModuleNames,
+} from '~/core/utils/virtual-modules';
+import fs from 'fs-extra';
+import { resolve } from 'path';
+
+/**
+ * Resolve all the virtual modules to the `node_modules/wxt/dist/virtual` directory.
+ */
+export function resolveVirtualModules(config: ResolvedConfig): Plugin[] {
+  return virtualModuleNames.map((name) => {
+    const virtualId: `${VirtualModuleId}?` = `virtual:wxt-${name}?`;
+    const resolvedVirtualId = '\0' + virtualId;
+    return {
+      name: `wxt:resolve-virtual-${name}`,
+      resolveId(id) {
+        // Id doesn't start with prefix, it looks like this:
+        // /path/to/project/virtual:wxt-background?/path/to/project/entrypoints/background.ts
+        const index = id.indexOf(virtualId);
+        if (index === -1) return;
+
+        const inputPath = normalizePath(id.substring(index + virtualId.length));
+        return resolvedVirtualId + inputPath;
+      },
+      async load(id) {
+        if (!id.startsWith(resolvedVirtualId)) return;
+
+        const inputPath = id.replace(resolvedVirtualId, '');
+        const template = await fs.readFile(
+          resolve(config.wxtModuleDir, `dist/virtual/${name}.js`),
+          'utf-8',
+        );
+        return template.replace(`virtual:user-${name}`, inputPath);
+      },
+    };
+  });
+}
@@ -1,8 +1,8 @@
-import { InternalConfig } from '~/types';
+import { ResolvedConfig } from '~/types';
 import type * as vite from 'vite';

 export function tsconfigPaths(
-  config: Omit<InternalConfig, 'builder'>,
+  config: Omit<ResolvedConfig, 'builder'>,
 ): vite.Plugin {
  return {
    name: 'wxt:aliases',
@@ -1,6 +1,5 @@
 import { createUnimport } from 'unimport';
-import { InternalConfig } from '~/types';
-import { getUnimportOptions } from '~/core/utils/unimport';
+import { ResolvedConfig } from '~/types';
 import type * as vite from 'vite';
 import { extname } from 'path';

@@ -17,9 +16,9 @@ const ENABLED_EXTENSIONS = new Set([
 * Inject any global imports defined by unimport
 */
 export function unimport(
-  config: Omit<InternalConfig, 'builder'>,
+  config: Omit<ResolvedConfig, 'builder'>,
 ): vite.PluginOption {
-  const options = getUnimportOptions(config);
+  const options = config.imports;
  if (options === false) return [];

  const unimport = createUnimport(options);
@@ -1,42 +0,0 @@
-import { Plugin } from 'vite';
-import { InternalConfig, VirtualEntrypointType } from '~/types';
-import fs from 'fs-extra';
-import { resolve } from 'path';
-import { normalizePath } from '~/core/utils/paths';
-
-/**
- * Wraps a user's entrypoint with a vitual version with additional logic.
- */
-export function virtualEntrypoint(
-  type: VirtualEntrypointType,
-  config: Omit<InternalConfig, 'builder'>,
-): Plugin {
-  const virtualId = `virtual:wxt-${type}?`;
-  const resolvedVirtualId = `\0${virtualId}`;
-
-  return {
-    name: `wxt:virtual-entrypoint`,
-    resolveId(id) {
-      // Id doesn't start with prefix, it looks like this:
-      // /path/to/project/virtual:background?/path/to/project/entrypoints/background.ts
-      const index = id.indexOf(virtualId);
-      if (index === -1) return;
-
-      const inputPath = normalizePath(id.substring(index + virtualId.length));
-      return resolvedVirtualId + inputPath;
-    },
-    async load(id) {
-      if (!id.startsWith(resolvedVirtualId)) return;
-
-      const inputPath = id.replace(resolvedVirtualId, '');
-      const template = await fs.readFile(
-        resolve(
-          config.root,
-          `node_modules/wxt/dist/virtual/${type}-entrypoint.js`,
-        ),
-        'utf-8',
-      );
-      return template.replace(`virtual:user-${type}`, inputPath);
-    },
-  };
-}
@@ -1,6 +1,6 @@
 import path from 'node:path';
 import type * as vite from 'vite';
-import { InternalConfig } from '~/types';
+import { ResolvedConfig } from '~/types';

 /**
 * Mock `webextension-polyfill` by inlining all dependencies that import it and adding a custom
@@ -16,7 +16,7 @@ import { InternalConfig } from '~/types';
 * `npm list` and inline them automatically.
 */
 export function webextensionPolyfillMock(
-  config: Omit<InternalConfig, 'builder'>,
+  config: Omit<ResolvedConfig, 'builder'>,
 ): vite.PluginOption {
  return {
    name: 'wxt:testing-inline-deps',
@@ -26,8 +26,8 @@ export function webextensionPolyfillMock(
          alias: {
            // Alias to use a mocked version of the polyfill
            'webextension-polyfill': path.resolve(
-              config.root,
-              'node_modules/wxt/dist/virtual/mock-browser',
+              config.wxtModuleDir,
+              'dist/virtual/mock-browser',
            ),
          },
        },
@@ -2,14 +2,12 @@ import {
  BuildStepOutput,
  EntrypointGroup,
  InlineConfig,
-  InternalConfig,
  ServerInfo,
  WxtDevServer,
 } from '~/types';
 import {
  getEntrypointBundlePath,
-  getEntrypointOutputFile,
-  resolvePerBrowserOption,
+  isHtmlEntrypoint,
 } from '~/core/utils/entrypoints';
 import {
  getContentScriptCssFiles,
@@ -17,7 +15,6 @@ import {
 } from '~/core/utils/manifest';
 import {
  internalBuild,
-  getInternalConfig,
  detectDevChanges,
  rebuild,
  findEntrypoints,
@@ -27,6 +24,12 @@ import { consola } from 'consola';
 import { Mutex } from 'async-mutex';
 import pc from 'picocolors';
 import { relative } from 'node:path';
+import { registerWxt, wxt } from './wxt';
+import { unnormalizePath } from './utils/paths';
+import {
+  getContentScriptJs,
+  mapWxtOptionsToRegisteredContentScript,
+} from './utils/content-scripts';

 /**
 * Creates a dev server and pre-builds all the files that need to exist before loading the extension.
@@ -40,21 +43,78 @@ import { relative } from 'node:path';
 export async function createServer(
  inlineConfig?: InlineConfig,
 ): Promise<WxtDevServer> {
-  const port = await getPort();
-  const hostname = 'localhost';
-  const origin = `http://${hostname}:${port}`;
-  const serverInfo: ServerInfo = {
-    port,
-    hostname,
-    origin,
-  };
+  await registerWxt('serve', inlineConfig, async (config) => {
+    const { port, hostname } = config.dev.server!;
+    const serverInfo: ServerInfo = {
+      port,
+      hostname,
+      origin: `http://${hostname}:${port}`,
+    };
+
+    // 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,
+      get watcher() {
+        return builderServer.watcher;
+      },
+      get ws() {
+        return builderServer.ws;
+      },
+      currentOutput: undefined,
+      async start() {
+        await builderServer.listen();
+        wxt.logger.success(`Started dev server @ ${serverInfo.origin}`);
+        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);
+      },
+      reloadContentScript(payload) {
+        server.ws.send('wxt:reload-content-script', payload);
+      },
+      reloadPage(path) {
+        server.ws.send('wxt:reload-page', path);
+      },
+      reloadExtension() {
+        server.ws.send('wxt:reload-extension');
+      },
+      async restartBrowser() {
+        await closeAndRecreateRunner();
+        await runner.openBrowser();
+      },
+    };
+    return server;
+  });
+
+  const server = wxt.server!;
+  let [runner, builderServer] = await Promise.all([
+    createExtensionRunner(),
+    wxt.builder.createServer(server),
+  ]);

  const buildAndOpenBrowser = async () => {
    // Build after starting the dev server so it can be used to transform HTML files
-    server.currentOutput = await internalBuild(config);
+    server.currentOutput = await internalBuild();
+
+    // Add file watchers for files not loaded by the dev server. See
+    // https://github.com/wxt-dev/wxt/issues/428#issuecomment-1944731870
+    try {
+      server.watcher.add(getExternalOutputDependencies(server));
+    } catch (err) {
+      wxt.config.logger.warn('Failed to register additional file paths:', err);
+    }

    // Open browser after everything is ready to go.
-    await runner.openBrowser(config);
+    await runner.openBrowser();
  };

  /**
@@ -62,105 +122,37 @@ export async function createServer(
   */
  const closeAndRecreateRunner = async () => {
    await runner.closeBrowser();
-    config = await getLatestConfig();
-    runner = await createExtensionRunner(config);
+    await wxt.reloadConfig();
+    runner = await createExtensionRunner();
  };

-  // 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,
-    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}`);
-      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);
-    },
-    reloadContentScript(contentScript) {
-      server.ws.send('wxt:reload-content-script', contentScript);
-    },
-    reloadPage(path) {
-      server.ws.send('wxt:reload-page', path);
-    },
-    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();
-
-  let [runner, builderServer] = await Promise.all([
-    createExtensionRunner(config),
-    config.builder.createServer(server),
-  ]);
-
  // 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);
+    reloadContentScripts(server.currentOutput.steps, server);
  });

  // Listen for file changes and reload different parts of the extension accordingly
-  const reloadOnChange = createFileReloader({
-    server,
-    getLatestConfig,
-    updateConfig(newConfig) {
-      config = newConfig;
-    },
-  });
+  const reloadOnChange = createFileReloader(server);
  server.watcher.on('all', reloadOnChange);

  return server;
 }

-async function getPort(): Promise<number> {
-  const { default: getPort, portNumbers } = await import('get-port');
-  return await getPort({ port: portNumbers(3000, 3010) });
-}
-
 /**
 * Returns a function responsible for reloading different parts of the extension when a file
 * changes.
 */
-function createFileReloader(options: {
-  server: WxtDevServer;
-  getLatestConfig: () => Promise<InternalConfig>;
-  updateConfig: (config: InternalConfig) => void;
-}) {
-  const { server, getLatestConfig, updateConfig } = options;
+function createFileReloader(server: WxtDevServer) {
  const fileChangedMutex = new Mutex();
  const changeQueue: Array<[string, string]> = [];

  return async (event: string, path: string) => {
-    const config = await getLatestConfig();
-    updateConfig(config);
+    await wxt.reloadConfig();

    // Here, "path" is a non-normalized path (ie: C:\\users\\... instead of C:/users/...)
-    if (path.startsWith(config.outBaseDir)) return;
+    if (path.startsWith(wxt.config.outBaseDir)) return;
    changeQueue.push([event, path]);

    await fileChangedMutex.runExclusive(async () => {
@@ -171,65 +163,63 @@ function createFileReloader(options: {
        .map(([_, file]) => file);
      if (fileChanges.length === 0) return;

-      const changes = detectDevChanges(
-        config,
-        fileChanges,
-        server.currentOutput,
-      );
+      const changes = detectDevChanges(fileChanges, server.currentOutput);
      if (changes.type === 'no-change') return;

      if (changes.type === 'full-restart') {
-        config.logger.info('Config changed, restarting server...');
+        wxt.logger.info('Config changed, restarting server...');
        server.restart();
        return;
      }

      if (changes.type === 'browser-restart') {
-        config.logger.info('Runner config changed, restarting browser...');
+        wxt.logger.info('Runner config changed, restarting browser...');
        server.restartBrowser();
        return;
      }

      // Log the entrypoints that were effected
-      config.logger.info(
+      wxt.logger.info(
        `Changed: ${Array.from(new Set(fileChanges))
-          .map((file) => pc.dim(relative(config.root, file)))
+          .map((file) => pc.dim(relative(wxt.config.root, file)))
          .join(', ')}`,
      );

-      const rebuiltNames = changes.rebuildGroups
-        .flat()
-        .map((entry) => {
-          return pc.cyan(
-            relative(config.outDir, getEntrypointOutputFile(entry, '')),
-          );
-        })
-        .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,
-      );
-      server.currentOutput = newOutput;
+      const allEntrypoints = await findEntrypoints();
+      try {
+        const { output: newOutput } = await rebuild(
+          allEntrypoints,
+          // TODO: this excludes new entrypoints, so they're not built until the dev command is restarted
+          changes.rebuildGroups,
+          changes.cachedOutput,
+        );
+        server.currentOutput = newOutput;

-      // Perform reloads
-      switch (changes.type) {
-        case 'extension-reload':
-          server.reloadExtension();
-          break;
-        case 'html-reload':
-          reloadHtmlPages(changes.rebuildGroups, server, config);
-          break;
-        case 'content-script-reload':
-          reloadContentScripts(changes.changedSteps, config, server);
-          break;
+        // Perform reloads
+        switch (changes.type) {
+          case 'extension-reload':
+            server.reloadExtension();
+            consola.success(`Reloaded extension`);
+            break;
+          case 'html-reload':
+            const { reloadedNames } = reloadHtmlPages(
+              changes.rebuildGroups,
+              server,
+            );
+            consola.success(`Reloaded: ${getFilenameList(reloadedNames)}`);
+            break;
+          case 'content-script-reload':
+            reloadContentScripts(changes.changedSteps, server);
+            const rebuiltNames = changes.rebuildGroups
+              .flat()
+              .map((entry) => entry.name);
+            consola.success(`Reloaded: ${getFilenameList(rebuiltNames)}`);
+            break;
+        }
+      } catch (err) {
+        // Catch build errors instead of crashing. Don't log error either, builder should have already logged it
      }
-      consola.success(`Reloaded: ${rebuiltNames}`);
    });
  };
 }
@@ -237,37 +227,25 @@ function createFileReloader(options: {
 /**
 * From the server, tell the client to reload content scripts from the provided build step outputs.
 */
-function reloadContentScripts(
-  steps: BuildStepOutput[],
-  config: InternalConfig,
-  server: WxtDevServer,
-) {
-  if (config.manifestVersion === 3) {
+function reloadContentScripts(steps: BuildStepOutput[], server: WxtDevServer) {
+  if (wxt.config.manifestVersion === 3) {
    steps.forEach((step) => {
      if (server.currentOutput == null) return;

      const entry = step.entrypoints;
      if (Array.isArray(entry) || entry.type !== 'content-script') return;

-      const js = [getEntrypointBundlePath(entry, config.outDir, '.js')];
+      const js = getContentScriptJs(wxt.config, entry);
      const cssMap = getContentScriptsCssMap(server.currentOutput, [entry]);
      const css = getContentScriptCssFiles([entry], cssMap);

      server.reloadContentScript({
-        allFrames: resolvePerBrowserOption(
-          entry.options.allFrames,
-          config.browser,
+        registration: entry.options.registration,
+        contentScript: mapWxtOptionsToRegisteredContentScript(
+          entry.options,
+          js,
+          css,
        ),
-        excludeMatches: resolvePerBrowserOption(
-          entry.options.excludeMatches,
-          config.browser,
-        ),
-        matches: resolvePerBrowserOption(entry.options.matches, config.browser),
-        runAt: resolvePerBrowserOption(entry.options.runAt, config.browser),
-        // @ts-expect-error: Chrome accepts this, not typed in webextension-polyfill (https://developer.chrome.com/docs/extensions/reference/scripting/#type-RegisteredContentScript)
-        world: resolvePerBrowserOption(entry.options.world, config.browser),
-        js,
-        css,
      });
    });
  } else {
@@ -278,10 +256,51 @@ function reloadContentScripts(
 function reloadHtmlPages(
  groups: EntrypointGroup[],
  server: WxtDevServer,
-  config: InternalConfig,
-) {
-  groups.flat().forEach((entry) => {
-    const path = getEntrypointBundlePath(entry, config.outDir, '.html');
+): { reloadedNames: string[] } {
+  // groups might contain other files like background/content scripts, and we only care about the HTMl pages
+  const htmlEntries = groups.flat().filter(isHtmlEntrypoint);
+
+  htmlEntries.forEach((entry) => {
+    const path = getEntrypointBundlePath(entry, wxt.config.outDir, '.html');
    server.reloadPage(path);
  });
+
+  return {
+    reloadedNames: htmlEntries.map((entry) => entry.name),
+  };
+}
+
+function getFilenameList(names: string[]): string {
+  return names
+    .map((name) => {
+      return pc.cyan(name);
+    })
+    .join(pc.dim(', '));
+}
+
+/**
+ * Based on the current build output, return a list of files that are:
+ * 1. Not in node_modules
+ * 2. Not inside project root
+ */
+function getExternalOutputDependencies(server: WxtDevServer) {
+  return (
+    server.currentOutput?.steps
+      .flatMap((step, i) => {
+        if (Array.isArray(step.entrypoints) && i === 0) {
+          // Dev server is already watching all HTML/esm files
+          return [];
+        }
+
+        return step.chunks.flatMap((chunk) => {
+          if (chunk.type === 'asset') return [];
+          return chunk.moduleIds;
+        });
+      })
+      .filter(
+        (file) => !file.includes('node_modules') && !file.startsWith('\x00'),
+      )
+      .map(unnormalizePath)
+      .filter((file) => !file.startsWith(wxt.config.root)) ?? []
+  );
 }
@@ -59,6 +59,16 @@ export async function initialize(options: {
  input.template ??= defaultTemplate;
  input.packageManager ??= options.packageManager;

+  const isExists = await fs.pathExists(input.directory);
+  if (isExists) {
+    const isEmpty = (await fs.readdir(input.directory)).length === 0;
+    if (!isEmpty) {
+      consola.error(
+        `The directory ${path.resolve(input.directory)} is not empty. Aborted.`,
+      );
+      process.exit(1);
+    }
+  }
  await cloneProject(input);

  const cdPath = path.relative(process.cwd(), path.resolve(input.directory));
@@ -90,26 +100,25 @@ interface Template {

 async function listTemplates(): Promise<Template[]> {
  try {
-    const res = await fetch(
-      'https://api.github.com/repos/wxt-dev/wxt/contents/templates',
-      {
-        headers: {
-          Accept: 'application/vnd.github+json',
-          'X-GitHub-Api-Version': '2022-11-28',
-        },
-      },
-    );
+    const res = await fetch('https://ungh.cc/repos/wxt-dev/wxt/files/main');
    if (res.status >= 300)
      throw Error(`Request failed with status ${res.status} ${res.statusText}`);

-    const data = (await res.json()) as Array<{
-      type: 'file' | 'dir';
-      name: string;
-      path: string;
-    }>;
-    return data
-      .filter((item: any) => item.type === 'dir')
-      .map((item) => ({ name: item.name, path: item.path }))
+    const data = (await res.json()) as {
+      meta: {
+        sha: string;
+      };
+      files: Array<{
+        path: string;
+        mode: string;
+        sha: string;
+        size: number;
+      }>;
+    };
+    return data.files
+      .map((item) => item.path.match(/templates\/(.+)\/package\.json/)?.[1])
+      .filter((name) => name != null)
+      .map((name) => ({ name: name!, path: `templates/${name}` }))
      .sort((l, r) => {
        const lWeight = TEMPLATE_SORT_WEIGHT[l.name] ?? Number.MAX_SAFE_INTEGER;
        const rWeight = TEMPLATE_SORT_WEIGHT[r.name] ?? Number.MAX_SAFE_INTEGER;
@@ -118,7 +127,8 @@ async function listTemplates(): Promise<Template[]> {
        return l.name.localeCompare(r.name);
      });
  } catch (err) {
-    throw Error(`Cannot load templates: ${JSON.stringify(err, null, 2)}`);
+    consola.error(err);
+    throw Error(`Failed to load templates`);
  }
 }

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+import path from 'node:path';
+import { bun } from '../bun';
+
+const cwd = path.resolve(__dirname, 'fixtures/bun-project');
+
+describe.skipIf(() => process.platform === 'win32')(
+  'Bun Package Management Utils',
+  () => {
+    describe('listDependencies', () => {
+      it('should list direct dependencies', async () => {
+        const actual = await bun.listDependencies({ cwd });
+        expect(actual).toEqual([
+          { name: 'flatten', version: '1.0.3' },
+          { name: 'mime-types', version: '2.1.35' },
+        ]);
+      });
+
+      it('should list all dependencies', async () => {
+        const actual = await bun.listDependencies({ cwd, all: true });
+        expect(actual).toEqual([
+          { name: 'flatten', version: '1.0.3' },
+          { name: 'mime-db', version: '1.52.0' },
+          { name: 'mime-types', version: '2.1.35' },
+        ]);
+      });
+    });
+  },
+);
@@ -0,0 +1,9 @@
+{
+  "name": "bun-ls",
+  "dependencies": {
+    "mime-types": "2.1.35"
+  },
+  "devDependencies": {
+    "flatten": "1.0.3"
+  }
+}
@@ -0,0 +1,42 @@
+{
+  "name": "npm-ls",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "npm-ls",
+      "dependencies": {
+        "mime-types": "2.1.35"
+      },
+      "devDependencies": {
+        "flatten": "1.0.3"
+      }
+    },
+    "node_modules/flatten": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/flatten/-/flatten-1.0.3.tgz",
+      "integrity": "sha512-dVsPA/UwQ8+2uoFe5GHtiBMu48dWLTdsuEd7CKGlZlD78r1TTWBvDuFaFGKCo/ZfEr95Uk56vZoX86OsHkUeIg==",
+      "deprecated": "flatten is deprecated in favor of utility frameworks such as lodash.",
+      "dev": true
+    },
+    "node_modules/mime-db": {
+      "version": "1.52.0",
+      "resolved": "https://registry.npmjs.org/mime-db/-/mime-db-1.52.0.tgz",
+      "integrity": "sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg==",
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
+    "node_modules/mime-types": {
+      "version": "2.1.35",
+      "resolved": "https://registry.npmjs.org/mime-types/-/mime-types-2.1.35.tgz",
+      "integrity": "sha512-ZDY+bPm5zTTF+YpCrAU9nK0UgICYPT0QtT1NZWFv4s++TNkcgVaT0g6+4R2uI4MjQjzysHB1zxuWL50hzaeXiw==",
+      "dependencies": {
+        "mime-db": "1.52.0"
+      },
+      "engines": {
+        "node": ">= 0.6"
+      }
+    }
+  }
+}
@@ -0,0 +1,9 @@
+{
+  "name": "npm-ls",
+  "dependencies": {
+    "mime-types": "2.1.35"
+  },
+  "devDependencies": {
+    "flatten": "1.0.3"
+  }
+}
@@ -0,0 +1,9 @@
+{
+  "name": "pnpm-ls",
+  "dependencies": {
+    "mime-types": "2.1.35"
+  },
+  "devDependencies": {
+    "flatten": "1.0.3"
+  }
+}
@@ -0,0 +1,34 @@
+lockfileVersion: '6.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+dependencies:
+  mime-types:
+    specifier: 2.1.35
+    version: 2.1.35
+
+devDependencies:
+  flatten:
+    specifier: 1.0.3
+    version: 1.0.3
+
+packages:
+
+  /flatten@1.0.3:
+    resolution: {integrity: sha512-dVsPA/UwQ8+2uoFe5GHtiBMu48dWLTdsuEd7CKGlZlD78r1TTWBvDuFaFGKCo/ZfEr95Uk56vZoX86OsHkUeIg==}
+    deprecated: flatten is deprecated in favor of utility frameworks such as lodash.
+    dev: true
+
+  /mime-db@1.52.0:
+    resolution: {integrity: sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg==}
+    engines: {node: '>= 0.6'}
+    dev: false
+
+  /mime-types@2.1.35:
+    resolution: {integrity: sha512-ZDY+bPm5zTTF+YpCrAU9nK0UgICYPT0QtT1NZWFv4s++TNkcgVaT0g6+4R2uI4MjQjzysHB1zxuWL50hzaeXiw==}
+    engines: {node: '>= 0.6'}
+    dependencies:
+      mime-db: 1.52.0
+    dev: false
@@ -0,0 +1,10 @@
+{
+  "name": "yarn-ls",
+  "packageManager": "yarn@1.22.19",
+  "dependencies": {
+    "mime-types": "2.1.35"
+  },
+  "devDependencies": {
+    "flatten": "1.0.3"
+  }
+}
@@ -0,0 +1,20 @@
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
+# yarn lockfile v1
+
+
+flatten@1.0.3:
+  version "1.0.3"
+  resolved "https://registry.yarnpkg.com/flatten/-/flatten-1.0.3.tgz#c1283ac9f27b368abc1e36d1ff7b04501a30356b"
+  integrity sha512-dVsPA/UwQ8+2uoFe5GHtiBMu48dWLTdsuEd7CKGlZlD78r1TTWBvDuFaFGKCo/ZfEr95Uk56vZoX86OsHkUeIg==
+
+mime-db@1.52.0:
+  version "1.52.0"
+  resolved "https://registry.yarnpkg.com/mime-db/-/mime-db-1.52.0.tgz#bbabcdc02859f4987301c856e3387ce5ec43bf70"
+  integrity sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg==
+
+mime-types@2.1.35:
+  version "2.1.35"
+  resolved "https://registry.yarnpkg.com/mime-types/-/mime-types-2.1.35.tgz#381a871b62a734450660ae3deee44813f70d959a"
+  integrity sha512-ZDY+bPm5zTTF+YpCrAU9nK0UgICYPT0QtT1NZWFv4s++TNkcgVaT0g6+4R2uI4MjQjzysHB1zxuWL50hzaeXiw==
+  dependencies:
+    mime-db "1.52.0"
@@ -0,0 +1,46 @@
+import { beforeAll, describe, expect, it } from 'vitest';
+import path from 'node:path';
+import { npm } from '../npm';
+import { execaCommand } from 'execa';
+import { exists } from 'fs-extra';
+
+const cwd = path.resolve(__dirname, 'fixtures/npm-project');
+
+describe('NPM Package Management Utils', () => {
+  beforeAll(async () => {
+    // NPM needs the modules installed for 'npm ls' to work
+    await execaCommand('npm i', { cwd });
+  }, 60e3);
+
+  describe('listDependencies', () => {
+    it('should list direct dependencies', async () => {
+      const actual = await npm.listDependencies({ cwd });
+      expect(actual).toEqual([
+        { name: 'flatten', version: '1.0.3' },
+        { name: 'mime-types', version: '2.1.35' },
+      ]);
+    });
+
+    it('should list all dependencies', async () => {
+      const actual = await npm.listDependencies({ cwd, all: true });
+      expect(actual).toEqual([
+        { name: 'flatten', version: '1.0.3' },
+        { name: 'mime-types', version: '2.1.35' },
+        { name: 'mime-db', version: '1.52.0' },
+      ]);
+    });
+  });
+
+  describe('downloadDependency', () => {
+    it('should download the dependency as a tarball', async () => {
+      const downloadDir = path.resolve(cwd, 'dist');
+      const id = 'mime-db@1.52.0';
+      const expected = path.resolve(downloadDir, 'mime-db-1.52.0.tgz');
+
+      const actual = await npm.downloadDependency(id, downloadDir);
+
+      expect(actual).toEqual(expected);
+      expect(await exists(actual)).toBe(true);
+    });
+  });
+});
@@ -0,0 +1,34 @@
+import { beforeAll, describe, expect, it } from 'vitest';
+import path from 'node:path';
+import { pnpm } from '../pnpm';
+import { execaCommand } from 'execa';
+
+const cwd = path.resolve(__dirname, 'fixtures/pnpm-project');
+
+process.env.WXT_PNPM_IGNORE_WORKSPACE = 'true';
+
+describe('PNPM Package Management Utils', () => {
+  beforeAll(async () => {
+    // PNPM needs the modules installed, or 'pnpm ls' will return a blank list.
+    await execaCommand('pnpm i --ignore-workspace', { cwd });
+  });
+
+  describe('listDependencies', () => {
+    it('should list direct dependencies', async () => {
+      const actual = await pnpm.listDependencies({ cwd });
+      expect(actual).toEqual([
+        { name: 'flatten', version: '1.0.3' },
+        { name: 'mime-types', version: '2.1.35' },
+      ]);
+    });
+
+    it('should list all dependencies', async () => {
+      const actual = await pnpm.listDependencies({ cwd, all: true });
+      expect(actual).toEqual([
+        { name: 'flatten', version: '1.0.3' },
+        { name: 'mime-types', version: '2.1.35' },
+        { name: 'mime-db', version: '1.52.0' },
+      ]);
+    });
+  });
+});
@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest';
+import path from 'node:path';
+import { yarn } from '../yarn';
+
+const cwd = path.resolve(__dirname, 'fixtures/yarn-project');
+
+describe('Yarn Package Management Utils', () => {
+  describe('listDependencies', () => {
+    it('should list direct dependencies', async () => {
+      const actual = await yarn.listDependencies({ cwd });
+      expect(actual).toEqual([
+        { name: 'mime-db', version: '1.52.0' },
+        { name: 'flatten', version: '1.0.3' },
+        { name: 'mime-types', version: '2.1.35' },
+      ]);
+    });
+
+    it('should list all dependencies', async () => {
+      const actual = await yarn.listDependencies({ cwd, all: true });
+      expect(actual).toEqual([
+        { name: 'mime-db', version: '1.52.0' },
+        { name: 'flatten', version: '1.0.3' },
+        { name: 'mime-types', version: '2.1.35' },
+      ]);
+    });
+  });
+});
@@ -0,0 +1,27 @@
+import { dedupeDependencies, npm } from './npm';
+import { WxtPackageManagerImpl } from './types';
+
+export const bun: WxtPackageManagerImpl = {
+  overridesKey: 'overrides', // But also supports "resolutions"
+  downloadDependency(...args) {
+    return npm.downloadDependency(...args);
+  },
+  async listDependencies(options) {
+    const args = ['pm', 'ls'];
+    if (options?.all) {
+      args.push('--all');
+    }
+    const { execa } = await import('execa');
+    const res = await execa('bun', args, { cwd: options?.cwd });
+    return dedupeDependencies(
+      res.stdout
+        .split('\n')
+        .slice(1) // Skip the first line, is not a dependency
+        .map((line) => line.trim())
+        .map((line) => /.* (@?\S+)@(\S+)$/.exec(line))
+        // @ts-expect-error: Filtering to known non-null matches
+        .filter<RegExpExecArray>((match) => !!match)
+        .map(([_, name, version]) => ({ name, version })),
+    );
+  },
+};
@@ -0,0 +1,76 @@
+import {
+  detectPackageManager,
+  addDependency,
+  addDevDependency,
+  ensureDependencyInstalled,
+  installDependencies,
+  removeDependency,
+  PackageManager,
+  PackageManagerName,
+} from 'nypm';
+import { WxtPackageManager } from '~/types';
+import { bun } from './bun';
+import { WxtPackageManagerImpl } from './types';
+import { yarn } from './yarn';
+import { pnpm } from './pnpm';
+import { npm } from './npm';
+
+export async function createWxtPackageManager(
+  root: string,
+): Promise<WxtPackageManager> {
+  const pm = await detectPackageManager(root, {
+    includeParentDirs: true,
+  });
+
+  // Use requirePm to prevent throwing errors before the package manager utils are used.
+  const requirePm = <T>(cb: (pm: PackageManager) => T) => {
+    if (pm == null) throw Error('Could not detect package manager');
+    return cb(pm);
+  };
+
+  return {
+    get name() {
+      return requirePm((pm) => pm.name);
+    },
+    get command() {
+      return requirePm((pm) => pm.command);
+    },
+    get version() {
+      return requirePm((pm) => pm.version);
+    },
+    get majorVersion() {
+      return requirePm((pm) => pm.majorVersion);
+    },
+    get lockFile() {
+      return requirePm((pm) => pm.lockFile);
+    },
+    get files() {
+      return requirePm((pm) => pm.files);
+    },
+    addDependency,
+    addDevDependency,
+    ensureDependencyInstalled,
+    installDependencies,
+    removeDependency,
+    get overridesKey() {
+      return requirePm((pm) => packageManagers[pm.name].overridesKey);
+    },
+    downloadDependency(...args) {
+      return requirePm((pm) =>
+        packageManagers[pm.name].downloadDependency(...args),
+      );
+    },
+    listDependencies(...args) {
+      return requirePm((pm) =>
+        packageManagers[pm.name].listDependencies(...args),
+      );
+    },
+  };
+}
+
+const packageManagers: Record<PackageManagerName, WxtPackageManagerImpl> = {
+  npm,
+  pnpm,
+  bun,
+  yarn,
+};
@@ -0,0 +1,85 @@
+import { Dependency } from '~/types';
+import { WxtPackageManagerImpl } from './types';
+import path from 'node:path';
+import { ensureDir } from 'fs-extra';
+
+export const npm: WxtPackageManagerImpl = {
+  overridesKey: 'overrides',
+  async downloadDependency(id, downloadDir) {
+    await ensureDir(downloadDir);
+    const { execa } = await import('execa');
+    const res = await execa('npm', ['pack', id, '--json'], {
+      cwd: downloadDir,
+    });
+    const packed: PackedDependency[] = JSON.parse(res.stdout);
+    return path.resolve(downloadDir, packed[0].filename);
+  },
+  async listDependencies(options) {
+    const args = ['ls', '--json'];
+    if (options?.all) {
+      args.push('--depth', 'Infinity');
+    }
+    const { execa } = await import('execa');
+    const res = await execa('npm', args, { cwd: options?.cwd });
+    const project: NpmListProject = JSON.parse(res.stdout);
+
+    return flattenNpmListOutput([project]);
+  },
+};
+
+export function flattenNpmListOutput(projects: NpmListProject[]): Dependency[] {
+  const queue: Record<string, NpmListDependency>[] = projects.flatMap(
+    (project) => {
+      const acc: Record<string, NpmListDependency>[] = [];
+      if (project.dependencies) acc.push(project.dependencies);
+      if (project.devDependencies) acc.push(project.devDependencies);
+      return acc;
+    },
+  );
+  const dependencies: Dependency[] = [];
+  while (queue.length > 0) {
+    Object.entries(queue.pop()!).forEach(([name, meta]) => {
+      dependencies.push({
+        name,
+        version: meta.version,
+      });
+      if (meta.dependencies) queue.push(meta.dependencies);
+      if (meta.devDependencies) queue.push(meta.devDependencies);
+    });
+  }
+  return dedupeDependencies(dependencies);
+}
+
+export function dedupeDependencies(dependencies: Dependency[]): Dependency[] {
+  const hashes = new Set<string>();
+  return dependencies.filter((dep) => {
+    const hash = `${dep.name}@${dep.version}`;
+    if (hashes.has(hash)) {
+      return false;
+    } else {
+      hashes.add(hash);
+      return true;
+    }
+  });
+}
+
+export interface NpmListProject {
+  name: string;
+  dependencies?: Record<string, NpmListDependency>;
+  devDependencies?: Record<string, NpmListDependency>;
+}
+
+export interface NpmListDependency {
+  version: string;
+  resolved?: string;
+  overridden?: boolean;
+  dependencies?: Record<string, NpmListDependency>;
+  devDependencies?: Record<string, NpmListDependency>;
+}
+
+interface PackedDependency {
+  id: string;
+  name: string;
+  version: string;
+  filename: string;
+}
@@ -0,0 +1,28 @@
+import { NpmListProject, flattenNpmListOutput, npm } from './npm';
+import { WxtPackageManagerImpl } from './types';
+
+export const pnpm: WxtPackageManagerImpl = {
+  overridesKey: 'resolutions', // "pnpm.overrides" has a higher priority, but I don't want to deal with nesting
+  downloadDependency(...args) {
+    return npm.downloadDependency(...args);
+  },
+  async listDependencies(options) {
+    const args = ['ls', '-r', '--json'];
+    if (options?.all) {
+      args.push('--depth', 'Infinity');
+    }
+    // Helper for testing - since WXT uses pnpm workspaces, folders inside it don't behave like
+    // standalone projects unless you pass the --ignore-workspace flag.
+    if (
+      typeof process !== 'undefined' &&
+      process.env.WXT_PNPM_IGNORE_WORKSPACE === 'true'
+    ) {
+      args.push('--ignore-workspace');
+    }
+    const { execa } = await import('execa');
+    const res = await execa('pnpm', args, { cwd: options?.cwd });
+    const projects: NpmListProject[] = JSON.parse(res.stdout);
+
+    return flattenNpmListOutput(projects);
+  },
+};
@@ -0,0 +1,6 @@
+import { WxtPackageManager } from '~/types';
+
+export type WxtPackageManagerImpl = Pick<
+  WxtPackageManager,
+  'downloadDependency' | 'listDependencies' | 'overridesKey'
+>;
@@ -0,0 +1,54 @@
+import { Dependency } from '~/types';
+import { WxtPackageManagerImpl } from './types';
+import { dedupeDependencies, npm } from './npm';
+
+export const yarn: WxtPackageManagerImpl = {
+  overridesKey: 'resolutions',
+  downloadDependency(...args) {
+    return npm.downloadDependency(...args);
+  },
+  async listDependencies(options) {
+    const args = ['list', '--json'];
+    if (options?.all) {
+      args.push('--depth', 'Infinity');
+    }
+    const { execa } = await import('execa');
+    const res = await execa('yarn', args, { cwd: options?.cwd });
+    const tree = res.stdout
+      .split('\n')
+      .map<JsonLine>((line) => JSON.parse(line))
+      .find((line) => line.type === 'tree')?.data as JsonLineTree | undefined;
+    if (tree == null) throw Error("'yarn list --json' did not output a tree");
+
+    const queue = [...tree.trees];
+    const dependencies: Dependency[] = [];
+
+    while (queue.length > 0) {
+      const { name: treeName, children } = queue.pop()!;
+      const match = /(@?\S+)@(\S+)$/.exec(treeName);
+      if (match) {
+        const [_, name, version] = match;
+        dependencies.push({ name, version });
+      }
+      if (children != null) {
+        queue.push(...children);
+      }
+    }
+
+    return dedupeDependencies(dependencies);
+  },
+};
+
+type JsonLine =
+  | { type: unknown; data: unknown }
+  | { type: 'tree'; data: JsonLineTree };
+
+interface JsonLineTree {
+  type: 'list';
+  trees: Tree[];
+}
+
+interface Tree {
+  name: string;
+  children?: Tree[];
+}
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
GitHub Actions	7e37e11caf	chore(release): v0.17.11	2024-03-31 13:22:25 +00:00
Aaron	bb90029c54	fix: Resolve absolute paths from the public directory properly (#583 )	2024-03-31 08:19:06 -05:00
Aaron	d3b14afbce	chore: Extract helper function	2024-03-30 14:49:10 -05:00
Aaron	ba2197a609	chore: Add some array utils (#582 )	2024-03-30 13:30:45 -05:00
Aaron	4c558d3eb6	chore: Simplify virtual module setup (#581 )	2024-03-30 12:44:27 -05:00
Qiwei Yang	dcd175444a	docs: Add "GitHub Custom Notifier" to homepage (#580 )	2024-03-30 08:37:26 -05:00
Aaron	16fc58404a	docs: Fix `zip.includeSources` example	2024-03-30 08:37:00 -05:00
GitHub Actions	28c7e7d9ed	chore(release): v0.17.10	2024-03-29 05:52:30 +00:00
Zizheng Tai	5a3b42a4b0	feat: Add `dev.server.port` config (#577 ) Co-authored-by: Aaron <aaronklinker1@gmail.com>	2024-03-29 00:49:36 -05:00
Aaron	c9c5d721ec	chore: Refactor order of config resolution (#578 )	2024-03-29 00:21:09 -05:00
Aaron	1556b9ad73	chore: Use `@aklinker1/check` to simplify checks setup (#550 )	2024-03-25 15:15:40 -05:00
GitHub Actions	ca15b1f321	chore(release): v0.17.9	2024-03-25 06:13:23 +00:00
Aaron	448436cb08	chore: Merge user config using `defu` (#568 )	2024-03-25 01:09:52 -05:00
Aaron	c9ddc3d0f2	fix: Don't override `wxt.config.ts` options when CLI flags are not passed (#567 )	2024-03-25 00:24:56 -05:00
Guillaume	6b72f883b6	feat: Add `{{mode}}` Template Variable (#566 ) Co-authored-by: Aaron <aaronklinker1@gmail.com>	2024-03-25 00:01:59 -05:00
GitHub Actions	cd3446bd7f	chore(release): v0.17.8	2024-03-24 16:26:00 +00:00
Aaron	829b371bba	fix(dev): Don't crash dev mode when rebuild fails (#565 )	2024-03-24 11:23:16 -05:00
Aaron	36b399dd49	feat(analysis): Open `stats.html` file automatically (#564 )	2024-03-24 11:05:34 -05:00
btea	08f32aa685	chore: Add a test covering `wxt init` in a non-empty directory (#563 ) Co-authored-by: Aaron <aaronklinker1@gmail.com>	2024-03-24 10:15:59 -05:00
Vlad Fedosov	05db264e02	docs: Fixed "Reload the Extension" section (#559 ) Co-authored-by: Aaron <aaronklinker1@gmail.com>	2024-03-20 16:52:52 -05:00
btea	de5a01834c	fix(init): Don't overwrite existing files when initializing a new project (#556 ) Co-authored-by: Aaron <aaronklinker1@gmail.com>	2024-03-20 09:22:53 -05:00
Lpmvb	1d260dbacb	chore(vue-template): Upgrade to `vue-tsc` v2 (#549 )	2024-03-15 08:08:40 -05:00
Aaron	53c63b4556	chore: Switch to seed plugin for testing (#547 )	2024-03-15 00:43:20 -05:00
btea	816878bc15	fix: Append option description error (#546 )	2024-03-13 23:07:32 -05:00
Guillaume	e087a0d6ef	docs: Add examples for GitHub Actions (#540 ) Co-authored-by: Aaron <aaronklinker1@gmail.com>	2024-03-13 23:07:17 -05:00
Aaron	56b71491a6	chore: Increase hook timeout for Windows/NPM tests	2024-03-13 12:34:59 -05:00
Aaron	121b521157	docs: Mention adding unlisted scripts and pages to `web_accessible_resources` This closes #536	2024-03-12 07:57:38 -05:00
Sunshio	16c2e3218b	docs: Add documentation for Bun.sh (#543 ) Co-authored-by: Aaron <aaronklinker1@gmail.com>	2024-03-12 07:46:46 -05:00
Aaron	d9cba55d34	chore: Increase unit test timeout	2024-03-12 07:45:42 -05:00
Guillaume	832cd5d640	docs: Add Plex skipper to "Using WXT" section (#541 )	2024-03-10 09:03:18 -05:00
btea	bb95e08d71	docs: Update README demo video (#539 )	2024-03-10 09:03:03 -05:00
Aaron	35269dad9e	docs: Update homepage demo video This closes #535	2024-03-09 10:04:23 -06:00
btea	64d1498460	fix: Remove deprecated extension from Vue template (#534 )	2024-03-08 21:03:56 -06:00
Luca Dalli	0d540a6df9	docs: Replace `pnpx` with `pnpm dlx` (#527 )	2024-03-06 16:04:52 -06:00
Aaron	b47c150daa	fix(init): Better error logging when templates fail to load This fixes #528	2024-03-06 07:46:26 -06:00
GitHub Actions	38345481df	chore(release): v0.17.7	2024-03-04 16:29:56 +00:00
Aaron	da92449e0f	Undo change to log	2024-03-04 10:26:30 -06:00
Aaron	23b3980645	fix(zip): List `.wxt/local_modules` overrides relative to the `package.json` they're added to (#526 )	2024-03-04 10:23:18 -06:00
Aaron	81b4b629c9	chore: Increase test timeout for windows NPM tests (#525 )	2024-03-04 07:48:39 -06:00
Aaron	4f7e9cb050	chore: Bump templates to v0.17 (#524 )	2024-03-04 07:32:18 -06:00
GitHub Actions	b226d9b947	chore(release): v0.17.6	2024-03-03 16:05:15 +00:00
Aaron	aabba41e86	fix(zip): List all private packages correctly in a PNPM workspace (#520 )	2024-03-03 09:56:42 -06:00
Aaron	f19e6908b0	feat: Automatically generate `browser_action` based on `action` for MV2 (#519 )	2024-03-03 09:52:43 -06:00
Aaron	5f651cc3fe	feat: Automatically remove top-level MV2-only or MV3-only keys (#518 ) When targeting MV2, all MV3 keys will be removed. When targeting MV3, all MV2 keys will be removed.	2024-03-03 09:22:24 -06:00
Aaron	8a6acbaaf2	feat: Add warnings when important directories are missing (#516 )	2024-03-02 08:56:20 -06:00
dependabot[bot]	13ab8e4d01	chore(deps-dev): bump @types/react from 18.2.34 to 18.2.61 (#510 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-03-02 08:55:51 -06:00
dependabot[bot]	bd039dcbab	chore(deps): bump chokidar from 3.5.3 to 3.6.0 (#511 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-03-02 08:55:00 -06:00
Aaron Klinker	9cd4e8342b	docs: Mentions moving folders into `srcDir` Apart of #515	2024-03-02 08:42:31 -06:00
dependabot[bot]	c9633cefec	chore(deps): bump linkedom from 0.16.1 to 0.16.8 (#513 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-03-01 17:04:05 -06:00
GitHub Actions	1dd1370ed7	chore(release): v0.17.5	2024-03-01 18:01:15 +00:00
Aaron	9ff90d0acf	feat: Download and override private packages for Firefox code review (#507 )	2024-03-01 10:17:45 -06:00
Aaron Klinker	b754435589	docs: Fix CLI generation	2024-02-29 12:13:28 -06:00
Aaron Klinker	195d2cceaf	docs: Add docs about configuring the manifest as a function	2024-02-29 11:39:06 -06:00
Aaron	420d78b638	feat: Expose package management utils under `wxt.pm` (#502 )	2024-02-28 21:38:35 -06:00
btea	b35e499355	docs: Fix typos (#503 )	2024-02-28 21:36:43 -06:00
Aaron	41c3d6d015	chore: Use JSZip for `wxt zip`, enabling future features (#501 )	2024-02-28 14:57:29 -06:00
GitHub Actions	64610bad41	chore(release): v0.17.4	2024-02-28 18:28:34 +00:00
Aaron	45b7d7c67f	fix: Resolve the path to `node_modules/wxt` correctly (#498 )	2024-02-28 12:25:04 -06:00
Aaron	0bb2746869	feat: Add `ResolvedConfig.wxtModuleDir`, resolving the directory once (#497 )	2024-02-28 11:52:46 -06:00
Aaron Klinker	f9b0aa45f8	chore: Fix tests after template change	2024-02-28 11:34:15 -06:00
btea	6f6ce33bbd	feat: Add basic content script to templates (#495 ) Co-authored-by: Aaron Klinker <aaronklinker1@gmail.com>	2024-02-28 11:30:53 -06:00
Aaron Klinker	e1c6020997	docs: Add testing example for `ContentScriptContext` Apart of #491	2024-02-28 11:17:20 -06:00
Aaron Klinker	012bd7e67f	docs: Update context usage	2024-02-28 11:16:56 -06:00
Aaron Klinker	35778f70cb	docs: Update comparison page	2024-02-28 10:39:47 -06:00
Aaron Klinker	cb4f9aa752	docs: Add CRXJS to comparison page	2024-02-28 08:05:39 -06:00
Aaron Klinker	f80fb42483	docs: Fix typos	2024-02-28 07:42:22 -06:00
Leo Shklovskii	02c79ca244	docs: Added DocVersionRedirector to "Using WXT" section (#492 )	2024-02-27 23:47:10 -06:00
Qiwei Yang	50e8c86ce9	doc: Add markdown sticky ntoes (#488 )	2024-02-25 13:37:10 -06:00
GitHub Actions	6fbfc15be7	chore(release): v0.17.3	2024-02-24 16:43:31 +00:00
Aaron	c793d3cf6b	fix(storage): Revert #478 and run migrations when item is defined and properly wait for migrations before allowing read/writes (#487 )	2024-02-24 10:40:03 -06:00
Aaron Klinker	b5f4d8cc1b	feat(storage): Guarantee `storage.getItems` returns values in the same order as requested	2024-02-24 08:56:45 -06:00
Aaron Klinker	77e6d1f5a4	fix: Content scripts crash when using `storage.defineItem`	2024-02-24 08:23:12 -06:00
GitHub Actions	3f149ac4fa	chore(release): v0.17.2	2024-02-23 21:49:55 +00:00
Aaron	c0dbffaa82	fix: Don't use sub-dependency binaries directly (#482 )	2024-02-23 15:45:18 -06:00
Aaron Klinker	707f03a3eb	Update changelog	2024-02-23 12:55:55 -06:00
GitHub Actions	8372462041	chore(release): v0.17.1	2024-02-23 18:54:07 +00:00
Aaron Klinker	3fbbe2ccde	fix: Content scripts not loading in dev mode	2024-02-23 12:51:11 -06:00
Leo Shklovskii	e7880fcde0	docs: Lots of small typo fixes (#480 )	2024-02-23 11:45:58 -06:00
Aaron Klinker	ee5e76e4b1	Update changelog	2024-02-22 14:24:38 -06:00
GitHub Actions	1ae8d6bc46	chore(release): v0.17.0	2024-02-22 17:55:31 +00:00
Aaron	de7dd09f60	fix: Improve dev mode for content scripts registered at runtime (#474 )	2024-02-22 11:52:37 -06:00
Aaron	1649785826	fix(storage)!: Only run migrations when the extension is updated (#478 )	2024-02-22 11:46:59 -06:00
Aaron Klinker	91fc41cb15	docs(storage): Update docs	2024-02-22 11:46:59 -06:00
Aaron	9c80ad832b	feat(storage)!: Improved support for default values on storage items (#477 )	2024-02-22 11:46:48 -06:00
Aaron Klinker	86b7162d99	Update changelog	2024-02-21 08:24:26 -06:00
Aaron Klinker	b8f8acd33d	Fix typo	2024-02-21 08:24:09 -06:00
GitHub Actions	d8905d23a4	chore(release): v0.16.11	2024-02-21 14:17:40 +00:00
Aaron	5d2d124e5a	fix: Output main JS file for HTML entrypoints to chunks directory (#473 )	2024-02-21 08:13:43 -06:00
Aaron Klinker	4fda203def	chore(e2e): Remove log	2024-02-21 08:13:21 -06:00
Aaron Klinker	905bfc7a38	ci: Upgrade `pnpm/action-setup` to v2	2024-02-20 14:35:53 -06:00
Aaron Klinker	7c6973f0e6	ci: Fix codecov warning in release workflow	2024-02-20 14:35:08 -06:00
GitHub Actions	969e39c541	chore(release): v0.16.10	2024-02-20 20:33:12 +00:00
Aaron	b256939cc4	fix: Respect `configFile` option (#472 )	2024-02-20 14:30:21 -06:00
Aaron	c46137644b	feat: Customize when content scripts are registered, in the manifest or at runtime (#471 )	2024-02-20 14:18:53 -06:00
Aaron	1bd7ef56c4	fix: Don't assume react when importing JSX entrypoints during build (#470 )	2024-02-20 13:53:00 -06:00
Aaron Klinker	c258b99cec	Update changelog	2024-02-20 08:26:02 -06:00
GitHub Actions	d3abb32cb4	chore(release): v0.16.9	2024-02-20 14:17:52 +00:00
Aaron	223ede9ff9	feat: Support setting side panel options in HTML file (#468 )	2024-02-20 08:14:34 -06:00
Aaron	9d31a4eba1	chore: Simplify entrypoint types (#464 )	2024-02-19 16:17:54 -06:00
okou	ea0e40c269	fix: Fix order of ShadowRootUI hooks calling (#459 )	2024-02-19 07:45:57 -06:00
Aaron Klinker	bc24ea45a4	docs: Add wrapper div to react's `createShadowRootUi` example Related to #456.	2024-02-17 09:20:35 -06:00
GitHub Actions	86d0c9b397	chore(release): v0.16.8	2024-02-15 21:41:43 +00:00
Aaron	c275ccf0da	fix: Watch files outside project root during development (#454 )	2024-02-15 14:23:32 -06:00
Aaron Klinker	447a48f306	docs: Add loading and error states for "Who's using WXT" section	2024-02-15 10:37:58 -06:00
GitHub Actions	70b5cbc8db	chore(release): v0.16.7	2024-02-15 16:35:13 +00:00
Aaron	3459de0375	perf: Upgrade Vite to 5.1 (#452 )	2024-02-15 10:31:20 -06:00
Aaron	c6817479bd	feat: Generate ESLint globals file for auto-imports (#450 )	2024-02-15 10:14:57 -06:00
Aaron	f02aae21f6	chore(e2e): Use `wxt prepare` instead of `wxt build` when possible to speed up E2E tests (#451 )	2024-02-15 09:59:36 -06:00
Aaron Klinker	87a62a1791	docs: Remove anchor from content script ui examples	2024-02-14 14:43:34 -06:00
Aaron Klinker	a0d1643021	docs: Add section about dev mode differences	2024-02-14 14:41:40 -06:00
William Gérald Blondel	856a946fa7	Fix typo on homepage hero section (#438 )	2024-02-11 10:13:17 -06:00
GitHub Actions	9d97164c20	chore(release): v0.16.6	2024-02-10 10:29:52 +00:00
lionelhorn	6d526e7043	feat: Add option to customize the analysis artifacts output (#431 ) Co-authored-by: Aaron Klinker <aaronklinker1@gmail.com>	2024-02-10 04:26:33 -06:00
Aaron Klinker	946072fc5a	docs: Fix `createShadowRootUi` unmount calls	2024-02-10 04:04:16 -06:00
Aaron Klinker	6b8dfdf02d	chore: Enable skipped test since it works now	2024-02-10 03:01:38 -06:00
okou	ba85fdf470	fix: Use `insertBefore` on mounting content script UI	2024-02-10 03:01:38 -06:00
okou	295f8601e3	refactor: Use `Element.prepend` on mounting UI	2024-02-10 03:01:38 -06:00
Aaron	a38ccd8624	doc: Fix custom block	2024-02-09 05:20:51 -06:00
GitHub Actions	b2dcec2f8a	chore(release): v0.16.5	2024-02-09 06:01:00 +00:00
Aaron Klinker	e8355029d9	fix: Support node 20 when running `wxt submit`	2024-02-08 23:55:53 -06:00
Aaron Klinker	2b374b98d2	docs: Remove "coming soon" from automated publishing feature	2024-02-05 23:36:13 -06:00
GitHub Actions	d14d76a0c8	chore(release): v0.16.4	2024-02-06 05:21:00 +00:00
Aaron Klinker	d0f1c7065c	chore: Fix fake path in test data generator	2024-02-05 23:17:14 -06:00
Aaron	3edb66d76d	feat: Add option to customize the analysis output filename (#426 )	2024-02-05 23:15:15 -06:00
Aaron	bba8cdace1	fix: Exclude analysis files from the build summary (#425 )	2024-02-05 23:09:30 -06:00
Aaron	22f82a67ee	feat: Automatically convert MV3 `web_accessible_resources` to MV2 (#423 )	2024-02-05 22:49:18 -06:00
Aaron	b32c60ca73	fix: Don't use immer for `transformManifest` (#424 )	2024-02-05 22:37:26 -06:00
Aaron Klinker	c93620cba5	Update changelog	2024-02-04 17:48:26 -06:00
GitHub Actions	dd05ed4d4c	chore(release): v0.16.3	2024-02-04 23:41:38 +00:00
Aaron	21636defda	feat: Hooks (#419 ) Deprecated `transformManifest` since a hook now exists for it.	2024-02-04 17:37:31 -06:00
Aaron	bb022646e3	chore: Register global `wxt` instance (#418 )	2024-02-04 16:34:10 -06:00
Aaron Klinker	37ad2c7ceb	fix(init): Use `ungh` to prevent rate limits when loading templates	2024-02-04 14:11:41 -06:00
dependabot[bot]	b992631e00	chore(deps): bump rollup-plugin-visualizer from 5.9.3 to 5.12.0 (#412 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-02-04 03:14:47 -06:00
dependabot[bot]	35a5cc6717	chore(deps-dev): bump typescript from 5.3.2 to 5.3.3 (#409 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-02-04 03:14:15 -06:00
dependabot[bot]	310b56fe5d	chore(deps): bump defu from 6.1.3 to 6.1.4 (#413 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-02-04 03:13:28 -06:00
dependabot[bot]	148234382e	chore(deps): bump @types/webextension-polyfill from 0.10.5 to 0.10.7 (#410 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-02-04 03:13:03 -06:00
dependabot[bot]	c1a97b77b0	chore(deps): bump actions/checkout from 3 to 4 (#407 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-02-04 03:11:32 -06:00
Chen Hua	557ccb4854	docs: fix typo of opinionated (#416 )	2024-02-04 03:11:03 -06:00
Chen Hua	83e7e8aab9	docs: Fix typo of intuitive (#415 )	2024-02-04 03:10:20 -06:00
dependabot[bot]	7bf490c59d	chore(deps-dev): bump happy-dom from 12.10.3 to 13.3.8 (#411 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-02-04 03:08:24 -06:00
dependabot[bot]	9670babdbb	chore(deps): bump codecov/codecov-action from 3 to 4 (#408 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-02-04 03:06:11 -06:00
Florian Metz	42dfc2d5cf	chore: Add dependabot for github actions (#404 )	2024-02-03 16:32:46 -06:00
GitHub Actions	1527f0e275	chore(release): v0.16.2	2024-02-03 21:02:28 +00:00
Aaron	66bd957ee0	fix: Don't crash background service worker when using `import.meta.url` (#402 )	2024-02-03 14:57:34 -06:00
GitHub Actions	72e3c5baa2	chore(release): v0.16.1	2024-02-03 19:57:51 +00:00
Aaron Klinker	9318346ab3	fix: Don't require config to run `wxt submit init`	2024-02-03 13:52:15 -06:00
Aaron Klinker	1d6aceab0a	Update changelog	2024-02-03 11:05:16 -06:00
Florian Metz	c1b5a9d270	docs: Add premid extension to homepage (#399 )	2024-02-02 22:46:46 -06:00
Aaron Klinker	f0b2a12724	chore(templates): Upgrade to wxt `^0.16.0`	2024-02-02 16:20:24 -06:00
Aaron Klinker	c45677ed48	Update changelog	2024-02-02 16:19:33 -06:00
GitHub Actions	7a3f075e21	chore(release): v0.16.0	2024-02-02 16:55:11 +00:00
Aaron Klinker	1e12ce2a0d	docs: Document how to opt into ESM	2024-02-02 10:48:00 -06:00
Aaron	eca30296a7	feat!: ESM background support (#398 ) BREAKING CHANGE: The build output has changed slightly. This isn't a huge deal, and no steps are required for users unless you're doing something weird with the output files after a build. Before: ``` .output/ <target>/ chunks/ popup-<hash>.js popup.html ``` After: ``` .output/ <target>/ popup.html popup.js ``` This applies for all HTML files, not just the popup.	2024-02-02 10:17:43 -06:00
dependabot[bot]	41fa320815	chore(deps-dev): bump @vitest/coverage-v8 from 1.0.1 to 1.2.2 (#397 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-02-02 07:07:50 -06:00
dependabot[bot]	873c24fa50	chore(deps-dev): bump p-map from 7.0.0 to 7.0.1 (#396 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-02-02 07:06:51 -06:00
dependabot[bot]	d92db5ba8f	chore(deps-dev): bump lint-staged from 15.2.0 to 15.2.1 (#395 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-02-02 07:06:31 -06:00
dependabot[bot]	1a6fe33f97	chore(deps): bump fast-glob from 3.3.1 to 3.3.2 (#394 ) Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2024-02-02 07:05:42 -06:00
GitHub Actions	2db4ea77a9	chore(release): v0.15.4	2024-01-31 17:42:07 +00:00
Aaron	ba5349ccaf	fix(submit): Load `.env.submit` automatically when running `wxt submit` and `wxt submit init` (#391 )	2024-01-31 11:38:11 -06:00
GitHub Actions	addb689de9	chore(release): v0.15.3	2024-01-31 14:59:26 +00:00
Aaron	2af8d28b82	fix(dev): Reload `<name>/index.html` entrypoints properly on save (#390 )	2024-01-31 08:50:23 -06:00
Aaron Klinker	ddbc66813e	Update changelog	2024-01-30 13:04:32 -06:00
GitHub Actions	0c8fc013a8	chore(release): v0.15.2	2024-01-30 19:01:54 +00:00
Aaron	26e30aaae9	feat: Add `submit` command (#370 )	2024-01-30 12:55:17 -06:00
Nenad Novaković	6557dfe430	fix(dev): Resolve `script` and `link` aliases (#387 ) Co-authored-by: Aaron Klinker <aaronklinker1@gmail.com>	2024-01-30 12:05:31 -06:00
Aaron Klinker	9cee9eefb4	Update changelog	2024-01-29 14:12:27 -06:00
GitHub Actions	f9cd7aaf05	chore(release): v0.15.1	2024-01-29 20:10:18 +00:00
0x7a7a	9049804413	docs: Fixed doc errors on the guide/extension-api page (#383 ) Co-authored-by: Aaron Klinker <aaronklinker1@gmail.com>	2024-01-29 14:06:27 -06:00
Aaron	d027a496f5	Upgrade `wxt init` templates to v0.15 (#385 )	2024-01-29 14:04:58 -06:00
Aaron	dd7abddb7c	feat: Allow passing custom preferences to chrome, enabling dev mode on `chrome://extensions` and allowing content script sourcemaps automatically (#384 )	2024-01-29 13:58:46 -06:00
Aaron Klinker	98d2792e02	chore: Fix vite version conflicts in demo extension	2024-01-29 13:53:57 -06:00
Aaron Klinker	39b76d3ec0	fix(security): Upgrade to vite@5.0.12 to resolve CVE-2024-23331	2024-01-29 11:25:31 -06:00
Aaron Klinker	bc29bfd434	Update changelog	2024-01-29 11:22:41 -06:00