Home › Chrome extensions › Browser extension with WXT AGENTS.md

Browser extension with WXT AGENTS.md

AGENTS.md for cross-browser Manifest V3 extensions built with WXT: entrypoints, messaging, storage, and permissions.

AGENTS.mdChrome extensions

Copy AGENTS.md

How to use

Save this as AGENTS.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

Note: Review and test before use. Provided as is, without warranty. See Terms.

# AGENTS.md: Browser extension (WXT)

## Commands
`pnpm dev` (Chrome) · `pnpm dev:firefox` · `pnpm build` · `pnpm zip` · `pnpm compile` (typecheck) · `pnpm test` (Vitest with WXT's testing plugin)

## Structure
- Entrypoints in `entrypoints/`: `background.ts` (`defineBackground`), `*.content.ts` (`defineContentScript({ matches, main })`), `popup/`, `options/`, `sidepanel/`. WXT generates the manifest from these plus `wxt.config.ts`; don't hand-write `manifest.json`.
- Shared code in `utils/`, `components/`; auto-imports are enabled.

## Rules
- Use the `browser` API (WXT's polyfilled global), not `chrome.*`, for cross-browser support.
- The background is a service worker in MV3: no long-lived globals; persist state with `storage.defineItem('local:settings', { fallback })` from WXT storage.
- Messaging through a typed wrapper (e.g., `@webext-core/messaging`) with defined message types; validate data from content scripts.
- Content scripts: inject UI with `createShadowRootUi` to avoid CSS conflicts; clean up on `ctx.onInvalidated`. Never `innerHTML` page-controlled text.
- Permissions: request the minimum in `wxt.config.ts` (`manifest.permissions`, `host_permissions`); prefer `activeTab` and optional permissions requested at runtime.
- No remote code: everything ships in the bundle (store policies forbid remotely hosted code).
- Fetch external APIs from the background, not content scripts, and keep API keys out of the extension when possible (use your backend).

## Don't
Don't upload to the Chrome Web Store or Firefox Add-ons from the agent.

## Done
Typecheck, tests, and `pnpm build` pass for Chrome and Firefox.