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
@@ -20,15 +20,33 @@ Currently, WXT is in pre-release. This means changes to the second digit, `v0.X`
20
20
21
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
22
23
-
:::warning
24
-
Read through all the changes before updating your extension.
23
+
:::tip
24
+
Read through all the changes once before making any code changes.
25
25
:::
26
26
27
27
### `webextension-polyfill` Removed
28
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.
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
+
```
30
48
31
-
As such, WXT no longer supports the polyfill and the `extensionApi` config has been removed.
49
+
Additionally, the `extensionApi` config has been removed. Remove it from your `wxt.config.ts` file if present:
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.
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
58
### `public/` and `modules/` Directories Moved
71
59
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` → `<root>/public`
75
-
- `<srcDir>/modules` → `<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
-
exportdefaultdefineConfig({
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
-
```
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
+
```
103
86
104
87
### Import Path Changes
105
88
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.
89
+
The APIs exported by `wxt/sandbox`, `wxt/client`, or `wxt/storage`have moved to `wxt/utils/*`.
107
90
108
-
:::details New import paths
91
+
To upgrade, replace these imports with the new `#imports` module:
109
92
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
93
```ts
133
94
import { storage } from 'wxt/storage'; // [!code --]
134
95
import { defineContentScript } from 'wxt/sandbox'; // [!code --]
135
96
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 ++]
97
+
import { storage } from '#imports'; // [!code ++]
98
+
import { defineContentScript } from '#imports'; // [!code ++]
99
+
import { ContentScriptContext, useAppConfig } from '#imports'; // [!code ++]
142
100
```
143
101
144
-
> If you want to see where all the imports are moved to, refer to the [API reference](/api/reference/wxt/) or your project's `.wxt/types/imports-module.d.ts` file.
145
-
146
-
When bundled, any imports from `#imports` will be broken up and replace with individual imports to the new submodules.
102
+
You can combine the imports into a single import statement, but it's easier to just find/replace each statement.
147
103
148
104
:::tip
149
-
Before types will work, you'll need to run `wxt prepare` to generate the TypeScript declarations.
105
+
Before types will work, you'll need to run `wxt prepare`after installing v0.20 to generate the new TypeScript declarations.
150
106
:::
151
107
152
108
Read more about the new `#imports` module in the [blog post](/blog/2024-12-06-using-imports-module).
153
109
154
110
### `createShadowRootUi` CSS Changes
155
111
156
-
WXT now blocks inherited styles from the webpage (`visibility`, `color`, `font-size`, etc.) by setting `all: initial` inside the shadow root.
112
+
WXT now resets styles inherited from the webpage (`visibility`, `color`, `font-size`, etc.) by setting `all: initial` inside the shadow root.
157
113
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:
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
+
```
168
127
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`.
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
+
:::
170
131
171
132
If you run into problems with the new behavior, you can disable it and continue using your current CSS:
The build mode is now apart of the output directory:
143
+
The default value for [`outDirTemplate`](/api/reference/wxt/interfaces/InlineConfig#outdirtemplate) has changed. Now, different build modes are output to different directories:
Several deprecations related to configuring`web-ext`, the package used to start the browser with your extension installed:
160
+
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:
200
161
201
-
1. (REQUIRED) `ExtensionRunnerConfig` type has been renamed to `WebExtConfig`
2. `defineRunnerConfig` has been renamed to `defineWebExtConfig`:
217
173
```ts
218
174
// web-ext.config.ts
219
175
import { defineRunnerConfig } from 'wxt'; // [!code --]
220
176
import { defineWebExtConfig } from 'wxt'; // [!code ++]
221
177
```
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.
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
+
```
228
183
229
184
### Load Config as ESM
230
185
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`.
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`.
232
189
233
190
### Deprecated APIs Removed
234
191
@@ -240,13 +197,11 @@ Upgraded `c12` to v2 and now `wxt.config.ts` and `web-ext.config.ts` are loaded
0 commit comments