🚀 web-extension-starter
Web Extension starter to build "Write Once Run on Any Browser" extension
Donate:
PayPal,
Patreon
❤️ it? ⭐️ it on [GitHub](https://github.com/abhijithvijayan/web-extension-starter) or [Tweet](https://twitter.com/intent/tweet?text=Check%20out%20web-extension-starter%21%20by%20%40_abhijithv%0A%0AWeb%20Extension%20starter%20to%20build%20%22Write%20Once%20Run%20on%20Any%20Browser%22%20extension.%20https%3A%2F%2Fgithub.com%2Fabhijithvijayan%2Fweb-extension-starter%0A%0A%23javascript%20%23react%20%23typescript%20%23sass%20%23webextension%20%23chrome%20%23firefox%20%23opera) 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](https://vitejs.dev/) 7
- **UI**: [React](https://react.dev/) 19
- **Language**: [TypeScript](https://www.typescriptlang.org/) 5.9
- **Styling**: SCSS with CSS Modules
- **Linting**: ESLint 9 (flat config) + Prettier
- **Manifest**: [vite-plugin-wext-manifest](https://github.com/abhijithvijayan/vite-plugin-wext-manifest)
## Browser Support
This starter uses **Manifest V3** for all browsers.
| [](/) | [](/) | [](/) | [](/) | [](/) |
| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| 88+ (Jan 2021) | 109+ (Jan 2023) | 74+ (Chromium-based) | 88+ (Chromium-based) | Latest (Chromium-based) |
> **Note**: Firefox 109+ is required for Manifest V3 support with ES modules in background scripts.
>
> Need to support older Firefox versions? See [Firefox MV2 Guide](docs/FIREFOX_MV2.md) for using Manifest V2 with Firefox.
## Used by extensions in production that has over 100,000+ users.
- [daily.dev](https://daily.dev) - [daily.dev extension](https://r.daily.dev/get)
- [Jiffy Reader](https://chrome.google.com/webstore/detail/jiffy-reader/lljedihjnnjjefafchaljkhbpfhfkdic)
- [kutt-extension](https://chrome.google.com/webstore/detail/kutt/pklakpjfiegjacoppcodencchehlfnpd)
- [doubanIMDb](https://chrome.google.com/webstore/detail/doubanimdb/nfibbjnhkbjlgjaojglmmibdjicidini)
## 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](https://nodejs.org) 20 or later installed.
Then run the following:
```bash
# 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:
```json
{
"__chrome__name": "My Chrome Extension",
"__firefox__name": "My Firefox Addon",
"__chrome|firefox__description": "Works on both!"
}
```
See [vite-plugin-wext-manifest](https://github.com/abhijithvijayan/vite-plugin-wext-manifest) for more details.
## Scripts
| Script | Description |
| ------------------- | ---------------------------------------- |
| `npm run dev:chrome` | Start dev server for Chrome |
| `npm run dev:firefox` | Start dev server for Firefox |
| `npm run build:chrome`| Build production Chrome extension |
| `npm run build:firefox`| Build production Firefox addon |
| `npm run build` | Build for all browsers |
| `npm run lint` | Run ESLint |
| `npm run lint:fix` | Run ESLint with auto-fix |
## Linting & TypeScript Config
- Shared ESLint & Prettier Configuration - [`@abhijithvijayan/eslint-config`](https://www.npmjs.com/package/@abhijithvijayan/eslint-config)
- Shared TypeScript Configuration - [`@abhijithvijayan/tsconfig`](https://www.npmjs.com/package/@abhijithvijayan/tsconfig)
## Bugs
Please file an issue [here](https://github.com/abhijithvijayan/web-extension-starter/issues/new) for bugs, missing documentation, or unexpected behavior.
## License
MIT © [Abhijith Vijayan](https://abhijithvijayan.in)
