chore(release): @wxt-dev/analytics v0.5.0

Co-authored-by: Aaron <aaronklinker1@gmail.com>

docs/guide/resources/upgrading.md

@@ -26,65 +26,72 @@ Read through all the changes once before making any code changes.
 
 ### `webextension-polyfill` Removed
 
-WXT no longer uses the `webextension-polyfill` internally and `wxt/browser` uses the `chrome`/`browser` globals provided by the browser.
+WXT's `browser` no longer uses the `webextension-polyfill`!
+
+:::details Why?
+See https://github.com/wxt-dev/wxt/issues/784
+:::
 
 To upgrade, you have two options:
 
-1. **Stop using the polyfill**
-   - Replace any manual imports from `wxt/browser/chrome` with `wxt/browser`
-2. **Continue using the polyfill**
-   - Install the polyfill and WXT's [new polyfill module](https://www.npmjs.com/package/@wxt-dev/webextension-polyfill):
+1. **Stop using the polyfill** - No changes necessary, though you may want to do some manual testing to make sure everything continues to work. None of the early testers of this feature reported any runtime issues once they stopped using the polyfill.
+   - If you're already using `extensionApi: "chrome"`, then you don't need to test anything! You're already using the same `browser` object v0.20 provides by default.
+2. **Continue using the polyfill** - If you want to keep using the polyfill, you can! One less thing to worry about during this upgrade.
+   - Install `webextension-polyfill` and WXT's [new polyfill module](https://www.npmjs.com/package/@wxt-dev/webextension-polyfill):
      ```sh
      pnpm i webextension-polyfill @wxt-dev/webextension-polyfill
      ```
    - Add the WXT module to your config:
-     ```ts
-     // wxt.config.ts
+     ```ts [wxt.config.ts]
      export default defineConfig({
        modules: ['@wxt-dev/webextension-polyfill'],
      });
      ```
 
-Regardless of your choice, the `extensionApi` config has been removed. Remove it from your `wxt.config.ts` file if present:
+The new `browser` object (and types) is backed by WXT's new package: [`@wxt-dev/browser`](https://www.npmjs.com/package/@wxt-dev/browser). This package continues WXT's mission of providing useful packages for the whole community. Just like [`@wxt-dev/storage`](https://www.npmjs.com/package/@wxt-dev/storage), [`@wxt-dev/i18n`](https://www.npmjs.com/package/@wxt-dev/i18n), [`@wxt-dev/analytics`](https://www.npmjs.com/package/@wxt-dev/analytics), it is designed to be easy to use in any web extension project, not just those using WXT, and provides a consistent API across all browsers and manifest versions.
 
-```ts
-// wxt.config.ts
+### `extensionApi` Config Removed
+
+The `extensionApi` config has been removed. Before, this config provided a way to opt into using the new `browser` object prior to v0.20.0.
+
+Remove it from your `wxt.config.ts` file if present:
+
+```ts [wxt.config.ts]
 export default defineConfig({
   extensionApi: 'chrome', // [!code --]
 });
 ```
 
-Additionally, extension API types have changed. `wxt/browser` now uses types from `@types/chrome` instead of `@types/webextension-polyfill`. You will have to migrate any type imports to use `@types/chrome`'s namespace approach:
+### Extension API Type Changes
+
+With the new `browser` introduced in v0.20, how you access types has changed. WXT now provides types based on `@types/chrome` instead of `@types/webextension-polyfill`.
+
+These types are more up-to-date with MV3 APIs, contain less bugs, are better organized, and don't have any auto-generated names.
+
+To access types, use the new `Browser` namespace from `wxt/browser`:
 
 <!-- prettier-ignore -->
 ```ts
 import type { Runtime } from 'wxt/browser'; // [!code --]
-import { browser } from 'wxt/browser'; // [!code ++]
+import type { Browser } from 'wxt/browser'; // [!code ++]
 
 function getMessageSenderUrl(sender: Runtime.MessageSender): string { // [!code --]
-function getMessageSenderUrl(sender: browser.runtime.MessageSender): string { // [!code ++]
+function getMessageSenderUrl(sender: Browser.runtime.MessageSender): string { // [!code ++]
   // ...
 }
 ```
 
-`@types/chrome` are more up-to-date, contain less bugs, and don't have any auto-generated names. So even if you continue to use the polyfill, you will need to update your types to use these types.
+> If you use auto-imports, `Browser` will be available without manually importing it.
+
+Not all type names will be the same as what `@types/webextension-polyfill` provides. You'll have to find the new type names by looking at the types of the `browser.*` API's you use.
 
 ### `public/` and `modules/` Directories Moved
 
-The default location for the `public/` and `modules/` directories have changed to better align with standards set by other frameworks (Nuxt, Next, Astro, etc). Now, each path is relative to the project's root directory.
+The default location for the `public/` and `modules/` directories have changed to better align with standards set by other frameworks (Nuxt, Next, Astro, etc). Now, each path is relative to the project's **root directory**, not the src directory.
 
 - If you follow the default folder structure, you don't need to make any changes.
 - If you set a custom `srcDir`, you have two options:
-  1.  Keep the folders in the same place and update your project config:
-      ```ts
-      // wxt.config.ts
-      export default defineConfig({
-        srcDir: 'src',
-        publicDir: 'src/public', // [!code ++]
-        modulesDir: 'src/modules', // [!code ++]
-      });
-      ```
-  2.  Move the your `public/` and `modules/` directories to the project root:
+  1.  Move the your `public/` and `modules/` directories to the project root:
       ```diff
       <root>/
       +   modules/
@@ -97,12 +104,32 @@ The default location for the `public/` and `modules/` directories have changed t
               utils/
           wxt.config.ts
       ```
+  2.  Keep the folders in the same place and update your project config:
+      ```ts [wxt.config.ts]
+      export default defineConfig({
+        srcDir: 'src',
+        publicDir: 'src/public', // [!code ++]
+        modulesDir: 'src/modules', // [!code ++]
+      });
+      ```
 
-### Import Path Changes
+### Import Path Changes and `#imports`
 
-The APIs exported by `wxt/sandbox`, `wxt/client`, or `wxt/storage` have moved to `wxt/utils/*`.
+The APIs exported by `wxt/sandbox`, `wxt/client`, or `wxt/storage` have moved to individual exports under the `wxt/utils/*` path.
 
-To upgrade, replace these imports with the new `#imports` module:
+:::details Why?
+As WXT grows and more utilities are added, any helper with side-effects will not be tree-shaken out of your final bundle.
+
+This can cause problems because not every API used by these side-effects is available in every type of entrypoint. Some APIs can only be used in the background, sandboxed pages can't use any extension API, etc. This was leading to JS throwing errors in the top-level scope, preventing your code from running.
+
+Splitting each util into it's own module solves this problem, making sure you're only importing APIs and side-effects into entrypoints they can run in.
+:::
+
+Refer to the updated [API Reference](/api/reference/) to see the list of new import paths.
+
+However, you don't need to memorize or learn the new import paths! v0.20 introduces a new virtual module, `#imports`, that abstracts all this away from developers. See the [blog post](/blog/2024-12-06-using-imports-module) for more details about how this module works.
+
+So to upgrade, just replace any imports from `wxt/storage`, `wxt/client`, and `wxt/sandbox` with an import to the new `#imports` module:
 
 ```ts
 import { storage } from 'wxt/storage'; // [!code --]
@@ -115,33 +142,44 @@ import { ContentScriptContext, useAppConfig } from '#imports'; // [!code ++]
 
 You can combine the imports into a single import statement, but it's easier to just find/replace each statement.
 
+```ts
+import { storage } from 'wxt/storage'; // [!code --]
+import { defineContentScript } from 'wxt/sandbox'; // [!code --]
+import { ContentScriptContext, useAppConfig } from 'wxt/client'; // [!code --]
+import {
+  // [!code ++]
+  storage, // [!code ++]
+  defineContentScript, // [!code ++]
+  ContentScriptContext, // [!code ++]
+  useAppConfig, // [!code ++]
+} from '#imports'; // [!code ++]
+```
+
 :::tip
 Before types will work, you'll need to run `wxt prepare` after installing v0.20 to generate the new TypeScript declarations.
 :::
 
-Read more about the new `#imports` module in the [blog post](/blog/2024-12-06-using-imports-module).
-
 ### `createShadowRootUi` CSS Changes
 
 WXT now resets styles inherited from the webpage (`visibility`, `color`, `font-size`, etc.) by setting `all: initial` inside the shadow root.
 
+:::warning
+This doesn't effect `rem` units. You should continue using `postcss-rem-to-px` or an equivalent library if the webpage sets the HTML element's `font-size`.
+:::
+
 If you use `createShadowRootUi`:
 
-1. Double check that your UI looks the same as before.
-2. If you have any manual CSS resets to override a page style, you can remove them:
+1. Remove any manual CSS overrides that reset the style of specific websites. For example:
 
    <!-- prettier-ignore -->
-   ```css
-   /* entrypoints/reddit.content/style.css */
+   ```css [entrypoints/reddit.content/style.css]
    body { /* [!code --] */
      /* Override Reddit's default "hidden" visibility on elements */ /* [!code --] */
      visibility: visible !important; /* [!code --] */
    } /* [!code --] */
    ```
 
-:::warning
-This doesn't effect `rem` units. You should continue using `postcss-rem-to-px` or an equivalent library if the webpage sets the HTML element's `font-size`.
-:::
+2. Double check that your UI looks the same as before.
 
 If you run into problems with the new behavior, you can disable it and continue using your current CSS:
 
@@ -154,70 +192,23 @@ const ui = await createShadowRootUi({
 
 ### Default Output Directories Changed
 
-The default value for [`outDirTemplate`](/api/reference/wxt/interfaces/InlineConfig#outdirtemplate) has changed. Now, different build modes are output to different directories:
+The default value for the [`outDirTemplate`](/api/reference/wxt/interfaces/InlineConfig#outdirtemplate) config has changed. Now, different build modes are output to different directories:
 
-- `--mode production`: `.output/chrome-mv3` (unchanged)
-- `--mode development`: `.output/chrome-mv3-dev` (`-dev` suffix)
-- `--mode custom`: `.output/chrome-mv3-custom` (`-[mode]` suffix)
+- `--mode production` &rarr; `.output/chrome-mv3`: Production builds are unchanged
+- `--mode development` &rarr; `.output/chrome-mv3-dev`: Dev mode now has a `-dev` suffix so it doesn't overwrite production builds
+- `--mode custom` &rarr; `.output/chrome-mv3-custom`: Other custom modes end with a `-[mode]` suffix
 
-To revert and use the old behavior, writing all output to the same directory, set `outDirTemplate` option:
+To use the old behavior, writing all output to the same directory, set the `outDirTemplate` option:
 
-```ts
-// wxt.config.ts
+```ts [wxt.config.ts]
 export default defineConfig({
   outDirTemplate: '{{browser}}-mv{{manifestVersion}}', // [!code ++]
 });
 ```
 
-If you've loaded the extension into your browser manually for development, uninstall and re-install it from the new dev output directory.
-
-### Internal Auto-import Options Changed
-
-Only relevant if you refer to WXT's built-in `preset`s in the `imports` config in a module or hooks.
-
-Instead of using `package` to auto-detect APIs to auto-import, WXT now uses `from` and `imports` to manually list APIs that are imported.
-
-```ts
-presets: [
-  { package: "wxt/browser" }, // [!code --]
-  { from: "wxt/browser": imports: ["browser"] }, // [!code --]
-  // ...
-]
-```
-
-See [PR #1315 `packages/wxt/src/core/resolve-config.ts` changes](https://github.com/wxt-dev/wxt/pull/1315/files#diff-ff0465c3a486d3ba187204149a25fc8f632c44d65da356dc04c0f2b268a71506) for exact changes made.
-
-### `runner` APIs Renamed
-
-To improve consistency with the `web-ext.config.ts` file, the "runner" APIs have been renamed. You can continue using the old names, but they have been deprecated and will be removed in a future version:
-
-1. The `runner` option has been renamed to `webExt`:
-   ```ts
-   // wxt.config.ts
-   export default defineConfig({
-     runner: { // [!code --]
-     webExt: { // [!code ++]
-       startUrls: ["https://wxt.dev"],
-     },
-   });
-   ```
-2. `defineRunnerConfig` has been renamed to `defineWebExtConfig`:
-   ```ts
-   // web-ext.config.ts
-   import { defineRunnerConfig } from 'wxt'; // [!code --]
-   import { defineWebExtConfig } from 'wxt'; // [!code ++]
-   ```
-3. The `ExtensionRunnerConfig` type has been renamed to `WebExtConfig`
-   ```ts
-   import type { ExtensionRunnerConfig } from 'wxt'; // [!code --]
-   import type { WebExtConfig } from 'wxt'; // [!code ++]
-   ```
-
-### Load Config as ESM
-
-`wxt.config.ts` and `web-ext.config.ts` are now loaded as ESM modules. Previously, they were loaded as CJS.
-
-If you're using any CJS APIs, like `__filename` or `__dirname`, replace them with their ESM counterparts, like `import.meta.filename` or `import.meta.dirname`.
+:::warning
+If you've previously loaded the extension into your browser manually for development, you'll need to uninstall and re-install it from the new dev output directory.
+:::
 
 ### Deprecated APIs Removed
 
@@ -225,8 +216,7 @@ If you're using any CJS APIs, like `__filename` or `__dirname`, replace them wit
   > This was deprecated in v0.19.0, see the [v0.19 section](#v0-18-5-rarr-v0-19-0) for migration steps.
 - `transformManifest` option: Use the `build:manifestGenerated` hook to transform the manifest instead:
   <!-- prettier-ignore -->
-  ```ts
-  // wxt.config.ts
+  ```ts [wxt.config.ts]
   export default defineConfig({
     transformManifest(manifest) { // [!code --]
     hooks: { // [!code ++]
@@ -237,6 +227,32 @@ If you're using any CJS APIs, like `__filename` or `__dirname`, replace them wit
   });
   ```
 
+### New Deprecations
+
+#### `runner` APIs Renamed
+
+To improve consistency with the `web-ext.config.ts` filename, the "runner" API and config options have been renamed. You can continue using the old names, but they have been deprecated and will be removed in a future version:
+
+1. The `runner` option has been renamed to `webExt`:
+   ```ts [wxt.config.ts]
+   export default defineConfig({
+     runner: { // [!code --]
+     webExt: { // [!code ++]
+       startUrls: ["https://wxt.dev"],
+     },
+   });
+   ```
+2. `defineRunnerConfig` has been renamed to `defineWebExtConfig`:
+   ```ts [web-ext.config.ts]
+   import { defineRunnerConfig } from 'wxt'; // [!code --]
+   import { defineWebExtConfig } from 'wxt'; // [!code ++]
+   ```
+3. The `ExtensionRunnerConfig` type has been renamed to `WebExtConfig`
+   ```ts
+   import type { ExtensionRunnerConfig } from 'wxt'; // [!code --]
+   import type { WebExtConfig } from 'wxt'; // [!code ++]
+   ```
+
 ## v0.18.5 &rarr; v0.19.0
 
 ### `vite-node` Entrypoint Loader
@@ -244,7 +260,7 @@ If you're using any CJS APIs, like `__filename` or `__dirname`, replace them wit
 The default entrypoint loader has changed to `vite-node`. If you use any NPM packages that depend on the `webextension-polyfill`, you need to add them to Vite's `ssr.noExternal` option:
 
 <!-- prettier-ignore -->
-```ts
+```ts [wxt.config.ts]
 export default defineConfig({
   vite: () => ({ // [!code ++]
     ssr: { // [!code ++]
@@ -292,7 +308,7 @@ Basically, you can now import and do things outside the `main` function of the e
 
 To continue using the old approach, add the following to your `wxt.config.ts` file:
 
-```ts
+```ts [wxt.config.ts]
 export default defineConfig({
   entrypointLoader: 'jiti', // [!code ++]
 });

packages/analytics/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+## v0.5.0
+
+[⚠️ breaking changes](https://wxt.dev/guide/upgrade-guide/wxt) • [compare changes](https://github.com/wxt-dev/wxt/compare/analytics-v0.4.1...analytics-v0.5.0)
+
+### 🚀 Enhancements
+
+- Analytics module ([5217279](https://github.com/wxt-dev/wxt/commit/5217279))
+- New `@wxt-dev/analytics` package ([#790](https://github.com/wxt-dev/wxt/pull/790))
+
+### 🩹 Fixes
+
+- ⚠️  Update min WXT version to 0.20 ([2e8baf0](https://github.com/wxt-dev/wxt/commit/2e8baf0))
+
+### 🏡 Chore
+
+- **release:** Analytics-v0.4.0 ([2faba91](https://github.com/wxt-dev/wxt/commit/2faba91))
+- **release:** Analytics-v0.4.1 ([1509809](https://github.com/wxt-dev/wxt/commit/1509809))
+
+#### ⚠️ Breaking Changes
+
+- ⚠️  Update min WXT version to 0.20 ([2e8baf0](https://github.com/wxt-dev/wxt/commit/2e8baf0))
+
+### ❤️ Contributors
+
+- Aaron ([@aklinker1](https://github.com/aklinker1))

packages/analytics/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wxt-dev/analytics",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Add analytics to your web extension",
   "repository": {
     "type": "git",

packages/wxt-demo/package.json

@@ -22,7 +22,6 @@
     "react-dom": "catalog:"
   },
   "devDependencies": {
-    "@types/chrome": "catalog:",
     "@types/react": "catalog:",
     "@types/react-dom": "catalog:",
     "@wxt-dev/auto-icons": "workspace:*",

packages/wxt/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Changelog
 
+## v0.20.0
+
+[⚠️ breaking changes](https://wxt.dev/guide/upgrade-guide/wxt) • [compare changes](https://github.com/wxt-dev/wxt/compare/wxt-v0.19.29...wxt-v0.20.0)
+
+### 🚀 Enhancements
+
+- ⚠️  Remove `webextension-polyfill` ([#1084](https://github.com/wxt-dev/wxt/pull/1084))
+- ⚠️  Individual exports and introduce the `#imports` module ([#1258](https://github.com/wxt-dev/wxt/pull/1258))
+- ⚠️  Reset inherited styles inside shadow root ([#1269](https://github.com/wxt-dev/wxt/pull/1269))
+- ⚠️  Auto-import types ([#1315](https://github.com/wxt-dev/wxt/pull/1315))
+
+### 🩹 Fixes
+
+- ⚠️  Add suffix to non-production output directories ([#1086](https://github.com/wxt-dev/wxt/pull/1086))
+- ⚠️  Remove deprecated `jiti` entrypoint loader ([#1087](https://github.com/wxt-dev/wxt/pull/1087))
+- ⚠️  Rename `runner` to `webExt` ([#1180](https://github.com/wxt-dev/wxt/pull/1180))
+- ⚠️  Remove `transformManfiest` option ([#1181](https://github.com/wxt-dev/wxt/pull/1181))
+- Remove unnecessary `VITE_CJS_IGNORE_WARNING` flag ([b0ef178](https://github.com/wxt-dev/wxt/commit/b0ef178))
+- ⚠️  Make `publicDir` and `modulesDir` relative to project root ([#1216](https://github.com/wxt-dev/wxt/pull/1216))
+- ⚠️  Move `wxt/storage` to `wxt/utils/storage` ([#1271](https://github.com/wxt-dev/wxt/pull/1271))
+- Add back `ExtensionRunnerConfig` as deprecated ([#1311](https://github.com/wxt-dev/wxt/pull/1311))
+- Missing browser in shadow-root file ([#1317](https://github.com/wxt-dev/wxt/pull/1317))
+
+### 📖 Documentation
+
+- Fix api reference for `wxt/utils/storage` ([99b5076](https://github.com/wxt-dev/wxt/commit/99b5076))
+- Fix broken links ([82d8024](https://github.com/wxt-dev/wxt/commit/82d8024))
+
+### 🏡 Chore
+
+- Fix type errors ([aad17c8](https://github.com/wxt-dev/wxt/commit/aad17c8))
+- Remove duplicate test ([e54df0a](https://github.com/wxt-dev/wxt/commit/e54df0a))
+
+#### ⚠️ Breaking Changes
+
+- ⚠️  Remove `webextension-polyfill` ([#1084](https://github.com/wxt-dev/wxt/pull/1084))
+- ⚠️  Individual exports and introduce the `#imports` module ([#1258](https://github.com/wxt-dev/wxt/pull/1258))
+- ⚠️  Reset inherited styles inside shadow root ([#1269](https://github.com/wxt-dev/wxt/pull/1269))
+- ⚠️  Auto-import types ([#1315](https://github.com/wxt-dev/wxt/pull/1315))
+- ⚠️  Add suffix to non-production output directories ([#1086](https://github.com/wxt-dev/wxt/pull/1086))
+- ⚠️  Remove deprecated `jiti` entrypoint loader ([#1087](https://github.com/wxt-dev/wxt/pull/1087))
+- ⚠️  Rename `runner` to `webExt` ([#1180](https://github.com/wxt-dev/wxt/pull/1180))
+- ⚠️  Remove `transformManfiest` option ([#1181](https://github.com/wxt-dev/wxt/pull/1181))
+- ⚠️  Make `publicDir` and `modulesDir` relative to project root ([#1216](https://github.com/wxt-dev/wxt/pull/1216))
+- ⚠️  Move `wxt/storage` to `wxt/utils/storage` ([#1271](https://github.com/wxt-dev/wxt/pull/1271))
+
+### ❤️ Contributors
+
+- Aaron ([@aklinker1](https://github.com/aklinker1))
+- 1natsu ([@1natsu172](https://github.com/1natsu172))
+
 ## v0.19.29
 
 [compare changes](https://github.com/wxt-dev/wxt/compare/wxt-v0.19.28...wxt-v0.19.29)

packages/wxt/package.json

@@ -1,7 +1,7 @@
 {
   "name": "wxt",
   "type": "module",
-  "version": "0.19.29",
+  "version": "0.20.0",
   "description": "⚡ Next-gen Web Extension Framework",
   "license": "MIT",
   "scripts": {

pnpm-lock.yaml

@@ -916,9 +916,6 @@ importers:
         specifier: 'catalog:'
         version: 19.0.0(react@19.0.0)
     devDependencies:
-      '@types/chrome':
-        specifier: 'catalog:'
-        version: 0.0.280
       '@types/react':
         specifier: 'catalog:'
         version: 19.0.1

templates/react/package.json

@@ -19,7 +19,6 @@
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@types/chrome": "^0.0.280",
     "@types/react": "^19.0.1",
     "@types/react-dom": "^19.0.2",
     "@wxt-dev/module-react": "^1.1.2",

templates/solid/package.json

@@ -18,7 +18,6 @@
     "solid-js": "^1.9.3"
   },
   "devDependencies": {
-    "@types/chrome": "^0.0.280",
     "@wxt-dev/module-solid": "^1.1.2",
     "typescript": "^5.6.3",
     "wxt": "^0.19.29"

templates/svelte/package.json

@@ -16,7 +16,6 @@
   },
   "devDependencies": {
     "@tsconfig/svelte": "^5.0.4",
-    "@types/chrome": "^0.0.280",
     "@wxt-dev/module-svelte": "^2.0.0",
     "svelte": "^5.1.16",
     "svelte-check": "^4.0.7",

templates/vanilla/package.json

@@ -15,7 +15,6 @@
     "postinstall": "wxt prepare"
   },
   "devDependencies": {
-    "@types/chrome": "^0.0.280",
     "typescript": "^5.6.3",
     "wxt": "^0.19.29"
   }

templates/vue/package.json

@@ -18,7 +18,6 @@
     "vue": "^3.5.12"
   },
   "devDependencies": {
-    "@types/chrome": "^0.0.280",
     "@wxt-dev/module-vue": "^1.0.1",
     "typescript": "5.6.3",
     "vue-tsc": "^2.1.10",