chore(release): wxt v0.19.0

BREAKING CHANGE: Switch from using `jiti` to import entrypoints during the build process by default to `vite-node`.

To continue using `jiti`, add the following to your `wxt.config.ts` file:

```ts
export default defineConfig({
  entrypointLoader: "jiti",
})
```

NOTE: "jiti" is deprecated and will be removed in the next major version, `v0.20.0`.

README.md

@@ -18,7 +18,7 @@
   <br/>
   <span>⚡</span>
   <br/>
-  <q><i>It's like Nuxt, but for Chrome Extensions</i></q>
+  <q><i>It's like Nuxt, but for Web Extensions</i></q>
 </p>
 
 <p align="center">
@@ -62,6 +62,7 @@ Or see the [installation guide](https://wxt.dev/guide/installation.html) to get
 - 🖍️ Quickly bootstrap a new project
 - 📏 Bundle analysis
 - ⬇️ Download and bundle remote URL imports
+- 📦 Modular architecture with [modules](https://wxt.dev/guide/go-further/reusable-modules.html#overview)
 
 ## Contributors
 

docs/.vitepress/config.ts

@@ -145,6 +145,9 @@ export default defineConfig({
           menuItem('Entrypoint Side Effects', 'entrypoint-side-effects'),
           menuItem('How WXT Works', 'how-wxt-works'),
         ]),
+        menuGroup('Upgrade Guide', '/guide/upgrade-guide/', [
+          menuItem('wxt', 'wxt'),
+        ]),
       ]),
       '/api/': menuRoot([
         menuGroup('CLI', '/api/cli/', [

docs/get-started/compare.md

@@ -4,30 +4,44 @@ Lets compare the features of WXT vs [Plasmo](https://docs.plasmo.com/framework)
 
 ## Overview
 
-| Features                                             |             WXT             |                  Plasmo                  |                  CRXJS                  |
-| ---------------------------------------------------- | :-------------------------: | :--------------------------------------: | :-------------------------------------: |
-| Supports all browsers                                |             ✅              |                    ✅                    |        ✅ As of `v2.0.0-beta.23`        |
-| 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        |       🟡 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                                    |             ✅              |                    ✅                    |                   ❌                    |
+| Features                                             |       WXT        |     Plasmo      |      CRXJS       |
+| ---------------------------------------------------- | :--------------: | :-------------: | :--------------: |
+| Supports all browsers                                |        ✅        |       ✅        | 🟡 <sup>10</sup> |
+| MV2 Support                                          |        ✅        |       ✅        | 🟡 <sup>1</sup>  |
+| MV3 Support                                          |        ✅        |       ✅        | 🟡 <sup>1</sup>  |
+| Create Extension ZIPs                                |        ✅        |       ✅        |        ❌        |
+| Create Firefox Sources ZIP                           |        ✅        |       ❌        |        ❌        |
+| First-class TypeScript support                       |        ✅        |       ✅        |        ✅        |
+| Entrypoint discovery                                 | ✅ <sup>2</sup>  | ✅ <sup>2</sup> |        ❌        |
+| Inline entrypoint config                             |        ✅        |       ✅        | ❌ <sup>9</sup>  |
+| Auto-imports                                         |        ✅        |       ❌        |        ❌        |
+| Supports all frontend frameworks                     |        ✅        | 🟡 <sup>3</sup> |        ✅        |
+| Framework specific entrypoints (like `Popup.tsx`)    | 🟡 <sup>4</sup>  | ✅ <sup>5</sup> |        ❌        |
+| Automated publishing                                 |        ✅        |       ✅        |        ❌        |
+| Remote Code Bundling (Google Analytics)              |        ✅        |       ✅        |        ❌        |
+| <strong style="opacity: 50%">Dev Mode</strong>       |                  |                 |
+| `.env` Files                                         |        ✅        |       ✅        |        ✅        |
+| Opens browser with extension installed               |        ✅        |       ❌        |        ❌        |
+| HMR for UIs                                          |        ✅        | 🟡 <sup>6</sup> |        ✅        |
+| Reload HTML Files on Change                          |        ✅        | 🟡 <sup>7</sup> |        ✅        |
+| Reload Content Scripts on Change                     |        ✅        | 🟡 <sup>7</sup> |        ✅        |
+| Reload Background on Change                          | 🟡 <sup>7</sup>  | 🟡 <sup>7</sup> | 🟡 <sup>7</sup>  |
+| Respects Content Script `run_at`                     |        ✅        |       ✅        | ❌ <sup>8</sup>  |
+| <strong style="opacity: 50%">Built-in Utils</strong> |                  |                 |                  |
+| Storage                                              |        ✅        |       ✅        | ❌ <sup>11</sup> |
+| Messaging                                            | ❌ <sup>11</sup> |       ✅        | ❌ <sup>11</sup> |
+| Content Script UI                                    |        ✅        |       ✅        | ❌ <sup>11</sup> |
+
+<small>
+  <sup>1</sup>: Either MV2 or MV3, not both.
+  <br/><sup>2</sup>: File based.
+  <br/><sup>3</sup>: Only React, Vue, and Svelte.
+  <br/><sup>4</sup>: <code>.html</code> <code>.ts</code> <code>.tsx</code>.
+  <br/><sup>5</sup>: <code>.html</code> <code>.ts</code> <code>.tsx</code>. <code>.vue</code> <code>.svelte</code>.
+  <br/><sup>6</sup>: React only.
+  <br/><sup>7</sup>: Reloads entire extension.
+  <br/><sup>8</sup>: ESM-style loaders run asynchronously.
+  <br/><sup>9</sup>: Entrypoint options all configured in `manifest.json`.
+  <br/><sup>10</sup>: As of <code>v2.0.0-beta.23</code>, but v2 stable hasn't been released yet.
+  <br/><sup>11</sup>: There is no built-in wrapper around this API. However, you can still access the standard APIs via <code>chrome</code>/<code>browser</code> globals or use any 3rd party NPM package.
+</small>

docs/get-started/introduction.md

@@ -11,7 +11,7 @@ head:
 
 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.
+WXT is based on [Nuxt](https://nuxt.com), and aims to provide the same great DX with TypeScript, auto-imports, and an opinionated project structure.
 
 ![Example build output](../assets/cli-output.png)
 

docs/get-started/publishing.md

@@ -176,6 +176,8 @@ bun zip:firefox
 
 :::
 
+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.
+
 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
@@ -184,8 +186,6 @@ If you use a `.env` files, they can effect the chunk hashes in the output direct
 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.
-
 #### Private Packages
 
 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.

docs/guide/extension-apis/storage.md

@@ -121,7 +121,7 @@ Storage items contain the same APIs as the `storage` variable, but you can confi
 const showChangelogOnUpdate = storage.defineItem<boolean>(
   'local:showChangelogOnUpdate',
   {
-    defaultValue: true,
+    fallback: true,
   },
 );
 ```
@@ -153,7 +153,7 @@ type IgnoredWebsiteV1 = string;
 export const ignoredWebsites = storage.defineItem<IgnoredWebsiteV1[]>(
   'local:ignoredWebsites',
   {
-    defaultValue: [],
+    fallback: [],
     version: 1,
   },
 );
@@ -173,7 +173,7 @@ export const ignoredWebsites = storage.defineItem<IgnoredWebsiteV1[]>( // [!code
 export const ignoredWebsites = storage.defineItem<IgnoredWebsiteV2[]>( // [!code ++]
   'local:ignoredWebsites',
   {
-    defaultValue: [],
+    fallback: [],
     version: 1, // [!code --]
     version: 2, // [!code ++]
     migrations: { // [!code ++]
@@ -205,7 +205,7 @@ export const ignoredWebsites = storage.defineItem<IgnoredWebsiteV2[]>( // [!code
 export const ignoredWebsites = storage.defineItem<IgnoredWebsiteV3[]>( // [!code ++]
   'local:ignoredWebsites',
   {
-    defaultValue: [],
+    fallback: [],
     version: 2, // [!code --]
     version: 3, // [!code ++]
     migrations: {
@@ -242,7 +242,7 @@ Lets look at the same ignored websites example from before, but start with an un
 export const ignoredWebsites = storage.defineItem<string[]>(
   'local:ignoredWebsites',
   {
-    defaultValue: [],
+    fallback: [],
   },
 );
 ```
@@ -262,7 +262,7 @@ export const ignoredWebsites = storage.defineItem<string[]>( // [!code --]
 export const ignoredWebsites = storage.defineItem<IgnoredWebsiteV2[]>( // [!code ++]
   'local:ignoredWebsites',
   {
-    defaultValue: [],
+    fallback: [],
     version: 2, // [!code ++]
     migrations: { // [!code ++]
       // Ran when migrating from v1 to v2 // [!code ++]
@@ -279,3 +279,35 @@ 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.
+
+### Default Values
+
+With `storage.defineItem`, there are multiple ways of defining default values:
+
+1. `fallback` - Return this value from `getValue` instead of `null` if the value is missing.
+
+   This option is great for providing default values for settings:
+
+   ```ts
+   const theme = storage.defineItem('local:theme', {
+     fallback: 'dark',
+   });
+   const allowEditing = storage.defineItem('local:allow-editing', {
+     fallback: true,
+   });
+   ```
+
+2. `init` - Initialize and save a value in storage if it is not already saved.
+
+   This is great for values that need to be initialized or set once:
+
+   ```ts
+   const userId = storage.defineItem('local:user-id', {
+     init: () => globalThis.crypto.randomUUID(),
+   });
+   const installDate = storage.defineItem('local:install-date', {
+     init: () => new Date().getTime(),
+   });
+   ```
+
+   The value is initialized in storage immediately.

docs/guide/go-further/entrypoint-loaders.md

@@ -1,4 +1,29 @@
-# Entrypoint Side Effects
+# Entrypoint Loaders
+
+Because entrypoint options, like content script matches, are listed in the entrypoint's JS file, WXT has to import them during the build process to use those options when generating the manifest.
+
+There are two options for loading your entrypoints:
+
+1. `vite-node` - default as of `v0.19.0`
+2. `jiti` (**DEPRECATED, will be removed in `v0.20.0`**) - Default before `v0.19.0`
+
+## vite-node
+
+Since 0.19.0, WXT uses `vite-node`, the same tool that powers Vitest and Nuxt, to import your entrypoint files.
+
+There isn't really anything to add here... By default, it should "just work".
+
+## jiti
+
+The original method WXT used to import TS files. However, because it doesn't support vite plugins like `vite-node`, there is one main caveot to it's usage: **_module side-effects_**.
+
+To enable `jiti`:
+
+```ts
+export default defineConfig({
+  entrypointLoader: 'jiti',
+});
+```
 
 You cannot use imported variables outside the `main` function in JS entrypoints. This includes options, as shown below:
 

docs/guide/go-further/handling-updates.md

@@ -6,7 +6,7 @@ When releasing an update to your extension, there's a couple of things you need
 
 ## Content Script Cleanup
 
-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).
+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 an extension API.
 
 WXT provides a utility for handling this process: `ContentScriptContext`. An instance of this class is provided to you automatically inside the `main` function of each content script.
 
@@ -51,33 +51,12 @@ This prevents old content scripts from interfering with new content scripts, and
 
 ## Testing Permission Changes
 
-When `permissions`/`host_permissions` change during an update, depending on what exactly changed, Chrome will disable your extension until the user accepts the new permissions.
+When `permissions`/`host_permissions` change during an update, depending on what exactly changed, the browser will disable your extension until the user accepts the new permissions.
 
-It is possible to test this before you release an update, but it's not a simple process:
+You can test if your permission changes will result in a disabled extension:
 
-1. Get 2 ZIPs of your extension, both generated by `wxt zip`. The first contains a previous version of your extension, the second contains the latest version. Make sure the second ZIP's version is higher than the first's.
-2. Unzip the two ZIP files somewhere next to each other that's easy to locate.
-3. In Chrome, open `chrome://extensions` and make sure developer mode is enabled
-4. Pack the first extension into a CRX, generating a new private key:
-   1. Click "Pack Extension" in the top left
-   2. For "Extension root directory", enter the path to the first extracted zip directory. The directory should contain a `manifest.json` file
-   3. Leave "Private key file" blank
-   4. Click "Pack Extension". This will generate a `.crx` and `.pem` file
-5. Pack the second extension into a CRX, reusing the private key generated by the previous step
-   1. Click "Pack Extension" in the top left
-   2. For "Extension root directory", enter the path to the second extracted zip directory.
-   3. For "Private key file", enter the path to the generated `.pem` private key file
-   4. Click "Pack Extension". This will generate a second `.crx` file.
-6. Install the first CRX file by dragging and dropping it onto the `chrome://extensions` page
-7. Install the second CRX file by dragging and dropping it onthe the `chrome://extensions` page
-
-If a new permission must be accepted, you'll be prompted to accept it after dropping the second CRX file onto the page.
-
-:::Info Note
-Note: Chrome no longer allows self-signed CRX extensions to run, but that's OK for this test case. We're still prompted to accept new permissions, even if we can't interact with the installed extension.
-
-To validate this, you can create a third ZIP file with a rare permission like `geolocation` in the manifest, that's guarenteed to reprompt permissions when added.
-:::
+- Chromium: Use [Google's Extension Update Testing tool](https://github.com/GoogleChromeLabs/extension-update-testing-tool)
+- Firefox/Safari: Everyone breaks something in production eventually... 🫡 Good luck soldier
 
 ## Update Event
 
@@ -94,23 +73,4 @@ browser.runtime.onInstalled.addListener(({ reason }) => {
 If the logic is simple, write a unit test to cover this logic. If you feel the need to manually test this callback, you can either:
 
 1. In dev mode, remove the `if` statement and reload the extension from `chrome://extensions`
-2. Build two ZIPs with the same runtime ID and actually update the extension
-
-The first approach is very straightforward. The second is more complicated...
-
-Here are the steps:
-
-So the steps:
-
-1. Checkout an old commit.
-2. [Add a `key`](https://developer.chrome.com/docs/extensions/reference/manifest/key#keep-consistent-id) to the `manifest` in your `wxt.config.ts`.
-3. Run `wxt zip` to create the first ZIP.
-4. Stash or reset changes and checkout your latest code.
-5. Add back the same `key` to your manifest.
-6. Make sure the extension's version is higher than the first zip. It can be any version that's higher, since you won't be releasing this version.
-7. Run `wxt zip` to create the second ZIP.
-8. In a fresh chrome profile, go to `chrome://extensions`, enable dev mode, and drag and drop the first zip onto the page to install it.
-9. In the extension, play around and setup your test case.
-10. Back on `chrome://extensions`, drag and drop your second zip onto the page.
-
-If you setup the `key` correctly, it will cause the extension to act like it was updated instead of installing a second version of your extension.
+2. Use [Google's Extension Update Testing tool](https://github.com/GoogleChromeLabs/extension-update-testing-tool)

docs/guide/go-further/reusable-modules.md

@@ -176,7 +176,7 @@ export default defineWxtPlugin(() => {
 :::
 
 :::warning Async Plugins
-Unlike modules, **_plugins cannot be async_**!! If you need to do some async work and expose that result to the rest of the extension, wrap it in an object and handle awaiting the promise internally.
+Unlike modules, **_plugins cannot be async_**!! If you need to do some async work and expose that result to the rest of the extension, store the result's promise synchronously and await it later on.
 :::
 
 ## Publishing to NPM

docs/guide/key-concepts/auto-imports.md

@@ -6,7 +6,7 @@ WXT uses the same tool as Nuxt for auto-imports, [`unimport`](https://github.com
 
 Some WXT APIs can be used without importing them:
 
-- [`browser`](/api/reference/wxt/browser/#browser) from `wxt/browser`, a small wrapper around `webextension-polyfill`
+- [`browser`](/api/reference/wxt/browser/variables/browser) from `wxt/browser`, a small wrapper around `webextension-polyfill`
 - [`defineContentScript`](/api/reference/wxt/sandbox/functions/defineContentScript) from `wxt/sandbox`
 - [`defineBackground`](/api/reference/wxt/sandbox/functions/defineBackground) from `wxt/sandbox`
 - [`defineUnlistedScript`](/api/reference/wxt/sandbox/functions/defineUnlistedScript) from `wxt/sandbox`
@@ -96,7 +96,7 @@ export default defineConfig({
 
 ### ESLint 9 and above
 
-WXT supports the new "flat config" file format. Just import the generated file and add it to the array of config to extend.
+WXT supports the "flat config" file format introduced in ESLint 9. Just import the generated file and add it to the array of config to extend.
 
 ```js
 // eslint.config.mjs

docs/guide/key-concepts/frontend-frameworks.md

@@ -51,7 +51,7 @@ export default defineConfig({
 
 If your framework doesn't have an official WXT module, no worries! WXT supports any framework with a Vite plugin.
 
-Just add the Vite plugin to your config and you're good to go! Use the framework in HTML pages or content scripts, it will just work 👍
+Just add the Vite plugin to your config and you're good to go! Use the framework in HTML pages or content scripts and it will just work 👍
 
 ```ts
 import { defineConfig } from 'wxt';
@@ -102,7 +102,7 @@ Usually, this means each entrypoint should be a directory with it's own files in
 
 Lots of frameworks come with routers for building a multi-page app using the URL's path. Chrome extensions don't don't work like this. Since HTML files are static, `chrome-extension://{id}/popup.html`, there's no way to change the entire path for routing.
 
-Instead, you need to configure the router to run in "hash" mode, where the routing information is apart of the URL's hash, not the path (ie: `popup.html#/` and `popup.html#/account/settings`)
+Instead, you need to configure the router to run in "hash" mode, where the routing information is apart of the URL's hash, not the path (ie: `popup.html#/` and `popup.html#/account/settings`).
 
 Refer to your router's docs for information about hash mode and how to enable it. Here's a non-extensive list of a few popular routers:
 

docs/guide/key-concepts/manifest.md

@@ -102,7 +102,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/directory-structure/public/) and use them for the [manifest's `icons`](https://developer.chrome.com/docs/extensions/mv3/manifest/icons/).
 
@@ -135,7 +135,7 @@ export default defineConfig({
 });
 ```
 
-### Permissions
+## Permissions
 
 [Permissions](https://developer.chrome.com/docs/extensions/reference/permissions/) must be listed in the manifest config.
 
@@ -147,7 +147,7 @@ export default defineConfig({
 });
 ```
 
-### Host Permissions
+## Host Permissions
 
 [Host Permissions](https://developer.chrome.com/docs/extensions/develop/concepts/declare-permissions#host-permissions) must be listed in the manifest config.
 

docs/guide/key-concepts/web-extension-polyfill.md

@@ -4,7 +4,7 @@
 
 WXT is built on top [`webextension-polyfill` by Mozilla](https://www.npmjs.com/package/webextension-polyfill). The polyfill standardizes much of web extension APIs so they behave the same across different browsers and manifest versions.
 
-Unlike with Chrome Extension development, which uses a `chrome` global, you need to import the `browser` variable from WXT to use the polyfill:
+Unlike with Chrome Extension development, which uses a `chrome` global, you need to import the `browser` variable from WXT to access the extension APIs:
 
 ```ts
 import { browser } from 'wxt/browser';
@@ -80,11 +80,11 @@ WXT uses Vite, so all of Vite's `import.meta.env` variables are also available:
 
 Based on the files in your project, WXT will modify some of the polyfill's types to be type-safe.
 
-For example, `browser.runtime.getURL` will be typed to only allow getting the URL of known files.
+For example, `browser.runtime.getURL` will be typed to only allow getting the URL of known files. `browser.i18n.getMessage` will only allow getting translations of messages defined in your `public/_locales/<default-locale>/messages.json` file.
 
 ## Missing Types
 
-Some newer APIs that Chrome provides are missing types. But don't worry, the APIs are present at runtime! The polyfill only provides types for standard and stable APIs that work on all browsers, so just be careful when you use them.
+Some newer APIs that Chrome provides are missing types. Don't worry, the APIs are present at runtime! The polyfill only provides types for standard and stable APIs that work on all browsers, so just be careful when you use them.
 
 If you're using TypeScript, you can use `@ts-expect-error` to ignore any errors when using an API that doesn't have any types.
 

docs/guide/upgrade-guide/wxt.md

@@ -0,0 +1,272 @@
+# Upgrading WXT
+
+## Overview
+
+To upgrade WXT to the latest version... just install it!
+
+```sh
+pnpm i wxt@latest
+```
+
+If there was a major version change, follow the steps below to fix breaking changes.
+
+## v0.18.0 → v0.19.0
+
+### `vite-node` Entrypoint Loader
+
+The default entrypoint loader has changed to `vite-node`. This change enables:
+
+- Importing variables and using them in the entrypoint options.
+
+  ```ts
+  // entrypoints/content.ts
+  import { GOOGLE_MATCHES } from '~/utils/constants'
+
+  export default defineContentScript({
+    matches: [GOOGLE_MATCHES],
+    main: () => ...,
+  })
+  ```
+
+- Use Vite-specific APIs like `import.meta.glob` to define entrypoint options.
+
+  ```ts
+  // entrypoints/content.ts
+  const providers: Record<string, any> = import.meta.glob('../providers/*', {
+    eager: true,
+  });
+
+  export default defineContentScript({
+    matches: Object.values(providers).flatMap(
+      (provider) => provider.default.paths,
+    ),
+    async main() {
+      console.log('Hello content.');
+    },
+  });
+  ```
+
+To continue using the old approach, add the following to your `wxt.config.ts` file:
+
+```ts
+export default defineConfig({
+  entrypointLoader: 'jiti', // [!code ++]
+});
+```
+
+:::warning
+`entrypointLoader: "jiti"` is deprecated and will be removed in the next major version.
+:::
+
+### Drop CJS Support
+
+WXT no longer ships with Common JS support. If you're using CJS, here's your migration steps:
+
+1. Add [`"type": "module"`](https://nodejs.org/api/packages.html#type) to your `package.json`.
+2. Change the file extension of any `.js` files that use CJS syntax to `.cjs`, or update them to use EMS syntax.
+
+Vite also provides steps for migrating to ESM. Check them out for more details: https://vitejs.dev/guide/migration#deprecate-cjs-node-api
+
+## v0.17.0 &rarr; v0.18.0
+
+### Automatic MV3 `host_permissions` to MV2 `permissions`
+
+> Out of an abundance of caution, this change has been marked as a breaking change because permission generation is different.
+
+If you list `host_permissions` in your `wxt.config.ts`'s manifest and have released your extension, double check that your `permissions` and `host_permissions` have not changed for all browsers you target in your `.output/*/manifest.json` files. Permission changes can cause the extension to be disabled on update, and can cause a drop in users, so be sure to double check for differences compared to the previous manifest version.
+
+## v0.16.0 &rarr; v0.17.0
+
+### Storage - `defineItem` Requires `defaultValue` Option
+
+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
+const item = storage.defineItem<number>("local:count", { // [!code --]
+const item = storage.defineItem<number | null>("local:count", { // [!code ++]
+defaultValue: null, // [!code ++]
+  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();
+```
+
+### Storage - Fix Types In `watch` Callback
+
+> If you don't use TypeScript, this isn't a breaking change, this is just a type change.
+
+```ts
+const item = storage.defineItem<number>('local:count', { defaultValue: 0 });
+item.watch((newValue: number | null, oldValue: number | null) => { // [!code --]
+item.watch((newValue: number, oldValue: number) => { // [!code ++]
+  // ...
+});
+```
+
+## v0.15.0 &rarr; v0.16.0
+
+### Output Directory Structure Changed
+
+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.
+
+```
+.output/
+  <target>/
+    chunks/
+      some-shared-chunk-<hash>.js
+      popup-<hash>.js // [!code --]
+    popup.html
+    popup.html
+    popup.js // [!code ++]
+```
+
+## v0.14.0 &rarr; v0.15.0
+
+### Renamed `zip.ignoredSources` to `zip.excludeSources`
+
+```ts
+// wxt.config.ts
+export default defineConfig({
+  zip: {
+    ignoredSources: [
+      /*...*/
+    ], // [!code --]
+    excludeSources: [
+      /*...*/
+    ], // [!code ++]
+  },
+});
+```
+
+### Renamed Undocumented Constants
+
+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__` → `import.meta.env.BROWSER`
+- `__COMMAND__` → `import.meta.env.COMMAND`
+- `__MANIFEST_VERSION__` → `import.meta.env.MANIFEST_VERSION`
+- `__IS_CHROME__` → `import.meta.env.CHROME`
+- `__IS_FIREFOX__` → `import.meta.env.FIREFOX`
+- `__IS_SAFARI__` → `import.meta.env.SAFARI`
+- `__IS_EDGE__` → `import.meta.env.EDGE`
+- `__IS_OPERA__` → `import.meta.env.OPERA`
+
+## v0.13.0 &rarr; v0.14.0
+
+### Content Script UI API changes
+
+`createContentScriptUi` and `createContentScriptIframe`, and some of their options, have been renamed:
+
+- `createContentScriptUi({ ... })` &rarr; `createShadowRootUi({ ... })`
+- `createContentScriptIframe({ ... })` &rarr; `createIframeUi({ ... })`
+- `type: "inline" | "overlay" | "modal"` has been changed to `position: "inline" | "overlay" | "modal"`
+- `onRemove` is now called **_before_** the UI is removed from the DOM, previously it was called after the UI was removed
+- `mount` option has been renamed to `onMount`, to better match the related option, `onRemove`.
+
+## v0.12.0 &rarr; v0.13.0
+
+### New `wxt/storage` APIs
+
+`wxt/storage` no longer relies on [`unstorage`](https://www.npmjs.com/package/unstorage). Some `unstorage` APIs, like `prefixStorage`, have been removed, while others, like `snapshot`, are methods on the new `storage` object. Most of the standard usage remains the same. See https://wxt.dev/guide/storage and https://wxt.dev/api/reference/wxt/storage/ for more details ([#300](https://github.com/wxt-dev/wxt/pull/300))
+
+## v0.11.0 &rarr; v0.12.0
+
+### API Exports Changed
+
+`defineContentScript` and `defineBackground` are now exported from `wxt/sandbox` instead of `wxt/client`. ([#284](https://github.com/wxt-dev/wxt/pull/284))
+
+- If you use auto-imports, no changes are required.
+- If you have disabled auto-imports, you'll need to manually update your import statements:
+  ```ts
+  import { defineBackground, defineContentScript } from 'wxt/client'; // [!code --]
+  import { defineBackground, defineContentScript } from 'wxt/sandbox'; // [!code ++]
+  ```
+
+## v0.10.0 &rarr; v0.11.0
+
+### Vite 5
+
+You will need to update any other Vite plugins to a version that supports Vite 5.
+
+## v0.9.0 &rarr; v0.10.0
+
+### Extension Icon Discovery
+
+WXT no longer discovers icons other than `.png` files. If you previously used `.jpg`, `.jpeg`, `.bmp`, or `.svg`, you'll need to convert your icons to `.png` files or manually add them to the manifest inside your `wxt.config.ts` file.
+
+## v0.8.0 &rarr; v0.9.0
+
+### Removed `WebWorker` Types by Default
+
+Removed [`"WebWorker"` types](https://www.typescriptlang.org/tsconfig/lib.html) from `.wxt/tsconfig.json`. These types are useful for MV3 projects using a service worker.
+
+To add them back to your project, add the following to your project's TSConfig:
+
+```json
+{
+  "extends": "./.wxt/tsconfig.json",
+  "compilerOptions": {
+    // [!code ++]
+    "lib": ["ESNext", "DOM", "WebWorker"] // [!code ++]
+  } // [!code ++]
+}
+```
+
+## v0.7.0 &rarr; v0.8.0
+
+### `defineUnlistedScript`
+
+Unlisted scripts must now `export default defineUnlistedScript(...)`.
+
+### `BackgroundDefinition` Type
+
+Rename `BackgroundScriptDefintition` to `BackgroundDefinition`.
+
+## v0.6.0 &rarr; v0.7.0
+
+### Content Script CSS Output Location Changed
+
+Content script CSS used to be output to `assets/<name>.css`, but is now `content-scripts/<name>.css` to match the docs.
+
+## v0.5.0 &rarr; v0.6.0
+
+### Require a Function for `vite` Config
+
+The `vite` config option must now be a function. If you were using an object before, change it from `vite: { ... }` to `vite: () => ({ ... })`.
+
+## v0.4.0 &rarr; v0.5.0
+
+### Revert Move Public Directory
+
+Change default `publicDir` to from `<rootDir>/public` to `<srcDir>/public`.
+
+## v0.3.0 &rarr; v0.4.0
+
+### Update Default Path Aliases
+
+Use relative path aliases inside `.wxt/tsconfig.json`.
+
+## v0.2.0 &rarr; v0.3.0
+
+### Move Public Directory
+
+Change default `publicDir` to from `<srcDir>/public` to `<rootDir>/public`.
+
+### Improve Type Safety
+
+Add type safety to `browser.runtime.getURL`.
+
+## v0.1.0 &rarr; v0.2.0
+
+### Rename `defineBackground`
+
+Rename `defineBackgroundScript` to `defineBackground`.

docs/public/_redirects

@@ -2,6 +2,8 @@
 # https://docs.netlify.com/routing/redirects/
 
 # Old URLs -> New URLs
+
+# OLD
 /config.html                    /api/reference/wxt/interfaces/InlineConfig.html
 /api/config.html                /api/reference/wxt/interfaces/InlineConfig.html
 /entrypoints                    /entrypoints/background.html
@@ -29,3 +31,6 @@
 /guide/build-targets.html       /guide/multiple-browsers.html
 /guide/installation.html        /get-started/installation.html
 /guide/introduction.html        /get-started/introduction.html
+
+# 0.19.0
+/guide/go-further/entrypoint-side-effects.html /guide/go-further/entrypoint-loaders.html

packages/wxt-demo/wxt.config.ts

@@ -19,9 +19,6 @@ export default defineConfig({
   analysis: {
     open: true,
   },
-  experimental: {
-    entrypointImporter: 'vite-node',
-  },
   runner: {
     startUrls: ['https://duckduckgo.com'],
   },

packages/wxt/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## v0.19.0
+
+[compare changes](https://github.com/wxt-dev/wxt/compare/wxt-v0.18.15...wxt-v0.19.0)
+
+### 🚀 Enhancements
+
+- **experimental:** First-class support for excluding `webextension-polyfill` ([#847](https://github.com/wxt-dev/wxt/pull/847))
+- **storage:** `init` option and rename `defaultValue` to `fallback` ([#827](https://github.com/wxt-dev/wxt/pull/827))
+- **hooks:** Add `prepare:publicPaths` hook ([#858](https://github.com/wxt-dev/wxt/pull/858))
+- ⚠️  Use `vite-node` to load entrypoints by default ([#859](https://github.com/wxt-dev/wxt/pull/859))
+
+### 🔥 Performance
+
+- **size:** ⚠️  Switch from `tsup` to `unbuild` for building WXT ([#848](https://github.com/wxt-dev/wxt/pull/848))
+
+### 🩹 Fixes
+
+- Wrong module hook type ([#849](https://github.com/wxt-dev/wxt/pull/849))
+
+### 📖 Documentation
+
+- Update labels in content script UI positioning screenshot ([2b6ff8d](https://github.com/wxt-dev/wxt/commit/2b6ff8d))
+- Add upgrade guide and breaking changes ([#860](https://github.com/wxt-dev/wxt/pull/860))
+
+### 🏡 Chore
+
+- **deps:** Bump all non-major dependencies ([#834](https://github.com/wxt-dev/wxt/pull/834))
+- **dev-deps:** Upgrade `vitest` from 1.6 to 2.0 ([#836](https://github.com/wxt-dev/wxt/pull/836))
+- **deps:** Upgrade `async-mutex` from 0.4.1 to 0.5.0 ([#837](https://github.com/wxt-dev/wxt/pull/837))
+- **deps:** Upgrade `esbuild` from 0.19.12 to 0.23.0 ([#838](https://github.com/wxt-dev/wxt/pull/838))
+- **deps:** Upgrade `vite-node` from 1.6 to 2.0 ([#839](https://github.com/wxt-dev/wxt/pull/839))
+- **deps:** Upgrade `ora` from 7 to 8 ([#841](https://github.com/wxt-dev/wxt/pull/841))
+- **deps:** Upgrade `webextension-polyfill` from 0.10 to 0.12 ([#842](https://github.com/wxt-dev/wxt/pull/842))
+- **deps:** Upgrade `minimatch` from 9 to 10 ([#840](https://github.com/wxt-dev/wxt/pull/840))
+- **dev-deps:** Upgrade `happy-dom` from 13 to 14 ([#843](https://github.com/wxt-dev/wxt/pull/843))
+
+#### ⚠️ Breaking Changes
+
+- ⚠️  Use `vite-node` to load entrypoints by default ([#859](https://github.com/wxt-dev/wxt/pull/859))
+- **size:** ⚠️  Switch from `tsup` to `unbuild` for building WXT ([#848](https://github.com/wxt-dev/wxt/pull/848))
+
+### ❤️ Contributors
+
+- Florian Metz ([@Timeraa](http://github.com/Timeraa))
+
 ## v0.18.15
 
 [compare changes](https://github.com/wxt-dev/wxt/compare/wxt-v0.18.14...wxt-v0.18.15)
@@ -298,7 +343,7 @@
 
 ## v0.18.0
 
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.17.12...v0.18.0)
+[⚠️ breaking changes](https://wxt.dev/guide/upgrade-guide/wxt) • [compare changes](https://github.com/wxt-dev/wxt/compare/v0.17.12...v0.18.0)
 
 ### 🚀 Enhancements
 
@@ -333,12 +378,6 @@
 - Refactor repo to a standard monorepo ([#646](https://github.com/wxt-dev/wxt/pull/646))
 - Fix formatting after monorepo refactor ([6ca3767](https://github.com/wxt-dev/wxt/commit/6ca3767))
 
-#### ⚠️ Breaking Changes
-
-- ⚠️ Automatically move `host_permissions` to `permissions` for MV2 ([#626](https://github.com/wxt-dev/wxt/pull/626))
-
-  Out of an abundance of caution, I've marked this as a breaking change because permission generation has changed. **_If you list `host_permissions` in your `wxt.config.ts`'s manifest and have released your extension_**, double check that your `permissions` and `host_permissions` have not changed for all browsers you target in your `.output/*/manifest.json` files. Permission changes can cause the extension to be disabled on update, and can cause a drop in users, so be sure to double check for differences compared to the previous manifest version.
-
 ### ❤️ Contributors
 
 - Alegal200 ([@alegal200](https://github.com/alegal200))
@@ -605,7 +644,7 @@
 
 ## v0.17.0
 
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.16.11...v0.17.0)
+[⚠️ breaking changes](https://wxt.dev/guide/upgrade-guide/wxt) • [compare changes](https://github.com/wxt-dev/wxt/compare/v0.16.11...v0.17.0)
 
 ### 🚀 Enhancements
 
@@ -620,70 +659,6 @@
 
 - **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)
@@ -889,7 +864,7 @@ item.migrate();
 
 ## v0.16.0
 
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.15.4...v0.16.0)
+[⚠️ breaking changes](https://wxt.dev/guide/upgrade-guide/wxt) &bull; [compare changes](https://github.com/wxt-dev/wxt/compare/v0.15.4...v0.16.0)
 
 ### 🚀 Enhancements
 
@@ -905,31 +880,6 @@ item.migrate();
 - **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)
@@ -988,7 +938,7 @@ This effects all HTML files, not just the Popup. The hash has been removed, and
 
 ## v0.15.0
 
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.14.7...v0.15.0)
+[⚠️ breaking changes](https://wxt.dev/guide/upgrade-guide/wxt) &bull; [compare changes](https://github.com/wxt-dev/wxt/compare/v0.14.7...v0.15.0)
 
 ### 🚀 Enhancements
 
@@ -1008,21 +958,6 @@ This effects all HTML files, not just the Popup. The hash has been removed, and
 
 - Update contributor docs ([eb758bd](https://github.com/wxt-dev/wxt/commit/eb758bd))
 
-#### ⚠️ Breaking Changes
-
-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ć ([@dvlden](https://github.com/dvlden))
@@ -1143,22 +1078,12 @@ Renamed undocumented constants for detecting the build config at runtime in [#38
 
 ## v0.14.0
 
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.13.5...v0.14.0)
+[⚠️ breaking changes](https://wxt.dev/guide/upgrade-guide/wxt) &bull; [compare changes](https://github.com/wxt-dev/wxt/compare/v0.13.5...v0.14.0)
 
 ### 🚀 Enhancements
 
 - ⚠️ Refactor content script UI functions and add helper for "integrated" UIs ([#333](https://github.com/wxt-dev/wxt/pull/333))
 
-#### ⚠️ Breaking Changes
-
-`createContentScriptUi` and `createContentScriptIframe`, and some of their options, have been renamed:
-
-- `createContentScriptUi({ ... })` &rarr; `createShadowRootUi({ ... })`
-- `createContentScriptIframe({ ... })` &rarr; `createIframeUi({ ... })`
-- `type: "inline" | "overlay" | "modal"` has been changed to `position: "inline" | "overlay" | "modal"`
-- `onRemove` is now called **_before_** the UI is removed from the DOM, previously it was called after the UI was removed
-- `mount` option has been renamed to `onMount`, to better match the related option, `onRemove`.
-
 ## v0.13.5
 
 [compare changes](https://github.com/wxt-dev/wxt/compare/v0.13.4...v0.13.5)
@@ -1248,16 +1173,12 @@ Renamed undocumented constants for detecting the build config at runtime in [#38
 
 ## v0.13.0
 
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.12.5...v0.13.0)
+[⚠️ breaking changes](https://wxt.dev/guide/upgrade-guide/wxt) &bull; [compare changes](https://github.com/wxt-dev/wxt/compare/v0.12.5...v0.13.0)
 
 ### 🚀 Enhancements
 
 - ⚠️ New `wxt/storage` APIs ([#300](https://github.com/wxt-dev/wxt/pull/300))
 
-#### ⚠️ Breaking Changes
-
-- `wxt/storage` no longer relies on [`unstorage`](https://www.npmjs.com/package/unstorage). Some `unstorage` APIs, like `prefixStorage`, have been removed, while others, like `snapshot`, are methods on the new `storage` object. Most of the standard usage remains the same. See https://wxt.dev/guide/storage and https://wxt.dev/api/reference/wxt/storage/ for more details ([#300](https://github.com/wxt-dev/wxt/pull/300))
-
 ## v0.12.5
 
 [compare changes](https://github.com/wxt-dev/wxt/compare/v0.12.4...v0.12.5)
@@ -1305,7 +1226,7 @@ Renamed undocumented constants for detecting the build config at runtime in [#38
 
 ## v0.12.0
 
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.11.2...v0.12.0)
+[⚠️ breaking changes](https://wxt.dev/guide/upgrade-guide/wxt) &bull; [compare changes](https://github.com/wxt-dev/wxt/compare/v0.11.2...v0.12.0)
 
 ### 🚀 Enhancements
 
@@ -1325,17 +1246,6 @@ Renamed undocumented constants for detecting the build config at runtime in [#38
 
 - Convert WXT CLI to an ESM binary ([#279](https://github.com/wxt-dev/wxt/pull/279))
 
-#### ⚠️ Breaking Changes
-
-`defineContentScript` and `defineBackground` are now exported from `wxt/sandbox` instead of `wxt/client`. ([#284](https://github.com/wxt-dev/wxt/pull/284))
-
-- If you use auto-imports, no changes are required.
-- If you have disabled auto-imports, you'll need to manually update your import statements:
-  ```diff
-  - import { defineBackground, defineContentScript } from 'wxt/client';
-  + import { defineBackground, defineContentScript } from 'wxt/sandbox';
-  ```
-
 ## v0.11.2
 
 [compare changes](https://github.com/wxt-dev/wxt/compare/v0.11.1...v0.11.2)
@@ -1368,7 +1278,7 @@ Renamed undocumented constants for detecting the build config at runtime in [#38
 
 ## v0.11.0
 
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.10.4...v0.11.0)
+[⚠️ breaking changes](https://wxt.dev/guide/upgrade-guide/wxt) &bull; [compare changes](https://github.com/wxt-dev/wxt/compare/v0.10.4...v0.11.0)
 
 ### 🚀 Enhancements
 
@@ -1383,10 +1293,6 @@ Renamed undocumented constants for detecting the build config at runtime in [#38
 - Speed up CI using `pnpm` instead of `npm` ([#259](https://github.com/wxt-dev/wxt/pull/259))
 - Abstract vite from WXT's core logic ([#242](https://github.com/wxt-dev/wxt/pull/242))
 
-#### ⚠️ Breaking Changes
-
-- You will need to update any other Vite plugins to a version that supports Vite 5 ([#261](https://github.com/wxt-dev/wxt/pull/261))
-
 ### ❤️ Contributors
 
 - Ítalo Brasil ([@italodeverdade](http://github.com/italodeverdade))
@@ -1459,7 +1365,7 @@ Renamed undocumented constants for detecting the build config at runtime in [#38
 
 ## v0.10.0
 
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.9.2...v0.10.0)
+[⚠️ breaking changes](https://wxt.dev/guide/upgrade-guide/wxt) &bull; [compare changes](https://github.com/wxt-dev/wxt/compare/v0.9.2...v0.10.0)
 
 ### 🚀 Enhancements
 
@@ -1532,7 +1438,7 @@ Renamed undocumented constants for detecting the build config at runtime in [#38
 
 ## v0.9.0
 
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.8.7...v0.9.0)
+[⚠️ breaking changes](https://wxt.dev/guide/upgrade-guide/wxt) &bull; [compare changes](https://github.com/wxt-dev/wxt/compare/v0.8.7...v0.9.0)
 
 ### 🩹 Fixes
 
@@ -1547,18 +1453,6 @@ Renamed undocumented constants for detecting the build config at runtime in [#38
 
 - Fix Svelte and React template READMEs ([#207](https://github.com/wxt-dev/wxt/pull/207))
 
-#### ⚠️ Breaking Changes
-
-- ⚠️ Removed [`"WebWorker"` types](https://www.typescriptlang.org/tsconfig/lib.html) from `.wxt/tsconfig.json` ([#209](https://github.com/wxt-dev/wxt/pull/209)). These types are useful for MV3 projects using a service worker. To add them back to your project, add the following to your project's TSConfig:
-  ```diff
-  {
-    "extends": "./.wxt/tsconfig.json",
-  + "compilerOptions": {
-  +   "lib": ["ESNext", "DOM", "WebWorker"]
-  + }
-  }
-  ```
-
 ### ❤️ Contributors
 
 - yyyanghj ([@yyyanghj](https://github.com/yyyanghj))
@@ -1667,7 +1561,7 @@ Renamed undocumented constants for detecting the build config at runtime in [#38
 
 ## v0.8.0
 
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.7.5...v0.8.0)
+[⚠️ breaking changes](https://wxt.dev/guide/upgrade-guide/wxt) &bull; [compare changes](https://github.com/wxt-dev/wxt/compare/v0.7.5...v0.8.0)
 
 ### 🚀 Enhancements
 
@@ -1681,11 +1575,6 @@ Renamed undocumented constants for detecting the build config at runtime in [#38
 
 - ⚠️ Rename `BackgroundScriptDefintition` to `BackgroundDefinition` ([446f265](https://github.com/wxt-dev/wxt/commit/446f265))
 
-#### ⚠️ Breaking Changes
-
-- ⚠️ Unlisted scripts must now `export default defineUnlistedScript(...)` ([#167](https://github.com/wxt-dev/wxt/pull/167))
-- ⚠️ Rename `BackgroundScriptDefintition` to `BackgroundDefinition` ([446f265](https://github.com/wxt-dev/wxt/commit/446f265))
-
 ### ❤️ Contributors
 
 - 渣渣120 [@WOSHIZHAZHA120](https://github.com/WOSHIZHAZHA120)
@@ -1768,7 +1657,7 @@ Renamed undocumented constants for detecting the build config at runtime in [#38
 
 ## v0.7.0
 
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.6.6...v0.7.0)
+[⚠️ breaking changes](https://wxt.dev/guide/upgrade-guide/wxt) &bull; [compare changes](https://github.com/wxt-dev/wxt/compare/v0.6.6...v0.7.0)
 
 ### 🚀 Enhancements
 
@@ -1784,10 +1673,6 @@ Renamed undocumented constants for detecting the build config at runtime in [#38
 
 - Store user config metadata in memory ([0591050](https://github.com/wxt-dev/wxt/commit/0591050))
 
-#### ⚠️ Breaking Changes
-
-- ⚠️ Content script CSS used to be output to `assets/<name>.css`, but is now `content-scripts/<name>.css` to match the docs. ([#140](https://github.com/wxt-dev/wxt/pull/140))
-
 ## v0.6.6
 
 [compare changes](https://github.com/wxt-dev/wxt/compare/v0.6.5...v0.6.6)
@@ -1870,7 +1755,7 @@ Renamed undocumented constants for detecting the build config at runtime in [#38
 
 ## v0.6.0
 
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.5.6...v0.6.0)
+[⚠️ breaking changes](https://wxt.dev/guide/upgrade-guide/wxt) &bull; [compare changes](https://github.com/wxt-dev/wxt/compare/v0.5.6...v0.6.0)
 
 ### 🚀 Enhancements
 
@@ -1882,10 +1767,6 @@ Renamed undocumented constants for detecting the build config at runtime in [#38
 - Use the same mode for each build step ([1f6a931](https://github.com/wxt-dev/wxt/commit/1f6a931))
 - Disable dev logs in production ([3f260ee](https://github.com/wxt-dev/wxt/commit/3f260ee))
 
-#### ⚠️ Breaking Changes
-
-- ⚠️ The `vite` config option must now be a function. If you were using an object before, change it from `vite: { ... }` to `vite: () => ({ ... })`. ([#121](https://github.com/wxt-dev/wxt/pull/121))
-
 ## v0.5.6
 
 [compare changes](https://github.com/wxt-dev/wxt/compare/v0.5.5...v0.5.6)
@@ -1946,7 +1827,7 @@ Renamed undocumented constants for detecting the build config at runtime in [#38
 
 ## v0.5.0
 
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.4.1...v0.5.0)
+[⚠️ breaking changes](https://wxt.dev/guide/upgrade-guide/wxt) &bull; [compare changes](https://github.com/wxt-dev/wxt/compare/v0.4.1...v0.5.0)
 
 ### 🩹 Fixes
 
@@ -1969,10 +1850,6 @@ Renamed undocumented constants for detecting the build config at runtime in [#38
 - **deps-dev:** Bump @types/node from 20.5.0 to 20.5.9 ([#110](https://github.com/wxt-dev/wxt/pull/110))
 - Add entrypoints debug log ([dbd84c8](https://github.com/wxt-dev/wxt/commit/dbd84c8))
 
-#### ⚠️ Breaking Changes
-
-- ⚠️ Change default `publicDir` to `<srcDir>/public` ([5f15f9c](https://github.com/wxt-dev/wxt/commit/5f15f9c))
-
 ## v0.4.1
 
 [compare changes](https://github.com/wxt-dev/wxt/compare/v0.4.0...v0.4.1)
@@ -1987,7 +1864,7 @@ Renamed undocumented constants for detecting the build config at runtime in [#38
 
 ## v0.4.0
 
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.3.2...v0.4.0)
+[⚠️ breaking changes](https://wxt.dev/guide/upgrade-guide/wxt) &bull; [compare changes](https://github.com/wxt-dev/wxt/compare/v0.3.2...v0.4.0)
 
 ### 🚀 Enhancements
 
@@ -2030,10 +1907,6 @@ Renamed undocumented constants for detecting the build config at runtime in [#38
 - 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
-
-- ⚠️ Use relative path aliases inside `.wxt/tsconfig.json` ([#102](https://github.com/wxt-dev/wxt/pull/102))
-
 ## v0.3.2
 
 [compare changes](https://github.com/wxt-dev/wxt/compare/v0.3.1...v0.3.2)
@@ -2100,7 +1973,7 @@ Renamed undocumented constants for detecting the build config at runtime in [#38
 
 ## v0.3.0
 
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.2.5...v0.3.0)
+[⚠️ breaking changes](https://wxt.dev/guide/upgrade-guide/wxt) &bull; [compare changes](https://github.com/wxt-dev/wxt/compare/v0.2.5...v0.3.0)
 
 ### 🚀 Enhancements
 
@@ -2124,11 +1997,6 @@ Renamed undocumented constants for detecting the build config at runtime in [#38
 
 - Improve checks against `demo/` extension ([9cc464f](https://github.com/wxt-dev/wxt/commit/9cc464f))
 
-#### ⚠️ Breaking Changes
-
-- ⚠️ Add type safety to `browser.runtime.getURL` ([58a84ec](https://github.com/wxt-dev/wxt/commit/58a84ec))
-- ⚠️ Change default `publicDir` to `<rootDir>/public` ([19c0948](https://github.com/wxt-dev/wxt/commit/19c0948))
-
 ## v0.2.5
 
 [compare changes](https://github.com/wxt-dev/wxt/compare/v0.2.4...v0.2.5)
@@ -2191,7 +2059,7 @@ Renamed undocumented constants for detecting the build config at runtime in [#38
 
 ## v0.2.0
 
-[compare changes](https://github.com/wxt-dev/wxt/compare/v0.1.6...v0.2.0)
+[⚠️ breaking changes](https://wxt.dev/guide/upgrade-guide/wxt) &bull; [compare changes](https://github.com/wxt-dev/wxt/compare/v0.1.6...v0.2.0)
 
 ### 🚀 Enhancements
 
@@ -2209,10 +2077,6 @@ Renamed undocumented constants for detecting the build config at runtime in [#38
 - Run `wxt prepare` on `postinstall` ([c1ea9ba](https://github.com/wxt-dev/wxt/commit/c1ea9ba))
 - Don't format lockfile ([5c7e041](https://github.com/wxt-dev/wxt/commit/5c7e041))
 
-#### ⚠️ Breaking Changes
-
-- ⚠️ Rename `defineBackgroundScript` to `defineBackground` ([5b48ae9](https://github.com/wxt-dev/wxt/commit/5b48ae9))
-
 ## v0.1.6
 
 [compare changes](https://github.com/wxt-dev/wxt/compare/v0.1.5...v0.1.6)

packages/wxt/e2e/tests/hooks.test.ts

@@ -5,6 +5,7 @@ import { WxtHooks } from '../../src/types';
 const hooks: WxtHooks = {
   ready: vi.fn(),
   'prepare:types': vi.fn(),
+  'prepare:publicPaths': vi.fn(),
   'build:before': vi.fn(),
   'build:done': vi.fn(),
   'build:manifestGenerated': vi.fn(),
@@ -43,6 +44,7 @@ describe('Hooks', () => {
     expectHooksToBeCalled({
       ready: true,
       'prepare:types': true,
+      'prepare:publicPaths': true,
       'build:before': false,
       'build:done': false,
       'build:publicAssets': false,
@@ -63,6 +65,7 @@ describe('Hooks', () => {
     expectHooksToBeCalled({
       ready: true,
       'prepare:types': true,
+      'prepare:publicPaths': true,
       'build:before': true,
       'build:done': true,
       'build:publicAssets': true,
@@ -83,6 +86,7 @@ describe('Hooks', () => {
     expectHooksToBeCalled({
       ready: true,
       'prepare:types': true,
+      'prepare:publicPaths': true,
       'build:before': true,
       'build:done': true,
       'build:publicAssets': true,
@@ -109,6 +113,7 @@ describe('Hooks', () => {
     expectHooksToBeCalled({
       ready: true,
       'prepare:types': true,
+      'prepare:publicPaths': true,
       'build:before': true,
       'build:done': true,
       'build:publicAssets': true,

packages/wxt/e2e/tests/manifest-content.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect } from 'vitest';
 import { TestProject } from '../utils';
 
-describe.each(['jiti', 'vite-runtime', 'vite-node'] as const)(
+describe.each(['vite-node', 'jiti'] as const)(
   'Manifest Content (Vite runtime? %s)',
   (entrypointImporter) => {
     it.each([

packages/wxt/package.json

@@ -1,7 +1,7 @@
 {
   "name": "wxt",
   "type": "module",
-  "version": "0.19.0-alpha1",
+  "version": "0.19.0",
   "description": "Next gen framework for developing web extensions",
   "repository": {
     "type": "git",
@@ -53,10 +53,6 @@
       "types": "./dist/browser/chrome.d.ts",
       "import": "./dist/browser/chrome.mjs"
     },
-    "./browser/webextension-polyfill": {
-      "types": "./dist/browser/webextension-polyfill.d.ts",
-      "import": "./dist/browser/webextension-polyfill.mjs"
-    },
     "./testing": {
       "types": "./dist/testing/index.d.ts",
       "default": "./dist/testing/index.mjs"

packages/wxt/src/__tests__/storage.test.ts

@@ -11,6 +11,14 @@ async function waitForMigrations() {
   return new Promise((res) => setTimeout(res));
 }
 
+/**
+ * Same as `waitForMigrations`, the fake browser being synchronous means the
+ * `init` logic is finished by the next task in the event queue.
+ */
+async function waitForInit() {
+  return new Promise((res) => setTimeout(res));
+}
+
 describe('Storage Utils', () => {
   beforeEach(() => {
     fakeBrowser.reset();
@@ -813,20 +821,56 @@ describe('Storage Utils', () => {
       });
     });
 
-    describe('defaultValue', () => {
-      it('should return the default value when provided', () => {
-        const defaultValue = 123;
-        const item = storage.defineItem(`local:test`, {
-          defaultValue,
+    describe.each(['fallback', 'defaultValue'] as const)(
+      '%s option',
+      (fallbackKey) => {
+        it('should return the default value when provided', () => {
+          const fallback = 123;
+          const item = storage.defineItem(`local:test`, {
+            [fallbackKey]: fallback,
+          });
+
+          expect(item.fallback).toBe(fallback);
+          expect(item.defaultValue).toBe(fallback);
         });
 
-        expect(item.defaultValue).toBe(defaultValue);
+        it('should return null when not provided', () => {
+          const item = storage.defineItem<number>(`local:test`);
+
+          expect(item.fallback).toBeNull();
+          expect(item.defaultValue).toBeNull();
+        });
+      },
+    );
+
+    describe('init option', () => {
+      it('should only call init once (per JS context) when calling getValue successively, avoiding race conditions', async () => {
+        const expected = 1;
+        const init = vi
+          .fn()
+          .mockResolvedValueOnce(expected)
+          .mockResolvedValue('not' + expected);
+        const item = storage.defineItem('local:test', { init });
+
+        await waitForInit();
+
+        const p1 = item.getValue();
+        const p2 = item.getValue();
+
+        await expect(p1).resolves.toBe(expected);
+        await expect(p2).resolves.toBe(expected);
+
+        expect(init).toBeCalledTimes(1);
       });
 
-      it('should return null when not provided', () => {
-        const item = storage.defineItem<number>(`local:test`);
+      it('should initialize the value in storage immediately', async () => {
+        const expected = 1;
+        const init = vi.fn().mockReturnValue(expected);
+        storage.defineItem('local:test', { init });
 
-        expect(item.defaultValue).toBeNull();
+        await waitForInit();
+
+        await expect(storage.getItem('local:test')).resolves.toBe(expected);
       });
     });
 

packages/wxt/src/browser/index.ts

@@ -1,4 +1,84 @@
 /**
+ * Includes the `browser` API and types when using `extensionApi: 'webextension-polyfill'` (the default).
+ *
  * @module wxt/browser
  */
-export * from './webextension-polyfill';
+
+import originalBrowser, { Browser, Runtime, I18n } from 'webextension-polyfill';
+
+export interface AugmentedBrowser extends Browser {
+  runtime: WxtRuntime;
+  i18n: WxtI18n;
+}
+
+export interface WxtRuntime extends Runtime.Static {
+  // Overriden per-project
+}
+
+export interface WxtI18n extends I18n.Static {
+  // Overriden per-project
+}
+
+export const browser: AugmentedBrowser = originalBrowser;
+
+// re-export all the types from webextension-polyfill
+// Because webextension-polyfill uses a weird namespace with "import export", there isn't a good way
+// to get these types without re-listing them.
+/** @ignore */
+export type {
+  ActivityLog,
+  Alarms,
+  Bookmarks,
+  Action,
+  BrowserAction,
+  BrowserSettings,
+  BrowsingData,
+  CaptivePortal,
+  Clipboard,
+  Commands,
+  ContentScripts,
+  ContextualIdentities,
+  Cookies,
+  DeclarativeNetRequest,
+  Devtools,
+  Dns,
+  Downloads,
+  Events,
+  Experiments,
+  Extension,
+  ExtensionTypes,
+  Find,
+  GeckoProfiler,
+  History,
+  I18n,
+  Identity,
+  Idle,
+  Management,
+  Manifest, // TODO: Export custom manifest types that are valid for both Chrome and Firefox.
+  ContextMenus,
+  Menus,
+  NetworkStatus,
+  NormandyAddonStudy,
+  Notifications,
+  Omnibox,
+  PageAction,
+  Permissions,
+  Pkcs11,
+  Privacy,
+  Proxy,
+  Runtime,
+  Scripting,
+  Search,
+  Sessions,
+  SidebarAction,
+  Storage,
+  Tabs,
+  Theme,
+  TopSites,
+  Types,
+  Urlbar,
+  UserScripts,
+  WebNavigation,
+  WebRequest,
+  Windows,
+} from 'webextension-polyfill';

packages/wxt/src/browser/webextension-polyfill.ts

@@ -1,84 +0,0 @@
-/**
- * Includes the `browser` API and types when using `extensionApi: 'webextension-polyfill'` (the default).
- *
- * @module wxt/browser/webextension-polyfill
- */
-
-import originalBrowser, { Browser, Runtime, I18n } from 'webextension-polyfill';
-
-export interface AugmentedBrowser extends Browser {
-  runtime: WxtRuntime;
-  i18n: WxtI18n;
-}
-
-export interface WxtRuntime extends Runtime.Static {
-  // Overriden per-project
-}
-
-export interface WxtI18n extends I18n.Static {
-  // Overriden per-project
-}
-
-export const browser: AugmentedBrowser = originalBrowser;
-
-// re-export all the types from webextension-polyfill
-// Because webextension-polyfill uses a weird namespace with "import export", there isn't a good way
-// to get these types without re-listing them.
-/** @ignore */
-export type {
-  ActivityLog,
-  Alarms,
-  Bookmarks,
-  Action,
-  BrowserAction,
-  BrowserSettings,
-  BrowsingData,
-  CaptivePortal,
-  Clipboard,
-  Commands,
-  ContentScripts,
-  ContextualIdentities,
-  Cookies,
-  DeclarativeNetRequest,
-  Devtools,
-  Dns,
-  Downloads,
-  Events,
-  Experiments,
-  Extension,
-  ExtensionTypes,
-  Find,
-  GeckoProfiler,
-  History,
-  I18n,
-  Identity,
-  Idle,
-  Management,
-  Manifest, // TODO: Export custom manifest types that are valid for both Chrome and Firefox.
-  ContextMenus,
-  Menus,
-  NetworkStatus,
-  NormandyAddonStudy,
-  Notifications,
-  Omnibox,
-  PageAction,
-  Permissions,
-  Pkcs11,
-  Privacy,
-  Proxy,
-  Runtime,
-  Scripting,
-  Search,
-  Sessions,
-  SidebarAction,
-  Storage,
-  Tabs,
-  Theme,
-  TopSites,
-  Types,
-  Urlbar,
-  UserScripts,
-  WebNavigation,
-  WebRequest,
-  Windows,
-} from 'webextension-polyfill';

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

@@ -183,9 +183,9 @@ export interface ContentScriptModalPositioningOptions {
 }
 
 /**
- * Choose between `"inline"`, `"overlay"`, or `"modal" `types.
+ * Choose between `"inline"`, `"overlay"`, or `"modal"` positions.
  *
- * ![Visualization of different types](https://wxt.dev/content-script-ui-type.png)
+ * ![Visualization of different types](https://wxt.dev/content-script-ui-position.png)
  */
 export type ContentScriptPositioningOptions =
   | ContentScriptInlinePositioningOptions

packages/wxt/src/core/builders/vite/index.ts

@@ -35,7 +35,9 @@ export async function createViteBuilder(
   /**
    * Returns the base vite config shared by all builds based on the inline and user config.
    */
-  const getBaseConfig = async () => {
+  const getBaseConfig = async (baseConfigOptions?: {
+    excludeAnalysisPlugin?: boolean;
+  }) => {
     const config: vite.InlineConfig = await wxtConfig.vite(wxtConfig.env);
 
     config.root = wxtConfig.root;
@@ -71,7 +73,12 @@ export async function createViteBuilder(
       wxtPlugins.wxtPluginLoader(wxtConfig),
       wxtPlugins.resolveAppConfig(wxtConfig),
     );
-    if (wxtConfig.analysis.enabled) {
+    if (
+      wxtConfig.analysis.enabled &&
+      // If included, vite-node entrypoint loader will increment the
+      // bundleAnalysis's internal build index tracker, which we don't want
+      !baseConfigOptions?.excludeAnalysisPlugin
+    ) {
       config.plugins.push(wxtPlugins.bundleAnalysis(wxtConfig));
     }
 
@@ -209,29 +216,15 @@ export async function createViteBuilder(
     name: 'Vite',
     version: vite.version,
     async importEntrypoint(path) {
-      switch (wxtConfig.experimental.entrypointImporter) {
+      switch (wxtConfig.entrypointLoader) {
         default:
         case 'jiti': {
           return await importEntrypointFile(path);
         }
-        case 'vite-runtime': {
-          const baseConfig = await getBaseConfig();
-          const envConfig: vite.InlineConfig = {
-            plugins: [
-              wxtPlugins.extensionApiMock(wxtConfig),
-              wxtPlugins.removeEntrypointMainFunction(wxtConfig, path),
-            ],
-          };
-          const config = vite.mergeConfig(baseConfig, envConfig);
-          const server = await vite.createServer(config);
-          await server.listen();
-          const runtime = await vite.createViteRuntime(server, { hmr: false });
-          const module = await runtime.executeUrl(path);
-          await server.close();
-          return module.default;
-        }
         case 'vite-node': {
-          const baseConfig = await getBaseConfig();
+          const baseConfig = await getBaseConfig({
+            excludeAnalysisPlugin: true,
+          });
           // Disable dep optimization, as recommended by vite-node's README
           baseConfig.optimizeDeps ??= {};
           baseConfig.optimizeDeps.noDiscovery = true;

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

@@ -75,7 +75,7 @@ export async function generateTypesDir(
 async function getPathsDeclarationEntry(
   entrypoints: Entrypoint[],
 ): Promise<WxtDirFileEntry> {
-  const unions = entrypoints
+  const paths = entrypoints
     .map((entry) =>
       getEntrypointBundlePath(
         entry,
@@ -83,10 +83,14 @@ async function getPathsDeclarationEntry(
         isHtmlEntrypoint(entry) ? '.html' : '.js',
       ),
     )
-    .concat(await getPublicFiles())
+    .concat(await getPublicFiles());
+
+  await wxt.hooks.callHook('prepare:publicPaths', wxt, paths);
+
+  const unions = paths
     .map(normalizePath)
-    .map((path) => `    | "/${path}"`)
     .sort()
+    .map((path) => `    | "/${path}"`)
     .join('\n');
 
   const template = `// Generated by wxt

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

@@ -185,9 +185,8 @@ export async function resolveConfig(
     extensionApi,
     browserModule:
       extensionApi === 'chrome' ? 'wxt/browser/chrome' : 'wxt/browser',
-    experimental: defu(mergedConfig.experimental, {
-      entrypointImporter: 'jiti' as const,
-    }),
+    entrypointLoader: mergedConfig.entrypointLoader ?? 'vite-node',
+    experimental: defu(mergedConfig.experimental, {}),
     dev: {
       server: devServerConfig,
       reloadCommand,

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

@@ -298,9 +298,8 @@ export const fakeResolvedConfig = fakeObjectCreator<ResolvedConfig>(() => {
     alias: {},
     extensionApi: 'webextension-polyfill',
     browserModule: 'wxt/browser',
-    experimental: {
-      entrypointImporter: 'jiti',
-    },
+    entrypointLoader: 'vite-node',
+    experimental: {},
     dev: {
       reloadCommand: 'Alt+R',
     },

packages/wxt/src/storage.ts

@@ -9,6 +9,7 @@ import { Storage, browser } from 'wxt/browser';
 import { dequal } from 'dequal/lite';
 import { logger } from './sandbox/utils/logger';
 import { toArray } from './core/utils/arrays';
+import { Mutex } from 'async-mutex';
 
 export const storage = createStorage();
 
@@ -43,8 +44,8 @@ function createStorage(): WxtStorage {
     };
   };
   const getMetaKey = (key: string) => key + '$';
-  const getValueOrDefault = (value: any, defaultValue: any) =>
-    value ?? defaultValue ?? null;
+  const getValueOrFallback = (value: any, fallback: any) =>
+    value ?? fallback ?? null;
   const getMetaValue = (properties: any) =>
     typeof properties === 'object' && !Array.isArray(properties)
       ? properties
@@ -56,7 +57,7 @@ function createStorage(): WxtStorage {
     opts: GetItemOptions<any> | undefined,
   ) => {
     const res = await driver.getItem<any>(driverKey);
-    return getValueOrDefault(res, opts?.defaultValue);
+    return getValueOrFallback(res, opts?.fallback ?? opts?.defaultValue);
   };
   const getMeta = async (driver: WxtStorageDriver, driverKey: string) => {
     const metaKey = getMetaKey(driverKey);
@@ -148,9 +149,10 @@ function createStorage(): WxtStorage {
           const driverResults = await drivers[driverArea].getItems(keys);
           return driverResults.map((driverResult) => {
             const key = `${driverArea}:${driverResult.key}` as StorageItemKey;
-            const value = getValueOrDefault(
+            const opts = keyToOptsMap.get(key);
+            const value = getValueOrFallback(
               driverResult.value,
-              keyToOptsMap.get(key)?.defaultValue,
+              opts?.fallback ?? opts?.defaultValue,
             );
             return { key, value };
           });
@@ -302,15 +304,38 @@ function createStorage(): WxtStorage {
               logger.error(`Migration failed for ${key}`, err);
             });
 
-      const getDefaultValue = () => opts?.defaultValue ?? null;
+      const initMutex = new Mutex();
+
+      const getFallback = () => opts?.fallback ?? opts?.defaultValue ?? null;
+
+      const getOrInitValue = () =>
+        initMutex.runExclusive(async () => {
+          const value = await driver.getItem<any>(driverKey);
+          // Don't init value if it already exists or the init function isn't provided
+          if (value != null || opts?.init == null) return value;
+
+          const newValue = await opts.init();
+          await driver.setItem<any>(driverKey, newValue);
+          return newValue;
+        });
+
+      // Initialize the value once migrations have finished
+      migrationsDone.then(getOrInitValue);
 
       return {
         get defaultValue() {
-          return getDefaultValue();
+          return getFallback();
+        },
+        get fallback() {
+          return getFallback();
         },
         getValue: async () => {
           await migrationsDone;
-          return await getItem(driver, driverKey, opts);
+          if (opts?.init) {
+            return await getOrInitValue();
+          } else {
+            return await getItem(driver, driverKey, opts);
+          }
         },
         getMeta: async () => {
           await migrationsDone;
@@ -334,7 +359,7 @@ function createStorage(): WxtStorage {
         },
         watch: (cb) =>
           watch(driver, driverKey, (newValue, oldValue) =>
-            cb(newValue ?? getDefaultValue(), oldValue ?? getDefaultValue()),
+            cb(newValue ?? getFallback(), oldValue ?? getFallback()),
           ),
         migrate,
       };
@@ -567,7 +592,14 @@ export interface WxtStorageItem<
   TValue,
   TMetadata extends Record<string, unknown>,
 > {
+  /**
+   * @deprecated Renamed to `fallback`, use it instead.
+   */
   defaultValue: TValue;
+  /**
+   * The value provided by the `fallback` option.
+   */
+  fallback: TValue;
   /**
    * Get the latest value from storage.
    */
@@ -610,9 +642,13 @@ export type StorageItemKey = `${StorageArea}:${string}`;
 
 export interface GetItemOptions<T> {
   /**
-   * Value returned from `getValue` when it would otherwise return null.
+   * @deprecated Renamed to `fallback`, use it instead.
    */
   defaultValue?: T;
+  /**
+   * Default value returned when `getItem` would otherwise return `null`.
+   */
+  fallback?: T;
 }
 
 export interface RemoveItemOptions {
@@ -633,7 +669,21 @@ export interface SnapshotOptions {
 }
 
 export interface WxtStorageItemOptions<T> {
-  defaultValue: T;
+  /**
+   * @deprecated Renamed to `fallback`, use it instead.
+   */
+  defaultValue?: T;
+  /**
+   * Default value returned when `getValue` would otherwise return `null`.
+   */
+  fallback?: T;
+  /**
+   * If passed, a value in storage will be initialized immediately after
+   * defining the storage item. This function returns the value that will be
+   * saved to storage during the initialization process if a value doesn't
+   * already exist.
+   */
+  init?: () => T | Promise<T>;
   /**
    * Provide a version number for the storage item to enable migrations. When changing the version
    * in the future, migration functions will be ran on application startup.

packages/wxt/src/types.ts

@@ -299,25 +299,27 @@ export interface InlineConfig {
    * - `"chrome"` (unstable): Use the regular `chrome` (or `browser` for Firefox/Safari) globals provided by the browser. Types provided by [`@types/chrome`](https://www.npmjs.com/package/@types/chrome), make sure to install the package or types won't work.
    *
    * @default "webextension-polyfill"
+   * @since 0.19.0
    */
   extensionApi?: 'webextension-polyfill' | 'chrome';
+  /**
+   * @deprecated Will be removed in v0.20.0, please migrate to using `vite-node`, the new default.
+   *
+   * Method used to import entrypoint files during the build process to extract their options.
+   *
+   * - `"vite-node"` (default as of 0.19.0): Uses `vite-node` to import the entrypoints. Automatically includes vite config based on your wxt.config.ts file
+   * - `"jiti"`: Simplest and fastest, but doesn't allow using any imported variables outside the entrypoint's main function
+   *
+   * @see {@link https://wxt.dev/guide/go-further/entrypoint-importers.html|Entrypoint Importers}
+   *
+   * @default "vite-node"
+   * @since 0.19.0
+   */
+  entrypointLoader?: 'vite-node' | 'jiti';
   /**
    * Experimental settings - use with caution.
    */
-  experimental?: {
-    /**
-     * Method used to import entrypoint files during the build process to extract their options.
-     *
-     * - `"jiti"`: Simplest and fastest, but doesn't allow using any imported variables outside the entrypoint's main function
-     * - `"vite-runtime"` (unstable): Uses Vite 5.3's new runtime API to import the entrypoints. Automatically includes vite config based on your wxt.config.ts file
-     * - `"vite-node"` (unstable): Uses `vite-node` to import the entrypoints. Automatically includes vite config based on your wxt.config.ts file
-     *
-     * @see {@link https://wxt.dev/guide/go-further/entrypoint-side-effects.html|Entrypoint Side-effect Docs}
-     *
-     * @default "jiti"
-     */
-    entrypointImporter?: 'jiti' | 'vite-runtime' | 'vite-node';
-  };
+  experimental?: {};
   /**
    * Config effecting dev mode only.
    */
@@ -1050,6 +1052,20 @@ export interface WxtHooks {
    * })
    */
   'prepare:types': (wxt: Wxt, entries: WxtDirEntry[]) => HookResult;
+  /**
+   * Called before generating the list of public paths inside
+   * `.wxt/types/paths.d.ts`. Use this hook to add additional paths (relative
+   * to output directory) WXT doesn't add automatically.
+   *
+   * @param wxt The configured WXT object
+   * @param paths This list of paths TypeScript allows `browser.runtime.getURL` to be called with.
+   *
+   * @example
+   * wxt.hooks.hook('prepare:publicPaths', (wxt, paths) => {
+   *   paths.push('/icons/128.png');
+   * })
+   */
+  'prepare:publicPaths': (wxt: Wxt, paths: string[]) => HookResult;
   /**
    * Called before the build is started in both dev mode and build mode.
    *
@@ -1057,7 +1073,9 @@ export interface WxtHooks {
    */
   'build:before': (wxt: Wxt) => HookResult;
   /**
-   * Called once the build process has finished.
+   * Called once the build process has finished. You can add files to the build
+   * summary here by pushing to `output.publicAssets`.
+   *
    * @param wxt The configured WXT object
    * @param output The results of the build
    */
@@ -1193,9 +1211,8 @@ export interface ResolvedConfig {
   alias: Record<string, string>;
   extensionApi: 'webextension-polyfill' | 'chrome';
   browserModule: 'wxt/browser' | 'wxt/browser/chrome';
-  experimental: {
-    entrypointImporter: 'jiti' | 'vite-runtime' | 'vite-node';
-  };
+  entrypointLoader: 'vite-node' | 'jiti';
+  experimental: {};
   dev: {
     /** Only defined during dev command */
     server?: {

packages/wxt/typedoc.json

@@ -5,7 +5,6 @@
     "src/sandbox/index.ts",
     "src/browser/index.ts",
     "src/browser/chrome.ts",
-    "src/browser/webextension-polyfill.ts",
     "src/index.ts",
     "src/storage.ts",
     "src/modules.ts"

scripts/bump-package-version.ts

@@ -49,11 +49,17 @@ const versionChangelog = await generateMarkDown(commits, {
   from: prevTag,
   to: newTag,
 });
-const versionChangelogBody = versionChangelog
+let versionChangelogBody = versionChangelog
   .split('\n')
   .slice(1)
   .join('\n')
   .trim();
+if (bumpType === 'major') {
+  versionChangelogBody = versionChangelogBody.replace(
+    '[compare changes]',
+    `[⚠️ breaking changes](https://wxt.dev/guide/upgrade-guide/wxt) • [compare changes]`,
+  );
+}
 const { releases: prevReleases } = await fs
   .readFile(changelogPath, 'utf8')
   .then(parseChangelogMarkdown)