# Chrome Extension

{% hint style="info" %}
This boilerplate is available with the package [Startup **+ Chrome Extension Boilerplate**](https://shipped.club/chrome-extension-boilerplate) so be sure to purchase it to get access.
{% endhint %}

## Get started

Start by cloning the repository.

```bash
git clone git@github.com: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.

```bash
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](#test-authentication-locally))
* 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.

{% code title="terminal" %}

```bash
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
```

{% endcode %}

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

{% code title="extension/src/config.ts" %}

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

{% endcode %}

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

{% code title=".env" %}

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

{% endcode %}

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).

<figure><img src="https://3985976695-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FT3t4pDs63s3Soj1JetJw%2Fuploads%2FARZfkVhcGHUIYwG6cswG%2FExport-1709383179094.gif?alt=media&#x26;token=6c07d5b7-01e6-4ebb-927e-14a0e3bcadbc" alt=""><figcaption><p>Chrome Extension install welcome page</p></figcaption></figure>

{% hint style="info" %}
**Claim your free static ngrok domain**

Do avoid having a different ngrok domain every time your run ngrok, follow [this guide](https://ngrok.com/blog-post/free-static-domains-ngrok-users) to get a static fixed domain.
{% endhint %}

## 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

{% code title="terminal" %}

```bash
cd extension
npm run storybook
```

{% endcode %}

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

<figure><img src="https://3985976695-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FT3t4pDs63s3Soj1JetJw%2Fuploads%2FAOPLvlAKqzgO6YjzCfYt%2Fimage.png?alt=media&#x26;token=1c61025c-a3d2-417b-82ce-7c00fdbe8bac" alt=""><figcaption><p>Storybook</p></figcaption></figure>

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.

<figure><img src="https://3985976695-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FT3t4pDs63s3Soj1JetJw%2Fuploads%2FE7eDzQQlp89DOBbRkr2Y%2Fimage.png?alt=media&#x26;token=f9bebdd2-0d11-4b97-8f7e-5af35dd800bb" alt=""><figcaption></figcaption></figure>

## 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](https://chromewebstore.google.com/) 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](#load-the-extension-into-chrome "mention")