diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index c2ae4b34..5f779dc7 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -60,7 +60,7 @@ representative at an online or offline event. Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at -aaronklinker1@gmail.com. +. All complaints will be reviewed and investigated promptly and fairly. All community leaders are obligated to respect the privacy and security of the @@ -116,7 +116,7 @@ the community. This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0, available at -https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. +. Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity). @@ -124,5 +124,5 @@ enforcement ladder](https://github.com/mozilla/diversity). [homepage]: https://www.contributor-covenant.org For answers to common questions about this code of conduct, see the FAQ at -https://www.contributor-covenant.org/faq. Translations are available at -https://www.contributor-covenant.org/translations. +. Translations are available at +. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a2db1d16..8f70ece8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -156,7 +156,7 @@ Configuration is in [`taze.config.ts`](./taze.config.ts). ## Install Unreleased Versions -This repo uses https://pkg.pr.new to publish versions of all it's packages for almost every commit. You can install them via: +This repo uses to publish versions of all it's packages for almost every commit. You can install them via: ```sh npm i https://pkg.pr.new/[package-name]@[ref] @@ -177,7 +177,7 @@ npm i https://pkg.pr.new/@wxt-dev/module-react@426f907 ## Blog Posts -Anyone is welcome to submit a blog post on https://wxt.dev/blog! +Anyone is welcome to submit a blog post on ! > [!NOTE] > Before starting on a blog post, please message Aaron on Discord or start a discussion on GitHub to get permission to write about a topic, but most topics are welcome: Major version updates, tutorials, etc. diff --git a/README.md b/README.md index 106d3a66..8dfd7404 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ ## Demo -https://github.com/wxt-dev/wxt/assets/10101283/4d678939-1bdb-495c-9c36-3aa281d84c94 + ## Quick Start diff --git a/docs/guide/essentials/config/hooks.md b/docs/guide/essentials/config/hooks.md index f66beafc..e735ff4a 100644 --- a/docs/guide/essentials/config/hooks.md +++ b/docs/guide/essentials/config/hooks.md @@ -50,7 +50,9 @@ Changing execution order is simple: 📄 0.my-module.ts 📄 1.another-module.ts ``` + - If you need to run an NPM module after user modules, just make it a user module and prefix the filename with a number! + ```ts // modules/2.i18n.ts export { default } from '@wxt-dev/i18n/module'; diff --git a/docs/guide/essentials/config/manifest.md b/docs/guide/essentials/config/manifest.md index 77a594f2..2a1ab0ae 100644 --- a/docs/guide/essentials/config/manifest.md +++ b/docs/guide/essentials/config/manifest.md @@ -235,6 +235,7 @@ If you want to use the `activeTab` permission or the `browser.action.onClicked` 1. Delete the [Popup entrypoint](/guide/essentials/entrypoints#popup) if it exists 2. Add the `action` key to your manifest: + ```ts export default defineConfig({ manifest: { diff --git a/docs/guide/essentials/content-scripts.md b/docs/guide/essentials/content-scripts.md index eefbd62c..42244e99 100644 --- a/docs/guide/essentials/content-scripts.md +++ b/docs/guide/essentials/content-scripts.md @@ -76,6 +76,7 @@ To create a standalone content script that only includes a CSS file: 1. Create the CSS file: `entrypoints/example.content.css` 2. Use the `build:manifestGenerated` hook to add the content script to the manifest: + ```ts [wxt.config.ts] export default defineConfig({ hooks: { @@ -459,6 +460,7 @@ If you don't need to run your UI in the same frame as the content script, you ca WXT provides a helper function, [`createIframeUi`](/api/reference/wxt/utils/content-script-ui/iframe/functions/createIframeUi), which simplifies setting up the IFrame. 1. Create an HTML page that will be loaded into your IFrame: + ```html @@ -473,7 +475,9 @@ WXT provides a helper function, [`createIframeUi`](/api/reference/wxt/utils/cont ``` + 1. Add the page to the manifest's `web_accessible_resources`: + ```ts [wxt.config.ts] export default defineConfig({ manifest: { @@ -486,6 +490,7 @@ WXT provides a helper function, [`createIframeUi`](/api/reference/wxt/utils/cont }, }); ``` + 1. Create and mount the IFrame: ```ts diff --git a/docs/guide/essentials/entrypoints.md b/docs/guide/essentials/entrypoints.md index 78e3f7b2..258fb2ce 100644 --- a/docs/guide/essentials/entrypoints.md +++ b/docs/guide/essentials/entrypoints.md @@ -580,7 +580,7 @@ body { } ``` -Follow Vite's guide to setup your preprocessor of choice: https://vitejs.dev/guide/features.html#css-pre-processors +Follow Vite's guide to setup your preprocessor of choice: CSS entrypoints are always unlisted. To add CSS to a content script, see the [Content Script](/guide/essentials/content-scripts#css) docs. diff --git a/docs/guide/essentials/i18n.md b/docs/guide/essentials/i18n.md index e505f6cc..f672852b 100644 --- a/docs/guide/essentials/i18n.md +++ b/docs/guide/essentials/i18n.md @@ -9,6 +9,7 @@ This page discusses how to setup internationalization using the vanilla `browser ## Usage 1. Add `default_locale` to your manifest: + ```ts export default defineConfig({ manifest: { @@ -16,6 +17,7 @@ This page discusses how to setup internationalization using the vanilla `browser }, }); ``` + 2. Create `messages.json` files in the `public/` directory: @@ -41,9 +43,11 @@ This page discusses how to setup internationalization using the vanilla `browser ``` 3. Get the translation: + ```ts browser.i18n.getMessage('helloWorld'); ``` + 4. _Optional_: Add translations for extension name and description: ```json diff --git a/docs/guide/essentials/target-different-browsers.md b/docs/guide/essentials/target-different-browsers.md index c854a976..3abb8357 100644 --- a/docs/guide/essentials/target-different-browsers.md +++ b/docs/guide/essentials/target-different-browsers.md @@ -62,6 +62,7 @@ Here are some examples: ``` - HTML file only built for all targets other than `chrome`: + ```html diff --git a/docs/guide/essentials/unit-testing.md b/docs/guide/essentials/unit-testing.md index a0e2bb21..9e12c8bb 100644 --- a/docs/guide/essentials/unit-testing.md +++ b/docs/guide/essentials/unit-testing.md @@ -105,4 +105,4 @@ To use a different framework, you will likely have to disable auto-imports, setu It is possible to do, but will require a bit more setup. Refer to Vitest's setup for an example of how to setup a test environment: -https://github.com/wxt-dev/wxt/blob/main/packages/wxt/src/testing/wxt-vitest-plugin.ts + diff --git a/docs/guide/essentials/wxt-modules.md b/docs/guide/essentials/wxt-modules.md index d359d969..cb475074 100644 --- a/docs/guide/essentials/wxt-modules.md +++ b/docs/guide/essentials/wxt-modules.md @@ -9,18 +9,23 @@ WXT provides a "module system" that let's you run code at different steps in the There are two ways to add a module to your project: 1. **NPM**: install an NPM package, like [`@wxt-dev/auto-icons`](https://www.npmjs.com/package/@wxt-dev/auto-icons) and add it to your config: + ```ts [wxt.config.ts] export default defineConfig({ modules: ['@wxt-dev/auto-icons'], }); ``` + > Searching for ["wxt module"](https://www.npmjs.com/search?q=wxt%20module) on NPM is a good way to find published WXT modules. + 2. **Local**: add a file to your project's `modules/` directory: + ``` / modules/ my-module.ts ``` + > To learn more about writing your own modules, read the [Writing Modules](/guide/essentials/wxt-modules) docs. ## Module Options diff --git a/docs/guide/installation.md b/docs/guide/installation.md index edd8d549..0f673eaf 100644 --- a/docs/guide/installation.md +++ b/docs/guide/installation.md @@ -45,47 +45,63 @@ Once you've run the `dev` command, continue to [Next Steps](#next-steps)! 1. Create a new project :::code-group + ```sh [PNPM] cd my-project pnpm init ``` + ```sh [Bun] cd my-project bun init ``` + ```sh [NPM] cd my-project npm init ``` + ```sh [Yarn] cd my-project yarn init ``` + ::: + 2. Install WXT: :::code-group + ```sh [PNPM] pnpm i -D wxt ``` + ```sh [Bun] bun i -D wxt ``` + ```sh [NPM] npm i -D wxt ``` + ```sh [Yarn] yarn add --dev wxt ``` + ::: + 3. Add an entrypoint, `my-project/entrypoints/background.ts`: :::code-group + ```ts export default defineBackground(() => { console.log('Hello world!'); }); ``` + ::: + 4. Add scripts to your `package.json`: + ```json [package.json] { "scripts": { @@ -99,20 +115,26 @@ Once you've run the `dev` command, continue to [Next Steps](#next-steps)! } } ``` + 5. Run your extension in dev mode :::code-group + ```sh [PNPM] pnpm dev ``` + ```sh [Bun] bun run dev ``` + ```sh [NPM] npm run dev ``` + ```sh [Yarn] yarn dev ``` + ::: WXT will automatically open a browser window with your extension installed. diff --git a/docs/guide/introduction.md b/docs/guide/introduction.md index 6b490a98..29841bd2 100644 --- a/docs/guide/introduction.md +++ b/docs/guide/introduction.md @@ -1,4 +1,4 @@ -# Welcome to WXT! +# Welcome to WXT WXT is a modern, open-source framework for building web extensions. Inspired by Nuxt, its goals are to: diff --git a/docs/guide/resources/faq.md b/docs/guide/resources/faq.md index a468b21f..6d11f8f1 100644 --- a/docs/guide/resources/faq.md +++ b/docs/guide/resources/faq.md @@ -20,13 +20,13 @@ await chrome.scripting.getRegisteredContentScripts(); ## How do I disable opening the browser automatically during development? -See https://wxt.dev/guide/essentials/config/browser-startup.html#disable-opening-browser +See ## How do I stay logged into a website during development? -See https://wxt.dev/guide/essentials/config/browser-startup.html#persist-data +See -## My component library doesn't work in content scripts! +## My component library doesn't work in content scripts This is usually caused by one of two things (or both) when using `createShadowRootUi`: @@ -167,11 +167,11 @@ Both issues have the same fix: tell the library to put elements inside the `Shad ## Is there an LLM trained on WXT's docs that I chat with? -Yes! There's a "Ask AI" button in the bottom right of the page, try it out! Or visit https://knowledge.wxt.dev/ for a fullscreen experience. +Yes! There's a "Ask AI" button in the bottom right of the page, try it out! Or visit for a fullscreen experience. Additionally, if you want to train your own model or provide context to your editor, you can use the LLM knowledge files hosted by the site: -https://wxt.dev/knowledge/index.json + You don't need to crawl the entire website, these files already contain all the relevant docs for training a LLM on WXT. But feel free to crawl it and generate your own files if you want! diff --git a/docs/guide/resources/upgrading.md b/docs/guide/resources/upgrading.md index cb951463..ef963bdd 100644 --- a/docs/guide/resources/upgrading.md +++ b/docs/guide/resources/upgrading.md @@ -9,14 +9,18 @@ outline: deep To upgrade WXT to the latest major version: 1. Install it, skipping scripts so `wxt prepare` doesn't run - it will probably throw an error after a major version change (we'll run it later). + ```sh pnpm i wxt@latest --ignore-scripts ``` + 2. Follow the upgrade steps below to fix any breaking changes. 3. Run `wxt prepare`. It should succeed and type errors will go away afterwords. + ```sh pnpm wxt prepare ``` + 4. Manually test to make sure both dev mode and production builds work. For minor or patch version updates, there are no special steps. Just update it with your package manager: @@ -44,7 +48,7 @@ Read through all the changes once before updating your code. WXT's `browser` no longer uses the `webextension-polyfill`! :::details Why? -See https://github.com/wxt-dev/wxt/issues/784 +See ::: To upgrade, you have two options: @@ -52,11 +56,15 @@ To upgrade, you have two options: 1. **Stop using the polyfill** - No changes necessary, though you may want to do some manual testing to make sure everything continues to work. None of the early testers of this feature reported any runtime issues once they stopped using the polyfill. - If you're already using `extensionApi: "chrome"`, then you don't need to test anything! You're already using the same `browser` object v0.20 provides by default. 2. **Continue using the polyfill** - If you want to keep using the polyfill, you can! One less thing to worry about during this upgrade. + - Install `webextension-polyfill` and WXT's [new polyfill module](https://www.npmjs.com/package/@wxt-dev/webextension-polyfill): + ```sh pnpm i webextension-polyfill @wxt-dev/webextension-polyfill ``` + - Add the WXT module to your config: + ```ts [wxt.config.ts] export default defineConfig({ modules: ['@wxt-dev/webextension-polyfill'], @@ -106,9 +114,10 @@ The default location for the `public/` and `modules/` directories have changed t - If you follow the default folder structure, you don't need to make any changes. - If you set a custom `srcDir`, you have two options: - 1. Move the your `public/` and `modules/` directories to the project root: - - ```html + + 1. Move the your `public/` and `modules/` directories to the project root: + + ```html 📂 {rootDir}/ 📁 modules/ 📁 public/ @@ -121,14 +130,16 @@ The default location for the `public/` and `modules/` directories have changed t 📄 app.config.ts 📄 wxt.config.ts ``` - 2. Keep the folders in the same place and update your project config: - ```ts [wxt.config.ts] - export default defineConfig({ - srcDir: 'src', - publicDir: 'src/public', // [!code ++] - modulesDir: 'src/modules', // [!code ++] - }); - ``` + + 2. Keep the folders in the same place and update your project config: + + ```ts [wxt.config.ts] + export default defineConfig({ + srcDir: 'src', + publicDir: 'src/public', // [!code ++] + modulesDir: 'src/modules', // [!code ++] + }); + ``` ### Import Path Changes and `#imports` @@ -251,6 +262,7 @@ If you've previously loaded the extension into your browser manually for develop To improve consistency with the `web-ext.config.ts` filename, the "runner" API and config options have been renamed. You can continue using the old names, but they have been deprecated and will be removed in a future version: 1. The `runner` option has been renamed to `webExt`: + ```ts [wxt.config.ts] export default defineConfig({ runner: { // [!code --] @@ -259,12 +271,16 @@ To improve consistency with the `web-ext.config.ts` filename, the "runner" API a }, }); ``` + 2. `defineRunnerConfig` has been renamed to `defineWebExtConfig`: + ```ts [web-ext.config.ts] import { defineRunnerConfig } from 'wxt'; // [!code --] import { defineWebExtConfig } from 'wxt'; // [!code ++] ``` + 3. The `ExtensionRunnerConfig` type has been renamed to `WebExtConfig` + ```ts import type { ExtensionRunnerConfig } from 'wxt'; // [!code --] import type { WebExtConfig } from 'wxt'; // [!code ++] @@ -342,7 +358,7 @@ WXT no longer ships with Common JS support. If you're using CJS, here's your mig 1. Add [`"type": "module"`](https://nodejs.org/api/packages.html#type) to your `package.json`. 2. Change the file extension of any `.js` files that use CJS syntax to `.cjs`, or update them to use EMS syntax. -Vite also provides steps for migrating to ESM. Check them out for more details: https://vitejs.dev/guide/migration#deprecate-cjs-node-api +Vite also provides steps for migrating to ESM. Check them out for more details: ## v0.18.0 → v0.18.5 @@ -357,11 +373,13 @@ If you already have `/modules` or `/Modules` directory, `wxt pre You have two options: 1. [Recommended] Keep your files where they are and tell WXT to look in a different folder: + ```ts [wxt.config.ts] export default defineConfig({ modulesDir: 'wxt-modules', // defaults to "modules" }); ``` + 2. Rename your `modules` directory to something else. ## v0.17.0 → v0.18.0 @@ -445,7 +463,7 @@ export default defineConfig({ ### Renamed Undocumented Constants -Renamed undocumented constants for detecting the build config at runtime in [#380](https://github.com/wxt-dev/wxt/pull/380). Now documented here: https://wxt.dev/guide/multiple-browsers.html#runtime +Renamed undocumented constants for detecting the build config at runtime in [#380](https://github.com/wxt-dev/wxt/pull/380). Now documented here: - `__BROWSER__` → `import.meta.env.BROWSER` - `__COMMAND__` → `import.meta.env.COMMAND` @@ -472,7 +490,7 @@ Renamed undocumented constants for detecting the build config at runtime in [#38 ### New `wxt/storage` APIs -`wxt/storage` no longer relies on [`unstorage`](https://www.npmjs.com/package/unstorage). Some `unstorage` APIs, like `prefixStorage`, have been removed, while others, like `snapshot`, are methods on the new `storage` object. Most of the standard usage remains the same. See https://wxt.dev/guide/storage and https://wxt.dev/api/reference/wxt/storage/ for more details ([#300](https://github.com/wxt-dev/wxt/pull/300)) +`wxt/storage` no longer relies on [`unstorage`](https://www.npmjs.com/package/unstorage). Some `unstorage` APIs, like `prefixStorage`, have been removed, while others, like `snapshot`, are methods on the new `storage` object. Most of the standard usage remains the same. See and for more details ([#300](https://github.com/wxt-dev/wxt/pull/300)) ## v0.11.0 → v0.12.0 @@ -482,6 +500,7 @@ Renamed undocumented constants for detecting the build config at runtime in [#38 - If you use auto-imports, no changes are required. - If you have disabled auto-imports, you'll need to manually update your import statements: + ```ts import { defineBackground, defineContentScript } from 'wxt/client'; // [!code --] import { defineBackground, defineContentScript } from 'wxt/sandbox'; // [!code ++] diff --git a/packages/analytics/README.md b/packages/analytics/README.md index d0355f0d..1cb90f69 100644 --- a/packages/analytics/README.md +++ b/packages/analytics/README.md @@ -10,15 +10,19 @@ Report analytics events from your web extension extension. ## Install With WXT 1. Install the NPM package: + ```bash pnpm i @wxt-dev/analytics ``` + 2. In your `wxt.config.ts`, add the WXT module: + ```ts export default defineConfig({ modules: ['@wxt-dev/analytics/module'], }); ``` + 3. In your `/app.config.ts`, add a provider: ```ts @@ -49,9 +53,11 @@ Report analytics events from your web extension extension. ## Install Without WXT 1. Install the NPM package: + ```bash pnpm i @wxt-dev/analytics ``` + 2. Create an `analytics` instance: ```ts @@ -66,10 +72,12 @@ Report analytics events from your web extension extension. ``` 3. Import your analytics module in the background to initialize the message listener: + ```ts // background.ts import './utils/analytics'; ``` + 4. Then use your `analytics` instance to report events: ```ts diff --git a/packages/runner/README.md b/packages/runner/README.md index 3bfc2144..a38f30c1 100644 --- a/packages/runner/README.md +++ b/packages/runner/README.md @@ -92,7 +92,7 @@ await run({ These presets configure different flags for different operating systems when spawning the browser process. -If you want to customize your data persistence beyond what these presets define, [you can override the browser flags yourself](#Arguments) to configure persistence. +If you want to customize your data persistence beyond what these presets define, [you can override the browser flags yourself](#arguments) to configure persistence. ### Browser Binaries diff --git a/packages/wxt/src/virtual/README.md b/packages/wxt/src/virtual/README.md index 248c7042..623f1585 100644 --- a/packages/wxt/src/virtual/README.md +++ b/packages/wxt/src/virtual/README.md @@ -8,4 +8,4 @@ For this reason, the virtual entrypoints get their own TS project to isolate the When bundling WXT for publishing to NPM, all the `wxt/*` imports are marked as external and resolved when building your application. Other imports are added inline. -See https://github.com/wxt-dev/wxt/issues/286#issuecomment-1858888390 for more details. +See for more details.