Chrome Extension

Boilerplate for the React Chrome Extension

This boilerplate is available with the package Startup + Chrome Extension Boilerplate so be sure to purchase it to get access.

Get started

Start by cloning the repository.

git clone [e-mail]:ShippedForBrowserExtensions/shipped-browser-extensions.git
cd shipped-browser-extensions

This repository contains both the Startup package, and the Next.js web app with all the components, pages, integrations, and the extension.

All the code for the extension is in the /extension folder of the repository.

Move to the extension folder, install the dependencies, and run it.

cd extension
nvm use # install the right version of node.js
npm i # install dependncies
npm run watch:dist # build and watch

When built, the Chrome Extension files are available into the folder /extension/dist.

Configuration

To configure the Chrome Extension you need to:

• set the dev domain in extension/src/config.ts (use the ngrok URL domain, see below)

• set the production domain in extension/src/config.ts (this is the URL of your production website, i.e. yourwebsite.com)

• fill the other variables in extension/src/config.ts

• update the file extension/src/manifest.json with all the information needed, especially:

  • externally_connectable

  • host_permissions

Load the extension into Chrome

To load the extension you need to follow these steps:

• Open Chrome

• Click on the three dots menu > Extensions > Manage Extensions

• Enable the Developer mode

• Click on Load unpacked

• Select the shipped /extension/dist folder on your computer

• The extension is now installed, and the welcome page should be open

Install welcome page

The welcome page is available at src/app/extension/welcome/page.tsx

To use it, you need to execute npm run dev in the root folder of the repository.

The page is available at http://localhost:3000/extension/welcome.

Test authentication locally

To make the authentication work inside the extension, you need to use a publicly available domain.

We will use ngrok for this purpose.

terminal

npm install -g ngrok # install ngrok globally
npm run dev # run your local Next.js web server
ngrok http http://localhost:3000 # run ngrok with redirect to your local web server

Take the URL returned by ngrok and update the file extension/src/config.ts.

extension/src/config.ts

export const domainDev = "a3f9-2001-b07-645f-cf50-d107-284b-a956-944f.ngrok-free.app";

Update the environment variable in .env to your ngrok URL if you're using NextAuth (otherwise, skip it).

.env

NEXTAUTH_URL="https://a3f9-2001-b07-645f-cf50-d107-284b-a956-944f.ngrok-free.app"

Now, if you have the watcher active (npm run watch:dist) the chrome extension should be automatically built, otherwise, execute npm run dist in the extension folder.

Uninstall your Chrome extension from chrome://extensions/ and Load unpacked again.

The welcome page should open! (bear in mind that using ngrok adds a small delay in the way the local Next.js web server is served).

Chrome Extension install welcome page

Claim your free static ngrok domain

Do avoid having a different ngrok domain every time your run ngrok, follow this guide to get a static fixed domain.

Storybook

Storybook is an excellent tool to build React component in isolation.

Considering that the build and reload of a Chrome extension takes time (build time + go to the extension tab and click reload), I thought of using Storybook when you just need to develop the UI components of your extension (much faster).

Execute storybook

terminal

cd extension
npm run storybook

This command will run Storybook and open http://localhost:6006

Storybook

The project includes the UI Library ChakraUI, so you can see the Stories for its components.

But the first stories on the left are yours. Feel free to customize and update the React components, and you'll see them updated in Storybook in a matter of seconds!

The Storybook stories files include the suffix .stories.tsx in the filename (i.e. Brand.stories.tsx) and I like to put them close to the component file.

Production Release

Set domainProd in extension/src/config.ts with the domain of your website. Build the extension with npm run dist Go to the Chrome Web Store and create your extension, then upload the zip generated in extension/zip to release a new version.

You can test your production extension locally with these steps: Load the extension into Chrome