Awesome

This boilerplate has Legacy version

[!NOTE] This project is listed in the Awesome Vite

[!TIP] Share storage state between all pages

https://github.com/user-attachments/assets/3b8e189f-6443-490e-a455-4f9570267f8c

Table of Contents

• Intro
• Features
• Structure
  • ChromeExtension
  • Packages
  • Pages
• Getting started
  • Chrome
  • Firefox
• Install dependency
  • For root
  • For module
• Community
• Reference
• Star History
• Contributors

Intro

This boilerplate helps you create Chrome/Firefox extensions using React and Typescript. It improves the build speed and development experience by using Vite and Turborepo.

Features

• React18
• TypeScript
• Tailwindcss
• Vite with Rollup
• Turborepo
• Prettier
• ESLint
• Chrome Extensions Manifest Version 3
• Custom i18n package
• Custom HMR (Hot Module Rebuild) plugin
• End-to-end testing with WebdriverIO

Getting started

1. When you're using Windows run this:

   • git config --global core.eol lf
   • git config --global core.autocrlf input

   This will set the EOL (End of line) character to be the same as on Linux/macOS. Without this, our bash script won't work, and you will have conflicts with developers on Linux/macOS.

2. Clone this repository.

3. Edit /packages/i18n/locales/{your locale(s)}/messages.json

4. In the objects extensionDescription and extensionName, change the message fields (leave description alone)

5. In /.package.json, change the version to the desired version of your extension.

6. Install pnpm globally: npm install -g pnpm (check your node version >= 18.19.1))

7. Run pnpm install

Then, depending on the target browser:

For Chrome: <a name="getting-started-chrome"></a>

1. Run:
   • Dev: pnpm dev (on Windows, you should run as administrator; see issue#456)
   • Prod: pnpm build
2. Open in browser - chrome://extensions
3. Check - <kbd>Developer mode</kbd>
4. Click - <kbd>Load unpacked</kbd> in the upper left corner
5. Select the dist directory from the boilerplate project

For Firefox: <a name="getting-started-firefox"></a>

1. Run:
   • Dev: pnpm dev:firefox
   • Prod: pnpm build:firefox
2. Open in browser - about:debugging#/runtime/this-firefox
3. Click - <kbd>Load Temporary Add-on...</kbd> in the upper right corner
4. Select the ./dist/manifest.json file from the boilerplate project

[!NOTE] In Firefox, you load add-ons in temporary mode. That means they'll disappear after each browser close. You have to load the add-on on every browser launch.

Install dependency for turborepo: <a name="install-dependency"></a>

For root: <a name="install-dependency-for-root"></a>

1. Run pnpm i <package> -w

For module: <a name="install-dependency-for-module"></a>

1. Run pnpm i <package> -F <module name>

package - Name of the package you want to install e.g. nodemon
module-name - You can find it inside each package.json under the key name, e.g. @extension/content-script, you can use only content-script without @extension/ prefix

Environment variables

To add an environment variable:

1. Copy .example.env to .env (in the same directory)

2. Add a new record inside .env, prefixed with VITE_, e.g. VITE_MY_API_KEY=...

3. Edit ./vite-env.d.ts and in the ImportMetaEnv interface, add your variable with the appropriate type, e.g.

   readonly VITE_MY_API_KEY: string;

4. Then you can read the variable via import.meta.env.VITE_MY_API_KEY (learn more at Env Variables and Modes)

If you want to set it for each package independently:

1. Create .env inside that package
2. Open related vite.config.mts and add envDir: '.' at the end of this config
3. Rest steps like above

Remember you can't use global and local at the same time for the same package(It will be overwritten)

Boilerplate structure <a name="structure"></a>

Chrome extension <a name="structure-chrome-extension"></a>

The extension lives in the chrome-extension directory and includes the following files:

• manifest.js - script that outputs the manifest.json
• src/background - background script (background.service_worker in manifest.json)
• public - icons referenced in the manifest; content CSS for user's page injection

[!IMPORTANT] To facilitate development, the boilerplate is configured to "Read and change all your data on all websites". In production, it's best practice to limit the premissions to only the strictly necessary websites. See Declaring permissions and edit manifest.js accordingly.

Pages <a name="structure-pages"></a>

Code that is transpiled to be part of the extension lives in the pages directory.

• content - content scripts (content_scripts in manifest.json)
• content-ui - React UI rendered in the current page (you can see it at the very bottom when you get started) (content_scripts in manifest.json)
• content-runtime - injected content scripts; this can be injected from popup like standard content
• devtools - extend the browser DevTools (devtools_page in manifest.json)
• devtools-panel - DevTools panel for devtools
• new-tab - override the default New Tab page (chrome_url_overrides.newtab in manifest.json)
• options - options page (options_page in manifest.json)
• popup - popup shown when clicking the extension in the toolbar (action.default_popup in manifest.json)
• side-panel - sidepanel (Chrome 114+) (side_panel.default_path in manifest.json)

Packages <a name="structure-packages"></a>

Some shared packages:

• dev-utils - utilities for Chrome extension development (manifest-parser, logger)
• i18n - custom internationalization package; provides i18n function with type safety and other validation
• hmr - custom HMR plugin for Vite, injection script for reload/refresh, HMR dev-server
• shared - shared code for the entire project (types, constants, custom hooks, components etc.)
• storage - helpers for easier integration with storage, e.g. local/session storages
• tailwind-config - shared Tailwind config for entire project
• tsconfig - shared tsconfig for the entire project
• ui - function to merge your Tailwind config with the global one; you can save components here
• vite-config - shared Vite config for the entire project
• zipper - run pnpm zip to pack the dist folder into extension-YYYYMMDD-HHmmss.zip inside the newly created dist-zip
• e2e - run pnpm e2e for end-to-end tests of your zipped extension on different browsers

Troubleshooting

Hot module reload seems to have frozen

If saving source files doesn't cause the extension HMR code to trigger a reload of the browser page, try this:

1. Ctrl+C the development server and restart it (pnpm run dev)
2. If you get a grpc error, kill the turbo process and run pnpm dev again.

Community

To chat with other community members, you can join the Discord server. You can ask questions on that server, and you can also help others.

Also, suggest new features or share any challenges you've faced while developing Chrome extensions!

Reference

• Chrome Extensions
• Vite Plugin
• Rollup
• Turborepo
• Rollup-plugin-chrome-extension

Star History <a name="star-history"></a>

Contributors <a name="contributors"></a>

This Boilerplate is made possible thanks to all of its contributors.

Special Thanks To

Made by Jonghakseo