- One codebase builds Manifest V3 extensions for Chrome, Edge and Firefox. The manifest is generated from the files in
src/entrypoints. - A popup, an options page, a side panel and a content script UI, all written in React 19 with shadcn/ui components.
- The content script UI renders in a shadow root, so the page's styles and the extension's styles never mix. Popovers, dialogs, selects and tooltips portal into the shadow root, and
remunits are converted topxat build time, so the UI keeps its size on pages that change their root font size. - Typed messaging between the background and the other contexts with @webext-core/messaging.
- Typed storage with WXT's storage API and a
useStorageItemhook. A value changed in one context shows up in every other context. - Light, dark and system themes. The choice is kept in extension storage and applies to the pages and the content script UI.
- Icons from lucide and from any Iconify icon set through
@iconify/tailwind4. - Unit tests with Vitest, and end-to-end tests with Playwright that load the built extension into Chromium.
- ESLint with @kirklin/eslint-config, run on every commit by simple-git-hooks and lint-staged.
The template comes with examples of features that need extra work in an extension. Each one has end-to-end tests in e2e/examples.spec.ts.
- A dialog, a select and a tooltip in the content script UI (
src/entrypoints/content). While the dialog is open, focus stays inside it, Escape closes it, the page behind it cannot scroll, and keys typed into it never reach the page. Radix finds the focused element throughdocument.activeElement, which inside a shadow root only returns the shadow host;followFocusIntoShadowRoots()insrc/lib/shadow-root-focus.tsmakes it return the element inside. - A reading time badge (
src/entrypoints/reading-time.content) that appears at the top of the page's first<article>whenever there is one, and appears again after a single-page app changes its route. - A script in the page's own JavaScript world (
src/entrypoints/page-requests.content.ts). It runs before the page's scripts, wrapsfetchandXMLHttpRequest, and reports the page's requests to the content script through events onwindow. The page can fire the same events, so the content script checks every report before using it. The panel lists the latest requests, and the badge on the extension icon shows how many there were. - Context menus, keyboard shortcuts and the icon badge (
src/entrypoints/background.ts). Text selected on a page can be sent to the side panel from the context menu,Alt+Shift+Bshows or hides the panel on the page, andAlt+Shift+Lcopies the page link as Markdown. - A long-lived port that streams tab activity to the side panel. The browser stops an idle service worker, which closes the port; the side panel then connects again, and that starts the service worker back up.
- Writing to the clipboard from the background. Chrome's service worker has no DOM, so an offscreen document writes the text (
src/entrypoints/offscreen); Firefox's background page writes it directly.
| Category | Technology |
|---|---|
| Framework | WXT 0.21, Vite 8 |
| UI | React 19, shadcn/ui, Radix |
| Styling | Tailwind CSS 4 |
| Language | TypeScript 7 for type checking, TypeScript 6 for the tools that need its API |
| Testing | Vitest 5, Testing Library, Playwright |
| Code quality | ESLint 10 |
- Node.js 22.22.2 or later, or 24.15.0 or later
- pnpm 12
npx degit kirklin/boot-webext my-webext
cd my-webext
pnpm install
pnpm devpnpm dev opens Chrome with the extension installed and reloads it when files change. pnpm dev:firefox does the same in Firefox.
Before publishing, change the extension name in wxt.config.ts, the description and version in package.json, the icons in public/icon, and the Firefox add-on ID (browser_specific_settings.gecko.id) in wxt.config.ts. Remove the examples you do not need, together with the permissions and commands they use in wxt.config.ts.
| Command | Description |
|---|---|
pnpm dev |
Start development in Chrome |
pnpm dev:firefox |
Start development in Firefox |
pnpm build |
Build for Chrome into .output/chrome-mv3 |
pnpm build:firefox |
Build for Firefox into .output/firefox-mv3 |
pnpm zip |
Build and zip for the Chrome Web Store |
pnpm zip:firefox |
Build and zip for Firefox Add-ons, together with the sources zip AMO review asks for |
pnpm lint |
Lint with ESLint (pnpm lint:fix also fixes) |
pnpm typecheck |
Type check with TypeScript 7 (pnpm typecheck:ts6 uses TypeScript 6) |
pnpm test |
Run unit tests |
pnpm test:e2e |
Build, then run the Playwright tests against the built extension |
The end-to-end tests run on the Chromium that Playwright downloads. Install it once with pnpm exec playwright install chromium --no-shell.
| Path | Contents |
|---|---|
src/entrypoints |
Background, content scripts, popup, options, side panel and offscreen document |
src/components |
Shared components |
src/components/ui |
Components added by the shadcn CLI |
src/hooks |
Hooks for storage, the active tab, tab activity, the theme and portals |
src/lib |
Messaging protocol, storage items and the code the entrypoints share |
src/styles/global.css |
Tailwind CSS and the shadcn/ui theme |
public |
Icons and other files copied as they are |
e2e |
Playwright tests and the local site they run the content scripts on |
pnpm shadcn add dropdown-menuComponents are added to src/components/ui. A component that renders through a portal, such as a dropdown menu, needs one change before it works in the content script: pass usePortalContainer() to its Portal, as the dialog, popover, select and tooltip in that folder do. On extension pages the hook returns nothing, and the portal stays on document.body.