Browser Extension Starter

Browser extension starter kit with Typescript, E2E tests, icon generation, automatic i18n, Github pages automation and ESBuild

Screenshot

Downloads

Chrome Web Store

Firefox Add-ons

Opera Add-ons

Ms Edge Add-ons

Safari Extensions

Project setup

# Install dependencies
npm install

# Build extension for development, watch for file changes and rebuild.
npm run build
npm run watch

# Generate compliant images assets for logo (default logo location assets/logo.png)
npm run generateIcons

# Translate app strings to all supported chrome locales
npm run translate

# Start an instance of Chromium with extension installed (using puppeteer)
# For Firefox, pass --browser=firefox as argument.
npm run build start

# Build and package extension into a store-ready upload
node tools/esbuild.js build --prod

# Create extension package for Firefox/Opera/Edge by specifying --browser argument
node tools/esbuild.js build --prod  --browser=firefox

# Run tests
npm run test

# Update static Github pages config and assets
node website/config_generator.js

Install Locally

Chrome

Open chrome and navigate to extensions page using this URL: chrome://extensions.
Enable the “Developer mode”.
Click “Load unpacked extension” button, browse the build/chrome-dev directory and select it.

Firefox

Open firefox and navigate to about:debugging#/runtime/this-firefox.
Click the “Load Temporary Add-on” button.
Browse the build/firefox-dev directory and select the manifest.json file.

Features

Automatic Github Pages generation: Files added in the gh-pages sub-directory are branched to create a Github page automatically. This is useful for static pages like help, welcome and feedback pages.
Typescript to Js: Write your entire chrome extension in Typescript and have it transpiled to JavaScript.
E2E extension test: Start up a chrome browser with your extension installed, write your tests in Jasmine.
Generate extension icons: Forget the pain of generating icons of different size to meet icons requirements.
Manifest V3 Compatible: Easier submission to the Chrome Webstore.
Automatic translation: The messages for all supported i18n locales are auto-generated from the English version.
Zero Dependencies: This starter is minimal to avoid supply-chain attacks which is rampant with Js projects.
Welcome and Uninstall pages: To give your project a head start, welcome pages are great for demos and uninstall pages provide a thoughtful exit.
Utilities for common tasks: Comes with helpers logging, storage, and requesting feedback.

Notes

E2E testing with Firefox.

By default, puppeteer only downloads Chromium, run the command below to install Firefox's equivalent of chromium: ``` PUPPETEER_PRODUCT=firefox npm i -D puppeteer --prefix ./node_modules/firefox-puppeteer ``` `PUPPETEER_PRODUCT=firefox` tells puppeteer to download firefox. `--prefix ./node_modules/firefox-puppeteer` forces a new fetch of puppeteer. This is necessary since `node_modules/puppeteer` already exists (for chromium). The actual value of the prefix doesn't matter, just don't overwrite an actual package. _NB:_ After running the above command, they will no be update to package.json or package-lock.json... since package "puppeteer" already exists.

Open-source chrome extensions built using this template

1. https://github.com/essentialkit/floating-calculator 2. https://github.com/essentialkit/better-previews 3. https://github.com/essentialkit/e-dictionary

Keeping up with changes in this repo

Staying up-to-date with this repo after a fork: 1. Create a new repository by either forking/copying this one. 2. Add this repository as a remote to the new repo `git remote add xtension git@github.com:justiceo/xtension.git` 3. Fetch the latest updates from the xtension repo (template). `git fetch xtension` 4. Create a local branch to track xtension repo. `git checkout -B xtension && git branch -u xtension/master` 5. There should be two divergent histories now. `master -> origin/master` and `xtension -> xtension/master`. 6. Copy the changes from xtension to master without a commit. `git checkout xtension -- .` 7. Fix any changes then commit `git commit -m "merged updates from xtension"`.

Integrating changes into this repo

1. Add xtension as a remote. `git remote add xtension git@github.com:justiceo/xtension.git` 2. Avoid pushing to it. `git remote set-url --push xtension do-not-push` 3. Create new branch to track xtension `git checkout -b base` 4. Pull changess from xtension and rebase onto it. `git pull xtension main --rebase -X theirs` 5. Push changes from base to origin `git push --set-upstream origin base` 6. Merge the changes from base into main `git merge base -X theirs --allow-unrelated-histories --no-commit --no-ff` 7. Review the diff and commit. `git commit -m "up-to-date with xtension"`