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 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.
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:
chrome://extensions in your browserDeveloper mode is enabled (top right)Load unpacked in the top leftAfter 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.
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" />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 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.
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:
npm run dev to start the development serverchrome://extensions in your browserDeveloper mode is enabled (top right)Load unpacked in the top left/build folder in this directoryAfter 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.
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.zipnpm run build - creates a production-ready buildnpm run dev - starts the Webpack development server that hot refreshes changesnpm run format - runs Prettier on the /src foldernpm run lint - runs ESLint on the /src foldernpm run test - runs the test suite via JestBy 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.
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.
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"
}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"
}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"
}
]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 buildsTo add an environment variable simply create / edit any of the above files and add your variable like the following:
MY_VAR=123And 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.productionThe 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.
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.
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.
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.
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:
npm run dev to start the development serverchrome://extensions in your browserDeveloper mode is enabled (top right)Load unpacked in the top left/build folder in this directoryAfter 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.
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.zipnpm run build - creates a production-ready buildnpm run dev - starts the Webpack development server that hot refreshes changesnpm run format - runs Prettier on the /src foldernpm run lint - runs ESLint on the /src foldernpm run test - runs the test suite via JestBy 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.
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.
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"
}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"
}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"
}
]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 buildsTo add an environment variable simply create / edit any of the above files and add your variable like the following:
MY_VAR=123And 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.productionThe 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.
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 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.
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.
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.
Our free ebook gives an overview on how to prepare your extension for development and how to publish it to the Chrome web store.
We're always looking for new template ideas! Feel free to get in touch or submit it to our feature requests.
Not a problem, simply get in touch and we'll help you get it sorted out as soon as possible.