Want to learn all about Chrome Extension development fundamentals? Take a look at our new course! Learn More →

Introduction

Welcome to the ExtensionKit documentation where you can learn how each template works and how to hit the ground running. Please note, every template downloaded also comes with a README file that may provide additional details that are specific to that template (such as how the manifest works). These docs provide a guide on how to work with the templates at a high level.

Basic Templates

Basic templates consist of vanilla HTML, CSS, and JS. There are no additional development tools included, however they are the easiest set of templates to get started with. They can be found here.

Setup

Since basic templates just consist of vanilla HTML, CSS, and JS, all you need to do is extract the downloaded template.

After that, load the extension into the Chrome extension environment:

  1. Navigate to chrome://extensions in your browser
  2. Ensure Developer mode is enabled (top right)
  3. Click Load unpacked in the top left
  4. Select the folder containing the template

After completing the above steps, you should see the developer, unpacked version appear in your extension list as well as the extension icon appear in your browser bar alongside the other extensions you may have installed.

Your template is now setup. Every time you make a change, simply click the refresh icon the extensions page to reload the extension with your changes.

Styling

By default, many of the basic templates come with temporary styles in css/styles.css. You can choose to add additional styles to this file or create additional stylesheets. Stylesheets are imported into the basic starters like you would with any normal HTML file, just add the following to the end of the head in the index.html file:

<link rel="stylesheet" href="path/to/my-stylesheet.css" />

Scripts

By default, many of the basic templates come with temporary scripts in js/scripts.js and potentially some other template-specific ones. You can choose to add additional scripts to this file or create additional files. Scripts are imported into the basic starters like you would with any normal HTML file, just add the following to the end of the body in the index.html file:

<script src="path/to/script.js"></script>

React Templates

React templates are built with React (and optionally TypeScript). They come loaded with additional development tools such as auto reloading of the extension environment. They can be found here.

Setup and dev scripts

Download your chosen template, extract the files, and run an npm install (or yarn) in the directory.

Once installed, start the dev server and add the extension to Chrome by doing the following:

  1. Run npm run dev to start the development server
  2. Navigate to chrome://extensions in your browser
  3. Ensure Developer mode is enabled (top right)
  4. Click Load unpacked in the top left
  5. Select the /build folder in this directory

After completing the above steps, you should see the developer, unpacked version appear in your extension list as well as the extension icon appear in your browser bar alongside the other extensions you may have installed.

After starting the dev server via npm run dev, changes will be automatically rebuilt to /build via webpack and the unpacked Chrome extension will automatically be refreshed for you behind the scenes, meaning you don't need to press the refresh button on chrome://extensions after every change you make.

Included dev scripts

React starter templates come with a series of utility scripts that are the following:

  • npm run assemble - creates a production-ready build and zips all files needed to publish in the web store to extension.zip
  • npm run build - creates a production-ready build
  • npm run dev - starts the Webpack development server that hot refreshes changes
  • npm run format - runs Prettier on the /src folder
  • npm run lint - runs ESLint on the /src folder
  • npm run test - runs the test suite via Jest

Styling

By default the template supports importing CSS files and modules in your components. Additional styling mechanisms such as Styled Components would need to be added if you want to use them.

Manifest

The manifest file is located in the root of the project. It will automatically be copied to the bundle on every build (change made) so there is no need to move it yourself with the dev server running.

Icons

Each starter template comes with a series of placeholder icons found in the /icons folder. Any additional icon sizes you add in here or icons you replace here will be copied to the final build and can be referenced relative to an icons folder in the manifest like the following:

"icons": {
  "128": "icons/my-icon.png"
}

Background scripts

To work with background scripts, create a background folder in the root of the project (not in the /src folder) with an index.js file. Any other files in the /background folder that you import into the index.js will automatically get bundled for you to create a final background.js file that you can reference in the manifest like the following:

"background": {
  "service_worker": "background.js"
}
Note: A current limitation of the dev scripts due to the Chrome extension environment is that changes to background scripts will automatically recompile and regenerate a bundle, however you may need to refresh the extension to see them in some cases.

Content scripts

To work with content scripts, create a content.jsx (or tsx) and / or content.css file in the root of the /src folder. This will cause the content files to be automatically compiled if present. They will be compile to content.js and content.css, respectively.

After that, you can easily reference them in the manifest file relative to the build directly like the following:

"content_scripts": [
  {
    "matches": ["http://*/*", "https://*/*"],
    "js": ["content.js"],
    "css": ["content.css"],
    "run_at": "document_end"
  }
]
Note: A current limitation of the dev scripts due to the Chrome extension environment is that changes to content scripts will automatically recompile and regenerate a bundle, however you may need to refresh the extension to see them in some cases.

Environment variables

There are 3 different environment variables files you can leverage:

  • .env: These variables apply to both development and production builds
  • .env.development: These variables apply to the development builds
  • .env.production: These variables apply to the production builds

To add an environment variable simply create / edit any of the above files and add your variable like the following:

MY_VAR=123

And to reference it in your code simply do process.env.MY_VAR.

Note: Environment variables are NOT ignored by default in the .gitignore but if you wish to have them ignored (good practice), add the following to it:

.env
.env.development
.env.production

Testing

The React starter templates come with Jest and React Testing Library out-of-the-box. To run the included app.test.tsx sample test, simply run npm run test.

The Jest config can be found in jest.config.js and the global setup can be found in jest-setup.js.

TypeScript support

The scripts included with the React starters come with TypeScript support out-of-the-box. If you'd like to use TypeScript, simply download the TypeScript version of the template from the dashboard.

If you've already started development and want to convert the current project to TypeScript, simply convert .jsx files to .tsx and .js files to .ts. Next, create a tsconfig.json file in the root of the project and add the following content:

{
  "compilerOptions": {
    "target": "es6",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": false,
    "jsx": "react-jsx"
  },
  "include": ["src"],
  "exclude": ["build", "node_modules"]
}

Finally, create a react-app-env.d.ts file in the root of the /src folder with the following:

/// <reference types="node" />
/// <reference types="react" />
/// <reference types="react-dom" />

declare namespace NodeJS {
  interface ProcessEnv {
    readonly NODE_ENV: "development" | "production" | "test";
  }
}

If you'd like a more complete type declaration file, grab the one included in the TypeScript version of any React starter on the dashboard.

Additional configuration

ESLint is configured to use eslint-config-react-app by default, which is the ESLint config that create-react-app uses. To make changes to the ESLint config, edit .eslintrc in the project root.

Prettier is configured with some common defaults. You can change those defaults or add your own in .prettierrc in the project root.

Vue Templates

These templates are built with the Vue 3 Composition API, however you can change to the Options API should you wish (navigate to Additional Configration for more information). They come loaded with additional development tools such as auto reloading of the extension environment. They can be found here.

Setup and dev scripts

Download your chosen template, extract the files, and run an npm install (or yarn) in the directory.

Once installed, start the dev server and add the extension to Chrome by doing the following:

  1. Run npm run dev to start the development server
  2. Navigate to chrome://extensions in your browser
  3. Ensure Developer mode is enabled (top right)
  4. Click Load unpacked in the top left
  5. Select the /build folder in this directory

After completing the above steps, you should see the developer, unpacked version appear in your extension list as well as the extension icon appear in your browser bar alongside the other extensions you may have installed.

After starting the dev server via npm run dev, changes will be automatically rebuilt to /build via webpack and the unpacked Chrome extension will automatically be refreshed for you behind the scenes, meaning you don't need to press the refresh button on chrome://extensions after every change you make.

Included dev scripts

Vue starter templates come with a series of utility scripts that are the following:

  • npm run assemble - creates a production-ready build and zips all files needed to publish in the web store to extension.zip
  • npm run build - creates a production-ready build
  • npm run dev - starts the Webpack development server that hot refreshes changes
  • npm run format - runs Prettier on the /src folder
  • npm run lint - runs ESLint on the /src folder
  • npm run test - runs the test suite via Jest

Styling

By default the template supports importing CSS files and modules in your components. Additional styling mechanisms such as Styled Components would need to be added if you want to use them.

Manifest

The manifest file is located in the root of the project. It will automatically be copied to the bundle on every build (change made) so there is no need to move it yourself with the dev server running.

Icons

Each starter template comes with a series of placeholder icons found in the /icons folder. Any additional icon sizes you add in here or icons you replace here will be copied to the final build and can be referenced relative to an icons folder in the manifest like the following:

"icons": {
  "128": "icons/my-icon.png"
}

Background scripts

To work with background scripts, create a background folder in the root of the project (not in the /src folder) with an index.js file. Any other files in the /background folder that you import into the index.js will automatically get bundled for you to create a final background.js file that you can reference in the manifest like the following:

"background": {
  "service_worker": "background.js"
}
Note: A current limitation of the dev scripts due to the Chrome extension environment is that changes to background scripts will automatically recompile and regenerate a bundle, however you may need to refresh the extension to see them in some cases.

Content scripts

To work with content scripts, create a content.js and / or content.css file in the root of the /src folder. This will cause the content files to be automatically compiled if present. They will be compile to content.js and content.css, respectively.

After that, you can easily reference them in the manifest file relative to the build directly like the following:

"content_scripts": [
  {
    "matches": ["http://*/*", "https://*/*"],
    "js": ["content.js"],
    "css": ["content.css"],
    "run_at": "document_end"
  }
]
Note: A current limitation of the dev scripts due to the Chrome extension environment is that changes to content scripts will automatically recompile and regenerate a bundle, however you may need to refresh the extension to see them in some cases.

Environment variables

There are 3 different environment variables files you can leverage:

  • .env: These variables apply to both development and production builds
  • .env.development: These variables apply to the development builds
  • .env.production: These variables apply to the production builds

To add an environment variable simply create / edit any of the above files and add your variable like the following:

MY_VAR=123

And to reference it in your code simply do process.env.MY_VAR.

Note: Environment variables are NOT ignored by default in the .gitignore but if you wish to have them ignored (good practice), add the following to it:

.env
.env.development
.env.production

Testing

The Vue starter templates come with Jest and Vue Testing Utils out-of-the-box. To run the included app.test.tsx sample test, simply run npm run test.

The Jest config can be found in jest.config.js and the global setup can be found in jest-setup.js.

Additional configuration

To make changes to the ESLint config, edit .eslintrc in the project root.

Prettier is configured with some common defaults. You can change those defaults or add your own in .prettierrc in the project root.

By default, the Vue.js Options API is disabled in favor of the Composition API, but this can be easily switched by tweaking the code found in App.vue to use the Options API as well as to enable it in Webpack config/webpack.common.js on line 46 by setting __VUE_OPTIONS_API__ to true.

Example Templates

Example templates consist of fully functional example extensions as well as one-off examples of how to achieve certain things in the extension environment. Recommended experience varies based on each template. They can be found here.

Setup and usage

Since every example template is different, please refer to the README of the specific one. All example templates are based off the basic and React templates mentioned above so the same instructions apply.

Frequently Asked Questions

How come I can't see changes I made in the code?

If you are using a basic extension, you need to manually refresh the extension on change to see the changes reflected. If it is a React-based template, it should automatically refresh the environment.

I'm done with my extension, how can I get it published?

Our free ebook gives an overview on how to prepare your extension for development and how to publish it to the Chrome web store.

I can't find a template that suites my use case, can you create one?

We're always looking for new template ideas! Feel free to get in touch or submit it to our feature requests.

I'm stuck with an issue and can't find the answer here or in the README, what can I do?

Not a problem, simply get in touch and we'll help you get it sorted out as soon as possible.

Start your next extension project without all the boilerplate