From b58fb02016e37bd051ac17a85dd3c1579d8501c6 Mon Sep 17 00:00:00 2001 From: Aaron Klinker Date: Sat, 7 Oct 2023 10:49:31 -0500 Subject: [PATCH] docs: Add migration guides --- docs/.vitepress/config.ts | 6 ++++ docs/guide/installation.md | 2 +- docs/guide/migrate-to-wxt.md | 57 ++++++++++++++++++++++++++++++++++++ docs/guide/testing.md | 2 +- 4 files changed, 65 insertions(+), 2 deletions(-) create mode 100644 docs/guide/migrate-to-wxt.md diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index eb2dafa1..9dd4265e 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -80,6 +80,12 @@ export default defineConfig({ { text: 'Development', link: '/guide/development.md' }, { text: 'Testing', link: '/guide/testing.md' }, { text: 'Vite', link: '/guide/vite.md' }, + ], + }, + { + text: 'Other', + items: [ + { text: 'Migrate to WXT', link: '/guide/migrate-to-wxt.md' }, { text: 'Compare', link: '/guide/compare.md' }, ], }, diff --git a/docs/guide/installation.md b/docs/guide/installation.md index c0f1d77d..4197a6d4 100644 --- a/docs/guide/installation.md +++ b/docs/guide/installation.md @@ -1,6 +1,6 @@ # Installation -Bootstrap a new project, start from scratch, or migrate an existing project. +Bootstrap a new project, start from scratch, or [migrate an existing project](/guide/migrate-to-wxt). ## Bootstrap Project diff --git a/docs/guide/migrate-to-wxt.md b/docs/guide/migrate-to-wxt.md new file mode 100644 index 00000000..ecbdd553 --- /dev/null +++ b/docs/guide/migrate-to-wxt.md @@ -0,0 +1,57 @@ +--- +outline: deep +--- + +# Migrate to WXT + +> If you have problems migrating to WXT, feel free to ask for help in GitHub by [starting a discussion](https://github.com/wxt-dev/wxt/discussions/new?category=q-a)! + +## Overview + +Always start by generating a new vanilla project and merging it into your project one file at a time. + +```sh +cd path/to/your/project +pnpx wxt@latest init example-wxt --template vanilla +``` + +In general, you'll need to: + + Install `wxt`
+ Update/create `package.json` scripts to use `wxt` (don't forget about `postinstall`)
+ Move entrypoints into `entrypoints/` directory
+ Move assets into either the `assets/` or `public/` directories
+ Move manifest.json content into `wxt.config.ts`
+ Convert custom import syntax to be compatible with Vite
+ Add a default export to JS entrypoints
+ Use the `browser` global instead of `chrome`
+ Compare final `manifest.json` files, making sure permissions and host permissions are unchanged
+ Extension output by `wxt build` works the same way as before the migration
+ +Every project is different, so there's no one-solution-fits-all to migrating your project. Just make sure `wxt dev` runs, `wxt build` results in a working extension, and the list of permissions in the `manifest.json` hasn't changed. If all that looks good, you've finished migrating your extension! + +## Popular Tools/Frameworks + +Here's specific steps for other popuplar frameworks/build tools. + +### `vite-plugin-web-extension` + +Since you're already using Vite, it's a simple refactor. + +1. Install `wxt` +2. Move and refactor your entrypoints to WXT's style (with a default export) +3. Update package.json scripts to use `wxt` +4. Add `"postinstall": "wxt prepare"` script +5. Move the `manifest.json` into `wxt.config.ts` +6. Move any custom settings from `vite.config.ts` into `wxt.config.ts`'s +7. Compare `dist/manifest.json` to `.output/*/manifest.json`, they should have the same content as before. If not, tweak your entrypoints and config to get as close as possible. + +### `plasmo` + +1. Install `wxt` +2. Move entrypoints into `entrypoints/` directory, merging the named exports used to configure your JS entrypoints into WXT's default export +3. Move public `assets/*` into the `public/` directory +4. If you use CSUI, migrate to WXT's `createContentScriptUi` +5. Convert Plasmo's custom import resolutions to Vite's +6. If importing remote code via a URL, add a `url:` prefix so it works with WXT +7. Compare your output `manifest.json` files from before the migration to after the migration. They should have the same content. If not, tweak your entrypoints and config to get as close as possible. diff --git a/docs/guide/testing.md b/docs/guide/testing.md index 13172199..470854ea 100644 --- a/docs/guide/testing.md +++ b/docs/guide/testing.md @@ -60,7 +60,7 @@ Eventually, WXT will provide utilities for setting up these auto-imports. For no Not all testing frameworks can handle auto-imports. If your framework or setup is not listed below, it may be easiest to disable auto-imports. -To setup auto-imports manually, use [`unplugin-auto-import`](https://www.npmjs.com/package/unplugin-auto-import). It uses the same tool, `unimport`, as WXT and will result in compatiple auto-imports. `unplugin-auto-import` supports lots of different tools (vite, webpage, esbuild, rollup, etc). You can try and integrate it into your build process. +To setup auto-imports manually, use [`unplugin-auto-import`](https://www.npmjs.com/package/unplugin-auto-import). It uses the same tool, `unimport`, as WXT and will result in compatiple auto-imports. `unplugin-auto-import` supports lots of different tools (vite, webpack, esbuild, rollup, etc). You can try and integrate it into your build process. ### Vitest (Recommended)