React Chrome Extension Template

A modern React Chrome extension template built with TypeScript, Vite, and Vitest. Pre-configured with Prettier, ESLint, and Tailwind CSS for clean, maintainable, and stylish code. This template includes two powerful scripts—build.cjs and publish.cjs—to streamline the development, building, and publishing process for Chrome extensions.

📋 Table of Contents

• Features
• Prerequisites
• Getting Started
• Scripts
• Contributing
• License

✨ Features

• React: Build dynamic UIs with component-based architecture.
• TypeScript: Write type-safe JavaScript with modern ECMAScript features.
• Vitest: Fast and lightweight unit testing framework for reliable code quality.
• Vite: Lightning-fast bundling and development server with HMR support.
• Tailwind CSS: Utility-first CSS framework for rapid and customizable styling.
• Prettier & ESLint: Enforces consistent code style and catches potential errors.
• Build Script: Automates manifest validation, version synchronization, Vite bundling, and ZIP packaging.
• Publish Script: Simplifies uploading your extension to the Chrome Web Store using OAuth 2.0.

📦 Prerequisites

• Node.js (v16 or higher recommended)
• npm (comes with Node.js)
• A Chrome Web Store Developer account (for publishing)

🚀 Getting Started

1. Clone the Repository

   git clone https://github.com/ganemedelabs/react-chrome-extension-template.git
   cd react-chrome-extension-template

2. Install Dependencies

   npm install

3. Customize Your Extension

   • Update manifest.json with your extension's details (e.g., name, description, icons).
   • Modify src/ files to implement your extension's functionality.

4. Configure Environment (for Publishing)

   • Create a .env file in the root directory (see Publish Script for details).

📄 Scripts

Build Script (build.cjs)

The build.cjs script handles the production bundling and packaging of your Chrome extension.

Features

• Validates manifest.json for required fields (e.g., manifest_version, name, version).
• Synchronizes versions between package.json and manifest.json.
• Runs Vite to bundle your React code into the dist/ directory.
• Creates a versioned ZIP file (e.g., extension-name-1-0-0.zip) for deployment if no warnings occur.

Usage

npm run build
# or
node build.cjs

Notes

• Errors (e.g., missing required manifest fields) stop the build.
• Warnings (e.g., missing description or icons) allow the build but prevent ZIP generation.
• Adds manifest_version: 3 if missing and uses package.json name as a fallback.

Publish Script (publish.cjs)

The publish.cjs script uploads a pre-built ZIP file to the Chrome Web Store using OAuth 2.0.

Features

• Verifies the existence of the ZIP file generated by build.cjs.
• Handles OAuth 2.0 authentication (fetches and stores a REFRESH_TOKEN if needed).
• Uploads the ZIP to the Chrome Web Store using your EXTENSION_ID.

Prerequisites

• A ZIP file from a prior build.cjs run.
• A .env file with:

  CLIENT_ID=your_client_id
  CLIENT_SECRET=your_client_secret
  EXTENSION_ID=your_extension_id

• See How to Obtain Credentials for setup instructions.

Usage

npm run publish
# or
node publish.cjs

Notes

• The EXTENSION_ID is available after publishing your extension manually at least once.

How to Obtain CLIENT_ID and CLIENT_SECRET

1. Go to Google Cloud Console and create a project (e.g., chrome-webstore-item).
2. Set up the OAuth consent screen (select "External," add your email as a test user).
3. Enable the Chrome Web Store API.
4. Create an OAuth client ID (select "Desktop app," name it e.g., Chrome Webstore Item).
5. Save the generated CLIENT_ID and CLIENT_SECRET to your .env file.

🤝 Contributing

Feel free to submit issues or pull requests to improve this template!

📜 License

This project is licensed under the MIT License. See the LICENSE file for details.