🚀 web-extension-starter

Web Extension starter to build "Write Once Run on Any Browser" extension

🙋‍♂️ Made by @abhijithvijayan

Donate: PayPal, Patreon

❤️ it? ⭐️ it on GitHub or Tweet about it.

Features

• Cross Browser Support (Web-Extensions API)
• Browser Tailored Manifest generation
• Vite for fast builds and HMR
• Automatic build on code changes
• Auto packs browser specific build files
• SASS/SCSS styling with CSS Modules
• TypeScript by default
• ES6 modules support
• React 19 with automatic JSX runtime
• ESLint 9 flat config with Prettier

Tech Stack

• Bundler: Vite 7
• UI: React 19
• Language: TypeScript 5.9
• Styling: SCSS with CSS Modules
• Linting: ESLint 9 (flat config) + Prettier
• Manifest: vite-plugin-wext-manifest

Browser Support

This starter uses Manifest V3 for all browsers.

88+ (Jan 2021)	112+ (Apr 2023)	74+ (Chromium-based)	88+ (Chromium-based)	Latest (Chromium-based)

Note: Firefox 112+ is required for Manifest V3 support with ES modules in background scripts.

Need to support older Firefox versions? See Firefox MV2 Guide for using Manifest V2 with Firefox.

Used by extensions in production that has over 100,000+ users.

• daily.dev - daily.dev extension
• Jiffy Reader
• kutt-extension
• doubanIMDb

Use this template

Create a new directory and run

curl -fsSL https://github.com/abhijithvijayan/web-extension-starter/archive/react-typescript-vite.tar.gz | tar -xz --strip-components=1

🚀 Quick Start

Ensure you have Node.js 20 or later installed.

Then run the following:

# Install dependencies
npm install

# Start development server
npm run dev:chrome    # For Chrome
npm run dev:firefox   # For Firefox

# Build for production
npm run build:chrome  # Build Chrome extension
npm run build:firefox # Build Firefox addon
npm run build         # Build for all browsers

Project Structure

source/
├── Background/        # Service worker (Chrome MV3) / Background script (Firefox)
├── ContentScript/     # Content scripts (injected into web pages)
├── Popup/             # Extension popup UI
├── Options/           # Options page UI
├── components/        # Shared React components
├── styles/            # Global styles and variables
├── types/             # TypeScript type definitions
├── utils/             # Utility functions
├── public/            # Static assets (icons, etc.)
└── manifest.json      # Extension manifest template

Development

Loading the Extension

Chrome

1. Navigate to chrome://extensions
2. Enable "Developer mode"
3. Click "Load unpacked"
4. Select extension/chrome directory

Firefox

1. Navigate to about:debugging
2. Click "This Firefox"
3. Click "Load Temporary Add-on"
4. Select extension/firefox/manifest.json

Content Scripts

Content scripts are automatically bundled as IIFE (Immediately Invoked Function Expression) to ensure compatibility with the browser's content script execution environment, which doesn't support ES modules.

Browser-Specific Manifest

The manifest uses vendor prefixes to generate browser-specific configurations:

{
  "__chrome__name": "My Chrome Extension",
  "__firefox__name": "My Firefox Addon",
  "__chrome|firefox__description": "Works on both!"
}

See vite-plugin-wext-manifest for more details.

Scripts

Linting & TypeScript Config

• Shared ESLint & Prettier Configuration - @abhijithvijayan/eslint-config
• Shared TypeScript Configuration - @abhijithvijayan/tsconfig

Bugs

Please file an issue here for bugs, missing documentation, or unexpected behavior.

License

MIT © Abhijith Vijayan