You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/guide/resources/upgrading.md
+193Lines changed: 193 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,3 +1,7 @@
1
+
---
2
+
outline: deep
3
+
---
4
+
1
5
# Upgrading WXT
2
6
3
7
## Overview
@@ -12,6 +16,195 @@ Listed below are all the breaking changes you should address when upgrading to a
12
16
13
17
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.
14
18
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
+
:::tip
24
+
Read through all the changes once before making any code changes.
25
+
:::
26
+
27
+
### `webextension-polyfill` Removed
28
+
29
+
WXT no longer uses the `webextension-polyfill` internally and `wxt/browser` uses the `chrome`/`browser` globals provided by the browser.
30
+
31
+
To upgrade, you have two options:
32
+
33
+
1.**Stop using the polyfill**
34
+
- No changes required, this is the default behavior of v0.20. Your extension will likely continue to work, but do some manual testing to confirm.
35
+
2.**Continue using the polyfill**
36
+
- Install the polyfill, types (if you use typescript), and WXT's [new polyfill module](https://www.npmjs.com/package/@wxt-dev/webextension-polyfill):
37
+
```sh
38
+
pnpm i webextension-polyfill
39
+
pnpm i -D @types/webextension-polyfill @wxt-dev/webextension-polyfill
40
+
```
41
+
- Add the WXT module to your config:
42
+
```ts
43
+
// wxt.config.ts
44
+
export default defineConfig({
45
+
modules: ['@wxt-dev/webextension-polyfill'],
46
+
});
47
+
```
48
+
49
+
Additionally, the `extensionApi` config has been removed. Remove it from your `wxt.config.ts` file if present:
50
+
51
+
```ts
52
+
// wxt.config.ts
53
+
export default defineConfig({
54
+
extensionApi: 'chrome', // [!code --]
55
+
});
56
+
```
57
+
58
+
### `public/` and `modules/` Directories Moved
59
+
60
+
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.
61
+
62
+
- If you follow the default folder structure, you don't need to make any changes.
63
+
- If you set a custom `srcDir`, you have two options:
64
+
1. Keep the folders in the same place and update your project config:
65
+
```ts
66
+
// wxt.config.ts
67
+
export default defineConfig({
68
+
srcDir: 'src',
69
+
publicDir: 'src/public', // [!code ++]
70
+
modulesDir: 'src/modules', // [!code ++]
71
+
});
72
+
```
73
+
2. Move the your `public/` and `modules/` directories to the project root:
74
+
```diff
75
+
<root>/
76
+
+ modules/
77
+
+ public/
78
+
src/
79
+
components/
80
+
entrypoints/
81
+
- modules/
82
+
- public/
83
+
utils/
84
+
wxt.config.ts
85
+
```
86
+
87
+
### Import Path Changes
88
+
89
+
The APIs exported by `wxt/sandbox`, `wxt/client`, or `wxt/storage` have moved to `wxt/utils/*`.
90
+
91
+
To upgrade, replace these imports with the new `#imports` module:
92
+
93
+
```ts
94
+
import { storage } from 'wxt/storage'; // [!code --]
95
+
import { defineContentScript } from 'wxt/sandbox'; // [!code --]
96
+
import { ContentScriptContext, useAppConfig } from 'wxt/client'; // [!code --]
97
+
import { storage } from '#imports'; // [!code ++]
98
+
import { defineContentScript } from '#imports'; // [!code ++]
99
+
import { ContentScriptContext, useAppConfig } from '#imports'; // [!code ++]
100
+
```
101
+
102
+
You can combine the imports into a single import statement, but it's easier to just find/replace each statement.
103
+
104
+
:::tip
105
+
Before types will work, you'll need to run `wxt prepare` after installing v0.20 to generate the new TypeScript declarations.
106
+
:::
107
+
108
+
Read more about the new `#imports` module in the [blog post](/blog/2024-12-06-using-imports-module).
109
+
110
+
### `createShadowRootUi` CSS Changes
111
+
112
+
WXT now resets styles inherited from the webpage (`visibility`, `color`, `font-size`, etc.) by setting `all: initial` inside the shadow root.
113
+
114
+
If you use `createShadowRootUi`:
115
+
116
+
1. Double check that your UI looks the same as before.
117
+
2. If you have any manual CSS resets to override a page style, you can remove them:
118
+
119
+
<!-- prettier-ignore -->
120
+
```css
121
+
/* entrypoints/reddit.content/style.css */
122
+
body { /* [!code --] */
123
+
/* Override Reddit's default "hidden" visibility on elements */ /* [!code --] */
124
+
visibility: visible !important; /* [!code --] */
125
+
} /* [!code --] */
126
+
```
127
+
128
+
:::warning
129
+
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`.
130
+
:::
131
+
132
+
If you run into problems with the new behavior, you can disable it and continue using your current CSS:
133
+
134
+
```ts
135
+
const ui = await createShadowRootUi({
136
+
inheritStyles: true, // [!code ++]
137
+
// ...
138
+
});
139
+
```
140
+
141
+
### Default Output Directories Changed
142
+
143
+
The default value for [`outDirTemplate`](/api/reference/wxt/interfaces/InlineConfig#outdirtemplate) has changed. Now, different build modes are output to different directories:
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:
161
+
162
+
1. The `runner` option has been renamed to `webExt`:
163
+
```ts
164
+
// wxt.config.ts
165
+
export default defineConfig({
166
+
runner: { // [!code --]
167
+
webExt: { // [!code ++]
168
+
startUrls: ["https://wxt.dev"],
169
+
},
170
+
});
171
+
```
172
+
2. `defineRunnerConfig` has been renamed to `defineWebExtConfig`:
173
+
```ts
174
+
// web-ext.config.ts
175
+
import { defineRunnerConfig } from 'wxt'; // [!code --]
176
+
import { defineWebExtConfig } from 'wxt'; // [!code ++]
177
+
```
178
+
3. The `ExtensionRunnerConfig` type has been renamed to `WebExtConfig`
179
+
```ts
180
+
import type { ExtensionRunnerConfig } from 'wxt'; // [!code --]
181
+
import type { WebExtConfig } from 'wxt'; // [!code ++]
182
+
```
183
+
184
+
### Load Config as ESM
185
+
186
+
`wxt.config.ts` and `web-ext.config.ts` are now loaded as ESM modules. Previously, they were loaded as CJS.
187
+
188
+
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`.
189
+
190
+
### Deprecated APIs Removed
191
+
192
+
- `entrypointLoader` option: WXT now uses `vite-node`for importing entrypoints during the build process.
193
+
> This was deprecated in v0.19.0, see the [v0.19 section](#v0-18-5-rarr-v0-19-0) for migration steps.
194
+
- `transformManifest` option: Use the `build:manifestGenerated` hook to transform the manifest instead:
0 commit comments