Repository files navigation

This boilerplatehasLegacy version

• Intro
• Features
• Structure
  • ChromeExtension
  • Packages
  • Pages
• Installation
  • Chrome
  • Firefox
• Install dependency
  • For root
  • For module
• Environment variables
  • Add new
  • Set via CLI
• Troubleshooting
  • Hot module reload seems to have frozen
  • Imports not resolving correctly
• Community
• Debugging
• Reference
• Star History
• Contributors

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

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

1. Clone this repository.(git clone https://github.com/Jonghakseo/chrome-extension-boilerplate-react-vite )
2. Ensure your node version is >= than in.nvmrc file, recommend to usenvm
3. Edit/packages/i18n/locales/{your locale(s)}/messages.json
4. In the objectsextensionDescription andextensionName, change themessage fields (leavedescription alone)
5. Install pnpm globally:npm install -g pnpm
6. Runpnpm install
7. Check if you have that configuration in your IDE/Editor:
   • VS Code:
     • InstalledESLint extension
     • InstalledPrettier extension
     • EnabledTypescript Workbench version in settings:
       • CTRL + SHIFT + P -> Search:Typescript: Select Typescript version... ->Use Workbench version
       • Read more
     • Optional, for imports to work correctly in WSL, you might need to install theRemote - WSL extension and connect to WSL remotely from VS Code. See overview section in the extension page for more information.
   • WebStorm:
     • ConfiguredESLint
     • ConfiguredPrettier
     • Optional, but usefulFile | Settings | Tools | Actions on Save
       ->Optimize imports andReformat code
8. Runpnpm update-version <version> for change theversion to the desired version of your extension.

Then, depending on the target browser:

1. Run:
   • Dev:pnpm dev (on Windows, you should run as administrator;seeissue#456)
   • Prod:pnpm build
2. Open in browser -chrome://extensions
3. Check -Developer mode
4. Click -Load unpacked in the upper left corner
5. Select thedist 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 -Load Temporary Add-on... in the upper right corner
4. Select the./dist/manifest.json file from the boilerplate project

1. Runpnpm i <package> -w

1. Runpnpm i <package> -F <module name>

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

Read here

Read:Env Documentation

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

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

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

• content - Scripts injected into specified pages (You can see it in console)
• content-ui - React Components injected into specified pages (You can see it at the very bottom of pages)
• content-runtime -injected content scriptsThis can be injected from e.g.popup like standardcontent
• devtools -extend the browser DevTools(devtools_page in manifest.json)
• devtools-panel -DevTools panelfordevtools
• 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 whenclicking the extension in the toolbar(action.default_popup in manifest.json)
• side-panel -sidepanel (Chrome 114+)(side_panel.default_path in manifest.json)

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 withstorage, 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 - runpnpm zip to pack thedist folder intoextension-YYYYMMDD-HHmmss.zip inside the newly createddist-zip
• module-manager - runpnpm module-manager to enable/disable modules
• e2e - runpnpm e2e for end-to-end tests of your zipped extension on different browsers

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 agrpc error,kill theturbo processand runpnpm dev again.

If you are using WSL and imports are not resolving correctly, ensure that you have connected VS Code to WSL remotely using theRemote - WSL extension.

To chat with other community members, you can join theDiscord 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 useBrie lets you capture screenshots, errors, and network activity, making it easier for us to help.

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

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

Made byJonghakseo