base on Chrome Extension Boilerplate with React + Vite + Typescript <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> > This boilerplate > has [Legacy version](https://github.com/Jonghakseo/chrome-extension-boilerplate-react-vite/tree/legacy) </div> > [!NOTE] > This project is listed in the [Awesome Vite](https://github.com/vitejs/awesome-vite) > [!TIP] > Share storage state between all pages > > https://github.com/user-attachments/assets/3b8e189f-6443-490e-a455-4f9570267f8c ## Table of Contents - [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) - [Environment variables](#env-variables) - [Add new](#env-variables-new) - [Set via CLI](#env-variables-cli-set) - [Community](#community) - [Reference](#reference) - [Star History](#star-history) - [Contributors](#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 - [React19](https://reactjs.org/) - [TypeScript](https://www.typescriptlang.org/) - [Tailwindcss](https://tailwindcss.com/) - [Vite](https://vitejs.dev/) with [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/) ## 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.( ```git clone https://github.com/Jonghakseo/chrome-extension-boilerplate-react-vite``` ) 3. Ensure your node version is >= than in `.nvmrc` file, recommend to use [nvm](https://github.com/nvm-sh/nvm?tab=readme-ov-file#intro) 4. Edit `/packages/i18n/locales/`{your locale(s)}/`messages.json` 5. In the objects `extensionDescription` and `extensionName`, change the `message` fields (leave `description` alone) 6. In `/.package.json`, change the `version` to the desired version of your extension. 7. Install pnpm globally: `npm install -g pnpm` (ensure your node version >= 22.12.0) 8. 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](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 ### 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 ## How do I disable modules I'm not using? ```bash $ pnpm module-manager ``` Read: [Module Manager](packages/module-manager/README.md) ## Environment variables Read: [Env Documentation](packages/env/README.md) ## 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.ts`](chrome-extension/manifest.ts) - 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 > [!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](https://developer.chrome.com/docs/extensions/develop/concepts/declare-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](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) ### Packages <a name="structure-packages"></a> Some shared packages: - `dev-utils` - utilities for Chrome extension development (manifest-parser, logger) - `env` - exports object which contain all environment variables from `.env` and dynamically declared - `hmr` - custom HMR plugin for Vite, injection script for reload/refresh, HMR dev-server - `i18n` - custom internationalization package; provides i18n function with type safety and other validation - `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 Other useful packages: - `zipper` - run `pnpm zip` to pack the `dist` folder into `extension-YYYYMMDD-HHmmss.zip` inside the newly created `dist-zip` - `module-manager` - run `pnpm module-manager` to enable/disable modules - `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](https://github.com/Jonghakseo/chrome-extension-boilerplate-react-vite/issues/612), [kill the `turbo` process](https://github.com/Jonghakseo/chrome-extension-boilerplate-react-vite/issues/612#issuecomment-2518982339) and run `pnpm dev` again. ## Community 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! If you're debugging one, you can use [Brie](https://go.briehq.com/github?utm_source=CEB) lets you capture screenshots, errors, and network activity, making it easier for us to help. ## Reference - [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) ## Star History <a name="star-history"></a> <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> ## Contributors <a name="contributors"></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> --- ## Special Thanks To | <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/) ", Assign "at most 3 tags" to the expected json: {"id":"11364","tags":[]} "only from the tags list I provide: [{"id":77,"name":"3d"},{"id":89,"name":"agent"},{"id":17,"name":"ai"},{"id":54,"name":"algorithm"},{"id":24,"name":"api"},{"id":44,"name":"authentication"},{"id":3,"name":"aws"},{"id":27,"name":"backend"},{"id":60,"name":"benchmark"},{"id":72,"name":"best-practices"},{"id":39,"name":"bitcoin"},{"id":37,"name":"blockchain"},{"id":1,"name":"blog"},{"id":45,"name":"bundler"},{"id":58,"name":"cache"},{"id":21,"name":"chat"},{"id":49,"name":"cicd"},{"id":4,"name":"cli"},{"id":64,"name":"cloud-native"},{"id":48,"name":"cms"},{"id":61,"name":"compiler"},{"id":68,"name":"containerization"},{"id":92,"name":"crm"},{"id":34,"name":"data"},{"id":47,"name":"database"},{"id":8,"name":"declarative-gui "},{"id":9,"name":"deploy-tool"},{"id":53,"name":"desktop-app"},{"id":6,"name":"dev-exp-lib"},{"id":59,"name":"dev-tool"},{"id":13,"name":"ecommerce"},{"id":26,"name":"editor"},{"id":66,"name":"emulator"},{"id":62,"name":"filesystem"},{"id":80,"name":"finance"},{"id":15,"name":"firmware"},{"id":73,"name":"for-fun"},{"id":2,"name":"framework"},{"id":11,"name":"frontend"},{"id":22,"name":"game"},{"id":81,"name":"game-engine "},{"id":23,"name":"graphql"},{"id":84,"name":"gui"},{"id":91,"name":"http"},{"id":5,"name":"http-client"},{"id":51,"name":"iac"},{"id":30,"name":"ide"},{"id":78,"name":"iot"},{"id":40,"name":"json"},{"id":83,"name":"julian"},{"id":38,"name":"k8s"},{"id":31,"name":"language"},{"id":10,"name":"learning-resource"},{"id":33,"name":"lib"},{"id":41,"name":"linter"},{"id":28,"name":"lms"},{"id":16,"name":"logging"},{"id":76,"name":"low-code"},{"id":90,"name":"message-queue"},{"id":42,"name":"mobile-app"},{"id":18,"name":"monitoring"},{"id":36,"name":"networking"},{"id":7,"name":"node-version"},{"id":55,"name":"nosql"},{"id":57,"name":"observability"},{"id":46,"name":"orm"},{"id":52,"name":"os"},{"id":14,"name":"parser"},{"id":74,"name":"react"},{"id":82,"name":"real-time"},{"id":56,"name":"robot"},{"id":65,"name":"runtime"},{"id":32,"name":"sdk"},{"id":71,"name":"search"},{"id":63,"name":"secrets"},{"id":25,"name":"security"},{"id":85,"name":"server"},{"id":86,"name":"serverless"},{"id":70,"name":"storage"},{"id":75,"name":"system-design"},{"id":79,"name":"terminal"},{"id":29,"name":"testing"},{"id":12,"name":"ui"},{"id":50,"name":"ux"},{"id":88,"name":"video"},{"id":20,"name":"web-app"},{"id":35,"name":"web-server"},{"id":43,"name":"webassembly"},{"id":69,"name":"workflow"},{"id":87,"name":"yaml"}]" returns me the "expected json"