From 885f8f0b76d8daa635957edcd0783cb3b2a41ade Mon Sep 17 00:00:00 2001 From: Aaron Date: Sun, 26 Jul 2026 01:20:52 -0500 Subject: [PATCH] docs: Cleanup v0.21 migration guide --- docs/guide/resources/upgrading.md | 70 ++++++++++++++++--------------- 1 file changed, 36 insertions(+), 34 deletions(-) diff --git a/docs/guide/resources/upgrading.md b/docs/guide/resources/upgrading.md index 99974548..f840e6d2 100644 --- a/docs/guide/resources/upgrading.md +++ b/docs/guide/resources/upgrading.md @@ -35,53 +35,49 @@ Listed below are all the breaking changes you should address when upgrading to a 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. -## v0.20.0 → vX.Y.Z +## v0.20.0 → v0.21.0 -### Dev Browser Startup +### Opt Into Opening the Browser During Dev Mode -The package used to open the browser on startup has changed. Previously, WXT used `web-ext-run` as a direct dependency, but now we use `web-ext` as a peer dependency. +Before v0.20, `web-ext` was included as a dependency of WXT so that the browser could open automatically. However, it is quite heavy and not everyone uses this feature. -:::details - -`web-ext-run` was a light-weight fork of `web-ext`, but it was difficult to maintain and quickly got out-of-date compared to `web-ext`. - -::: - -In v0.20, how automatic startup is enabled/disabled has changed: - -- To continue opening the browser automatically, add `web-ext` as a dependency. No changes are required in your `web-ext.config.ts` files. +So in v0.21, `web-ext` is now an optional peer dependency - if it's installed, the browser will be opened automatically. If not, the feature is disabled. +- **To continue opening the browser automatically**: Install `web-ext` as a dependency ```sh pnpm add -D web-ext ``` +- **If you don't use this feature**: Don't install it and you can delete any `web-ext.config.ts` options and/or remove any `webExt.enabled: false` config -- To disable the browser automatically, **_DON'T_** add `web-ext` as a dependency. Additionally, you can remove any `web-ext.config.ts` files since they're not used if `web-ext` isn't installed: +You can still disable this behavior by setting `webExt.enabled: false` in your `wxt.config.ts` file or `web-ext.config.ts` file if the package is present. - ```sh - rm web-ext.config.ts +> Projects created with `wxt init` will include `web-ext` in their `package.json`, opting new projects into this feature by default. - # Keep the config in your home dir until all your projects have been upgraded - rm ~/web-ext.config.ts - ``` +### Template Variable Changes -### `{{version}}` Template Variable Changes +The `{{version}}` variable's value in the `artifactTemplate` and `sourcesTemplate` config has changed: -The `{{version}}` template var in `artifactTemplate` and `sourcesTemplate` used to equal `manifest.version_name ?? manifest.version`. It now equals `{{manifest.version}}`. - -If you have a custom template for one of these options, replace `{{version}}` with `{{versionName}}` to maintain the same behavior. +- Old: `manifest.version_name ?? manifest.version` +- New: `manifest.version` If you don't customize `artifactTemplate` or `sourcesTemplate`, this does not effect you. -## Shadow root UIs no longer include a full HTML document +If you have a custom template for one of these options, replace `{{version}}` with `{{versionName}}` to maintain the same behavior as before. -`@webext-core/isolated-element` was upgraded to v2. This release changes the internal structure of the shadow DOM, simplifying it from a full `` document to just a `div`: +For more info on the difference between `manifest.version_name` and `manifest.version`, see the [Manifest Config docs](/guide/essentials/config/manifest#version-and-version-name). + +### `createShadowRoot` DOM Changes + +`@webext-core/isolated-element` was upgraded to v3. This release changes the internal structure of the shadow root's DOM, simplifying it from a full `` document to just a `div`: :::code-group -```[Before] +```html [Before] - + ...your app @@ -89,18 +85,16 @@ If you don't customize `artifactTemplate` or `sourcesTemplate`, this does not ef ``` -```[After] - -
- ...your app -
+```html [After] + +
...your app
``` ::: -Most modern CSS frameworks support the simplified "fragment", but if yours doesn't, please open an issue. You'll know if something broke because your content script UI will be unstyled. - -If you roll your own CSS, make sure your base styles are applied to shadow root hosts like so: +Historically, CSS frameworks haven't had good support for shadow roots, we used to need the full `` structure for styles to be applied correctly. But that has change this past few years, frameworks have started to include the `host:` selector alongside `root:`, which is required for base styles to be applied to the shadow root's host element: ```css :root { /* [!code --] */ @@ -109,6 +103,14 @@ If you roll your own CSS, make sure your base styles are applied to shadow root } ``` +If you use `createShadowRootUi`, see if your UI looks the same after this update without any changes. + +If the styles are broken, you can continue using the full `` structure by installing the v1 of `@webext-core/isolated-element` - WXT will respect whatever version of the package is listed in your `package.json`. + +```sh +pnpm add @webext-core/isolated-element@^1 +``` + ## New Deprecations in v0.20 Deprecated APIs will be removed in the next major release.