Skip to content

Commit ed69155

Browse files
aklinker1aklinker1
committed
docs: Add upgrade guide for v0.20
1 parent 406766b commit ed69155

File tree

2 files changed

+239
-1
lines changed

2 files changed

+239
-1
lines changed

‎docs/guide/essentials/config/auto-imports.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -115,4 +115,4 @@ import {
115115

116116
To learn more about how the `#imports` module works, read the [related blog post](/blog/2024-12-06-using-imports-module).
117117

118-
If you've disabled auto-imports, you can use `#imports` to import all of WXT's APIs from a simple place.
118+
If you've disabled auto-imports, you should still use `#imports` to import all of WXT's APIs from a single place.

‎docs/guide/resources/upgrading.md‎

Lines changed: 238 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
---
2+
outline: deep
3+
---
4+
15
# Upgrading WXT
26

37
## Overview
@@ -12,6 +16,240 @@ Listed below are all the breaking changes you should address when upgrading to a
1216

1317
Currently, WXT is in pre-release. This means changes to the second digit, `v0.X`, are considered major and have breaking changes. Once v1 is released, only major version bumps will have breaking changes.
1418

19+
## v0.19.0 → v0.20.0
20+
21+
v0.20 is a big release! There are lots of breaking changes because this version is intended to be a release candidate for v1.0. If all goes well, v1.0 will be released with no additional breaking changes.
22+
23+
:::warning
24+
Read through all the changes before updating your extension.
25+
:::
26+
27+
### `webextension-polyfill` Removed
28+
29+
Since MV3 and the deprecation of MV2 by Chrome in June 2024, the `webextension-polyfill` doesn't really serve a purpose anymore. In WXT, all it did was polyfill the promise-based API for Chrome MV2.
30+
31+
As such, WXT no longer supports the polyfill and the `extensionApi` config has been removed.
32+
33+
```ts
34+
// wxt.config.ts
35+
export default defineConfig({
36+
extensionApi: 'chrome', // [!code --]
37+
});
38+
```
39+
40+
If you were using `extensionApi: 'chrome'`, this is the default now! Remove it from your config and you're good to go.
41+
42+
If you weren't using `extensionApi: 'chrome'`, `wxt/browser` has changed. Now, it re-exports the `chrome` global for Chromium or the `browser` global for Firefox and Safari. However, most of the time no code changes are required, the API behaves the same at runtime. Continue importing `browser` from WXT:
43+
44+
```ts
45+
import { browser } from 'wxt/browser';
46+
```
47+
48+
#### Extension API Types
49+
50+
Type definitions are now provided by `@types/chrome` instead of `@types/webextension-polyfill`. `@types/chrome` is more up-to-date with the latest MV3 APIs, while still supporting MV2.
51+
52+
If you're importing types, they are not named exports anymore. Instead, types are accessed directly off the `browser` variable.
53+
54+
```ts
55+
import { browser, type Runtime } from 'wxt/browser'; // [!code --]
56+
import { browser } from 'wxt/browser'; // [!code ++]
57+
58+
function onInstalled(details: Runtime.OnInstalledDetailsType) { // [!code --]
59+
function onInstalled(details: browser.runtime.InstalledDetails) { // [!code ++]
60+
// ...
61+
}
62+
63+
browser.runtime.onInstalled.addListener(onInstalled);
64+
```
65+
66+
:::warning
67+
Be aware the `@types/chrome` and `@types/webextension-polyfill` use different names and may have different types for some APIs. If you get a type-error, fix it.
68+
:::
69+
70+
### `public/` and `modules/` Directories Moved
71+
72+
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 root directory.
73+
74+
- `<srcDir>/public` &rarr; `<root>/public`
75+
- `<srcDir>/modules` &rarr; `<root>/modules`
76+
77+
If you follow the default folder structure, you don't need to make any changes.
78+
79+
If you set a custom `srcDir`, you have two options:
80+
81+
1. Keep the folders in the same place and update your project config:
82+
```ts
83+
// wxt.config.ts
84+
export default defineConfig({
85+
srcDir: 'src',
86+
publicDir: 'src/public', // [!code ++]
87+
modulesDir: 'src/modules', // [!code ++]
88+
});
89+
```
90+
2. Move the your `public/` and `modules/` directories to the project root:
91+
```diff
92+
<root>/
93+
+ modules/
94+
+ public/
95+
src/
96+
components/
97+
entrypoints/
98+
- modules/
99+
- public/
100+
utils/
101+
wxt.config.ts
102+
```
103+
104+
### Import Path Changes
105+
106+
If you are manually importing `wxt/sandbox`, `wxt/client`, or `wxt/storage`, their APIs have been moved. Now, each API gets it's own submodule inside `wxt/utils/*`. This improves treeshaking, reduces bundle size, and better prepares WXT for adding more utilities in the future.
107+
108+
:::details New import paths
109+
110+
<!-- prettier-ignore -->
111+
```ts
112+
import { useAppConfig } from 'wxt/utils/app-config';
113+
import { ContentScriptContext } from 'wxt/utils/content-script-context';
114+
import { createIframeUi } from 'wxt/utils/content-script-ui/iframe';
115+
import { createIntegratedUi } from 'wxt/utils/content-script-ui/integrated';
116+
import { createShadowRootUi } from 'wxt/utils/content-script-ui/shadow-root';
117+
import { defineAppConfig } from 'wxt/utils/define-app-config';
118+
import { defineBackground } from 'wxt/utils/define-background';
119+
import { defineContentScript } from 'wxt/utils/define-content-script';
120+
import { defineUnlistedScript } from 'wxt/utils/define-unlisted-script';
121+
import { defineWxtPlugin } from 'wxt/utils/define-wxt-plugin';
122+
import { injectScript } from 'wxt/utils/inject-script';
123+
import { InvalidMatchPattern, MatchPattern } from 'wxt/utils/match-patterns';
124+
import { MigrationError, storage } from 'wxt/utils/storage';
125+
```
126+
127+
:::
128+
129+
However, that's a lot of new paths to learn. That why WXT is also introducing the new [`#imports` module](/guide/essentials/config/auto-imports#explicit-imports-imports)! Instead of using the new import paths, just import the APIs from `#imports` instead:
130+
131+
<!-- prettier-ignore -->
132+
```ts
133+
import { storage } from 'wxt/storage'; // [!code --]
134+
import { defineContentScript } from 'wxt/sandbox'; // [!code --]
135+
import { ContentScriptContext, useAppConfig } from 'wxt/client'; // [!code --]
136+
import { // [!code ++]
137+
storage, // [!code ++]
138+
defineContentScript, // [!code ++]
139+
ContentScriptContext, // [!code ++]
140+
useAppConfig, // [!code ++]
141+
} from '#imports'; // [!code ++]
142+
```
143+
144+
> If you want to see where all the efer to the [API reference](/api/reference/wxt) or your project's `.wxt/types/imports-module.d.ts` file if you're curious.
145+
146+
When bundled, any imports from `#imports` will be broken up and replace with individual imports to the new submodules.
147+
148+
:::tip
149+
Before types will work, you'll need to run `wxt prepare` to generate the TypeScript declarations.
150+
:::
151+
152+
Read more about the new `#imports` module in the [blog post](/blog/2024-12-06-using-imports-module).
153+
154+
### `createShadowRootUi` CSS Changes
155+
156+
WXT now blocks inherited styles from the webpage (`visibility`, `color`, `font-size`, etc.) by setting `all: initial` inside the shadow root.
157+
158+
If you use `createShadowRootUI`, double check that your UIs are styled properly. If you have any manual CSS resets to override a page style, you can remove them:
159+
160+
<!-- prettier-ignore -->
161+
```css
162+
/* entrypoints/reddit.content/styles.css */
163+
body { /* [!code --] */
164+
/* Override Reddit's default "hidden" visibility */ /* [!code --] */
165+
visibility: visible !important; /* [!code --] */
166+
} /* [!code --] */
167+
```
168+
169+
> 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`.
170+
171+
If you run into problems with the new behavior, you can disable it and continue using your current CSS:
172+
173+
```ts
174+
const ui = await createShadowRootUi({
175+
inheritStyles: true, // [!code ++]
176+
// ...
177+
});
178+
```
179+
180+
### Default Build Output Directories Changed
181+
182+
The build mode is now apart of the output directory:
183+
184+
- `--mode production` → `.output/chrome-mv3` (unchanged)
185+
- `--mode development` → `.output/chrome-mv3-dev` (dev mode is now output with the "-dev" suffix)
186+
- `--mode other` → `.output/chrome-mv3-other` (all other build modes are output with the "-[mode]" suffix)
187+
188+
To revert back to the old behavior and output all builds to the same directory, set the `outDirTemplate` option:
189+
190+
```ts
191+
// wxt.config.ts
192+
export default defineConfig({
193+
outDirTemplate: '{{browser}}-mv{{manifestVersion}}', // [!code ++]
194+
});
195+
```
196+
197+
### Renamed `runner` to `webExt`
198+
199+
Several deprecations related to configuring `web-ext`, the package used to start the browser with your extension installed:
200+
201+
1. (REQUIRED) `ExtensionRunnerConfig` type has been renamed to `WebExtConfig`
202+
```ts
203+
import type { ExtensionRunnerConfig } from 'wxt'; // [!code --]
204+
import type { WebExtConfig } from 'wxt'; // [!code ++]
205+
```
206+
2. (Optional) `runner` &rarr; `webExt`:
207+
```ts
208+
// wxt.config.ts
209+
export default defineConfig({
210+
runner: { // [!code --]
211+
webExt: { // [!code ++]
212+
startUrls: ["https://wxt.dev"],
213+
},
214+
});
215+
```
216+
3. (Optional) `defineRunnerConfig` &rarr; `defineWebExtConfig`
217+
```ts
218+
// web-ext.config.ts
219+
import { defineRunnerConfig } from 'wxt'; // [!code --]
220+
import { defineWebExtConfig } from 'wxt'; // [!code ++]
221+
```
222+
223+
> The optional changes will be deprecated in the future.
224+
225+
This improves the consistency with the config's filename, `web-ext.config.ts`.
226+
227+
If you continue using `runner` or `defineRunnerConfig`, WXT will log an warning, but it will still work until the next major version.
228+
229+
### Load Config as ESM
230+
231+
Upgraded `c12` to v2 and now `wxt.config.ts` and `web-ext.config.ts` are loaded as true ESM modules. 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`.
232+
233+
### Deprecated APIs Removed
234+
235+
- `entrypointLoader` option: WXT now uses `vite-node` for importing entrypoints during the build process.
236+
> This was deprecated in v0.19.0, see the [v0.19 section](#v0-18-5-rarr-v0-19-0) for migration steps.
237+
- `transformManifest` option: Use the `build:manifestGenerated` hook to transform the manifest instead:
238+
<!-- prettier-ignore -->
239+
```ts
240+
// wxt.config.ts
241+
export default defineConfig({
242+
transformManifest(manifest) { // [!code --]
243+
// ... // [!code --]
244+
}, // [!code --]
245+
hooks: { // [!code ++]
246+
'build:manifestGenerated': (_, manifest) => { // [!code ++]
247+
// ... // [!code ++]
248+
}, // [!code ++]
249+
}, // [!code ++]
250+
});
251+
```
252+
15253
## v0.18.5 &rarr; v0.19.0
16254
17255
### `vite-node` Entrypoint Loader

0 commit comments

Comments
 (0)