<div align="center">

<picture>

<source media="(prefers-color-scheme: dark)" srcset="https://github.com/user-attachments/assets/99cb6303-64e4-4bed-bf3f-35735353e6de" />

<source media="(prefers-color-scheme: light)" srcset="https://github.com/user-attachments/assets/a5dbf71c-c509-4c4f-80f4-be88a1943b0a" />

<img alt="Logo" src="https://github.com/user-attachments/assets/99cb6303-64e4-4bed-bf3f-35735353e6de" />

</picture>



<img src="https://hits.seeyoufarm.com/api/count/incr/badge.svg?url=https://github.com/Jonghakseo/chrome-extension-boilerplate-react-viteFactions&count_bg=%23#222222&title_bg=%23#454545&title=😀&edge_flat=true" alt="hits"/>

<a href="https://discord.gg/4ERQ6jgV9a" target="_blank"><img src="https://discord.com/api/guilds/1263404974830915637/widget.png"/></a>

- [Intro](#intro)

- [Features](#features)

- [Structure](#structure)

- [ChromeExtension](#structure-chrome-extension)

- [Packages](#structure-packages)

- [Pages](#structure-pages)

- [Getting started](#getting-started)

- [Chrome](#getting-started-chrome)

- [Firefox](#getting-started-firefox)

- [Install dependency](#install-dependency)

- [For root](#install-dependency-for-root)

- [For module](#install-dependency-for-module)

- [Community](#community)

- [Reference](#reference)

- [Star History](#star-history)

- [Contributors](#contributors)

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.

- [React18](https://reactjs.org/)

- [TypeScript](https://www.typescriptlang.org/)

- [Tailwindcss](https://tailwindcss.com/)

- [Vite](https://vitejs.dev/) (and [Rollup](https://rollupjs.org/))

- [Turborepo](https://turbo.build/repo)

- [Prettier](https://prettier.io/)

- [ESLint](https://eslint.org/)

- [Chrome Extensions Manifest Version 3](https://developer.chrome.com/docs/extensions/mv3/intro/)

- [Custom i18n package](/packages/i18n/)

- [Custom HMR (Hot Module Rebuild) plugin](/packages/hmr/)

- [End-to-end testing with WebdriverIO](https://webdriver.io/)

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`

1. Run:

- Dev: `pnpm dev` (on Windows, you should run as administrator; see [issue#456](https://github.com/Jonghakseo/chrome-extension-boilerplate-react-vite/issues/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

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

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

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.MY_API_KEY` (learn more at [Env Variables and Modes](https://vite.dev/guide/env-and-mode))

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

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

- [`manifest.js`](chrome-extension/manifest.js) - script that outputs the `manifest.json`

- [`src/background`](chrome-extension/src/background) - [background script](https://developer.chrome.com/docs/extensions/mv3/background_pages/)

(`background.service_worker` in manifest.json)

- [`public`](chrome-extension/public/) - icons referenced in the manifest; content CSS for user's page injection

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](https://developer.chrome.com/docs/extensions/reference/api/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.zip` inside the newly created `dist-zip`

- `e2e` - run `pnpm e2e` for end-to-end tests of your zipped extension on different browsers

Code that is transpiled to be part of the extension lives in the [pages](pages/) directory.

- [`content`](pages/content/) - [content scripts](https://developer.chrome.com/docs/extensions/develop/concepts/content-scripts)

(`content_scripts` in manifest.json)

- [`content-ui`](pages/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`](pages/content-runtime/src/) - [injected content scripts](https://developer.chrome.com/docs/extensions/develop/concepts/content-scripts#functionality);

this can be injected from `popup` like standard `content`

- [`devtools`](pages/devtools/) - [extend the browser DevTools](https://developer.chrome.com/docs/extensions/how-to/devtools/extend-devtools#creating)

(`devtools_page` in manifest.json)

- [`devtools-panel`](pages/devtools-panel/) - [DevTools panel](https://developer.chrome.com/docs/extensions/reference/api/devtools/panels)

for [devtools](pages/devtools/src/index.ts)

- [`new-tab`](pages/new-tab/) - [override the default New Tab page](https://developer.chrome.com/docs/extensions/develop/ui/override-chrome-pages)

(`chrome_url_overrides.newtab` in manifest.json)

- [`options`](pages/options/) - [options page](https://developer.chrome.com/docs/extensions/develop/ui/options-page)

(`options_page` in manifest.json)

- [`popup`](pages/popup/) - [popup](https://developer.chrome.com/docs/extensions/reference/api/action#popup) shown when clicking the extension in the toolbar

(`action.default_popup` in manifest.json)

- [`side-panel`](pages/side-panel/) - [sidepanel (Chrome 114+)](https://developer.chrome.com/docs/extensions/reference/api/sidePanel)

(`side_panel.default_path` in manifest.json)

To chat with other community members, you can join the [Discord](https://discord.gg/4ERQ6jgV9a) 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!

- [Chrome Extensions](https://developer.chrome.com/docs/extensions)

- [Vite Plugin](https://vitejs.dev/guide/api-plugin.html)

- [Rollup](https://rollupjs.org/guide/en/)

- [Turborepo](https://turbo.build/repo/docs)

- [Rollup-plugin-chrome-extension](https://www.extend-chrome.dev/rollup-plugin)

<a href="https://star-history.com/#Jonghakseo/chrome-extension-boilerplate-react-vite&Date">

<picture>

<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=Jonghakseo/chrome-extension-boilerplate-react-vite&type=Date&theme=dark" />

<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=Jonghakseo/chrome-extension-boilerplate-react-vite&type=Date" />

<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=Jonghakseo/chrome-extension-boilerplate-react-vite&type=Date" />

</picture>

</a>

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

<a href="https://github.com/Jonghakseo/chrome-extension-boilerplate-react-vite/graphs/contributors">

<img width="500px" src="https://contrib.rocks/image?repo=Jonghakseo/chrome-extension-boilerplate-react-vite" alt="All Contributors"/>

</a>

| <a href="https://jb.gg/OpenSourceSupport"><img width="40" src="https://resources.jetbrains.com/storage/products/company/brand/logos/jb_beam.png" alt="JetBrains Logo (Main) logo."></a> | <a href="https://www.linkedin.com/in/j-acks0n"><img width="40" style="border-radius:50%" src='https://avatars.githubusercontent.com/u/23139754' alt='Jackson Hong'/></a> |

|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

Made by [Jonghakseo](https://jonghakseo.github.io/)