browser-extension

Browser Extension Creator

Create cross-browser extensions using WXT framework (wxt.dev). Supports Chrome, Firefox, Edge, Safari, and Opera with a single codebase.

When to Use

• Creating a new browser extension from scratch
• Porting an existing extension to WXT
• Adding features to a WXT-based extension (content scripts, popup, background, options)
• Working on, testing, or publishing an EXISTING extension NOT built with WXT (Rspack/Webpack/Vite + hand-rolled src/manifest.json)
• Publishing to Chrome Web Store, Firefox AMO, Edge Add-ons, or distributing internally

Workflow

First, branch on the project type. The phases below scaffold a NEW project with WXT. For an EXISTING extension that does not use WXT (a checked-in src/manifest.json bundled by Rspack/Webpack/Vite — no wxt.config.ts), the scaffold/dev phases do NOT apply: do not migrate it to WXT unless explicitly asked. Consult references/existing-extension-guide.md for that case (project shape, testing the real code, dependency lockstep, CI). references/store-publishing-guide.md applies to both — use its standalone path for non-WXT.

Phase 1: Interview

Gather requirements before writing any code:

1. Purpose — What does the extension do? (one sentence)
2. Features — What specific capabilities? (content script injection, popup UI, background tasks, options page, etc.)
3. Target browsers — Chrome, Firefox, Edge, Safari, Opera? (default: Chrome + Firefox)
4. UI framework — React, Vue, Svelte, Solid, or Vanilla? (default: Vanilla)
5. Distribution mode — stores, local/internal, or both?
6. Internal use? — Does the extension handle corporate/sensitive data?

If the user says "internal" or "work", read the security section in references/local-distribution-guide.md and apply its checklist in all subsequent phases.

Phase 2: Scaffold

Initialize the project with WXT. Consult references/wxt-reference.md for CLI commands and config.

# Initialize project
npx wxt@latest init <project-name>
cd <project-name>

# Install dependencies
npm install

# Prepare TypeScript types
npm run postinstall

Generate these files:

1. wxt.config.ts — Browser targets, permissions, manifest overrides
2. CLAUDE.md — Project-specific instructions (stack, commands, structure)
3. .gitignore — Must include: *.pem, *.key, .env*, config.local.*, .output/, node_modules/

If internal/work extension:

• Generate .env.example with placeholders (never real values)
• Generate config.ts that reads from storage.local, never hardcoded URLs/tokens

Phase 3: Development

Build features using WXT entrypoints. Consult references/extension-patterns.md for code patterns and references/manifest-permissions.md for permissions.

Entrypoints (file-based, in entrypoints/ directory):

• popup/ — Extension popup UI (index.html + main.ts/tsx)
• background.ts — Service worker (alarms, events, API calls)
• content.ts — Scripts injected into web pages
• options/ — Settings page (index.html + main.ts/tsx)

Key APIs (all via wxt/storage and browser namespace):

• Storage — storage.defineItem() for typed persistent state
• Messaging — defineExtensionMessaging() for popup ↔ background communication
• Content Script UI — createShadowRootUi() or createIntegratedUi() for injecting UI

For internal extensions accessing corporate APIs:

• URLs go in storage.local (configurable from options page), never in code
• Auth via browser.identity or user-provided tokens at runtime
• host_permissions with specific domains, never <all_urls>

Phase 4: Testing

Set up Vitest with WXT plugin. Consult references/wxt-reference.md testing section for config and fakeBrowser usage. Write tests beside the files they test.

Phase 5: Build & Distribute

Distribution bifurcates based on the mode chosen in Phase 1.

Local/Internal distribution — Consult references/local-distribution-guide.md:

wxt build                    # Chrome output: .output/chrome-mv3/
wxt build -b firefox         # Firefox output: .output/firefox-mv2/

Load unpacked in browser for testing, ZIP for sharing internally.

Store publishing — Consult references/store-publishing-guide.md:

wxt zip                      # Chrome ZIP for CWS
wxt zip -b firefox           # Firefox ZIP + sources for AMO

Each store has specific requirements (assets, fees, review times).

Automated publishing (optional):

wxt submit init              # Configure store credentials
wxt submit --dry-run \       # Test submission
  --chrome-zip .output/*-chrome.zip \
  --firefox-zip .output/*-firefox.zip \
  --firefox-sources-zip .output/*-sources.zip

Reference Files

File	When to consult
references/existing-extension-guide.md	EXISTING non-WXT extensions: bundler-based MV3, testing the real code (not a mock), dependency lockstep, CI
references/wxt-reference.md	CLI commands, project structure, wxt.config.ts, testing setup
references/extension-patterns.md	Code patterns: popup, content script, background, storage, messaging
references/manifest-permissions.md	Choosing permissions, host_permissions, optional_permissions
references/store-publishing-guide.md	Publishing to Chrome Web Store, Firefox AMO, Edge, Safari
references/local-distribution-guide.md	Load unpacked, enterprise deployment, internal security