React Chrome Extension Template

A minimal Chrome extension starter built with React 19, TypeScript, Vite, and Tailwind CSS.

Quick Start

# Clone the template
git clone https://github.com/yosevu/react-chrome-extension-template.git my-extension
cd my-extension

# Run setup wizard
npm run setup
# (resets name/version/manifest to your project)

# Install dependencies
npm install

# Start development
npm run dev

Load in Chrome

1. Open chrome://extensions
2. Enable "Developer mode" (top right)
3. Click "Load unpacked"
4. Select the dist folder

Project Structure

├── options.html            # Options page entry
├── src/                    # Popup UI
│   ├── App.tsx
│   ├── background.ts       # Service worker (background)
│   ├── main.tsx
│   └── options.tsx         # Options UI
├── content-script/         # Content script (injected into pages)
│   └── src/
│       ├── App.tsx
│       └── main.tsx
├── lib/                    # Shared code
│   ├── components/
│   └── styles/
├── public/
│   └── icons/              # Extension icons (16, 32, 48, 128px)
├── manifest.json           # Extension configuration
└── scripts/
    └── setup.js            # Setup wizard

Scripts

Command	Description
npm run dev	Start development server with HMR
npm run build	Build for production
npm run lint	Run ESLint
npm run setup	Run setup wizard

Customizing Icons

Replace the files in public/icons/ with your own icon set:

"icons": {
  "16": "icons/icon-16.png",
  "32": "icons/icon-32.png",
  "48": "icons/icon-48.png",
  "128": "icons/icon-128.png"
}

Background Service Worker

The service worker (src/background.ts) demonstrates a minimal use case: increment a badge counter for quick visual feedback.

Options Page

An options page is available at options.html. The popup includes a button to open it, or you can open it from the extension details page. It also includes a "Reset badge" button to show background messaging.

Demo: Extension Tour

This template includes a tiny demo app that touches the core extension pieces: