publication logo
post cover

EXT-101: Creating and Publishing a Web Extension in 15 Minutes

A beginner-friendly, end-to-end tutorial on how to create a simple web extension and seamlessly publish it to major web-stores

author profile

Louis Vilgo

Aug 10 2022

6 mins read

This tutorial assumes the reader has the following essential skills and tools:

  • Operating a terminal/CLI program
  • Using a text editor (VSCode, WebStorm)
  • (Optional) NodeJS, TypeScript and React
  • (Optional) GitHub Action

Setup Development Environment

We begin by setting up our development environment:

  1. Install NodeJS: https://nodejs.org/
    1. NodeJS is a JavaScript runtime. It allows powerful JavaScript tools to run on your system (similar to the Python runtime).
    2. Many cutting-edge front-end toolings leverage NodeJS, such as NextJS, Gatsby, and Plasmo
  2. Install pnpm: https://pnpm.io/
    1. pnpm is a package manager for the NodeJS ecosystem
    2. It is a faster alternative to the default tool npm
  3. Install git: https://git-scm.com/
    1. git is a program to "quick-save" and backup your code
    2. We will use git to upload our code online to GitHub, a popular source code hosting and versioning platform

Open a terminal and check that our tools are good to go. Run npm -v and pnpm -v:

Checking npm and pnpm


Creating a Web Extension

We are now ready to create our extension. In your terminal, run:

pnpm create plasmo 

This command will ask for an "Extension name:"

Extension name Prompt

‎Provide the name, and hit ENTER. The program will bootstrap all the tooling necessary to make our extension development journey as seamless as possible. Once it is done, you will see something like this:

create plasmo finished

‎Run the two commands provided. They will kickstart a development server for our Plasmo web extension project.

A development server provides many benefits such as auto-reloading on code changes, TypeScript code transpiling and bundling, error reporting, etc...

With the dev server running, open your browser of choice (we will be using Google Chrome) and navigate to chrome://extensions:

chrome://extensions page

‎Enable the Developer mode (top-right of the page). Three new buttons will appear:

  1. Load unpacked: Install a development extension
  2. Pack extension: Create an extension bundle for internal distribution, useful for companies with an internal extension policy.
  3. Update: Update every extension installed

Pressing the "Load unpacked" button will open a directory picker. Navigate to our project's directory, then pick the build/chrome-mv3-devartifact:

Load unpacked picking Plasmo dev bundle

‎Your extension is now available in the browser! By default, it is hidden under the extension menu:

Extension Menu

‎To make the extension always show in the browser bar, press the pin button next to its name:

Pinned extension

‎From here, you can leverage your knowledge of React to extend the popup page of your extension. For example, you can change it into a todo-list, a note-taking app, or a link categorizer. For more complex use-cases, please visit the Plasmo example repository:

To learn more about the Plasmo framework, check out our documentation: https://docs.plasmo.com/

Publishing a Web Extension

The Plasmo framework enables seamless automated publishing across multiple browsers. Before we can automate our publishing pipeline, we must do the following once:

  • Manually uploading our extension bundle once
  • Upload our code to GitHub
  • Setup GitHub action

To create a zip bundle for your extension, run:

pnpm build --zip 

This command will produce a zip file called "chrome-mv3-prod.zip" inside the "build" directory:

Plasmo build directory

Use this zip file and follow the official guide below to publish to the chrome webstore and the edge add-on marketplaces:

NOTE: as of August 2022, Mozilla accepts only extension manifest version 2. To create a bundle for Mozilla, you will need to run:

pnpm build --target=firefox-mv2 --zip

This command will produce a firefox-mv2-prod.zip, which should be suitable for the Mozilla Add-on Marketplace.

Once you have created your first bundle, we are now clear to set up the automated submission pipeline provided by Plasmo.

To begin, we will need to upload your extension source code to GitHub. Since Plasmo already setup a git project for you, all you have to do is:

  1. Create a GitHub project
  2. Copy the remote configuration instruction
  3. Push the code

If you are having trouble following the steps above, feel free to join our Discord server and ask! We are a beginner-friendly community:

Once your GitHub project is ready, we will configure the built-in GitHub action Browser Platform Publisher to automate the publishing pipeline. Create a "keys.json" file at the root of your project, starting with a $schema property:

{
  "$schema": "https://raw.githubusercontent.com/PlasmoHQ/bpp/v2/keys.schema.json"
}
NOTE: Do not share the key.json file. Plasmo "ignored" this file for you via the .gitignore file, thus preventing you from pushing it to GitHub

The schema will show you how to create the rest of the keys. You can read more about the key in this Token Documentation: https://github.com/PlasmoHQ/bms/blob/main/tokens.md

Once your key is complete, it might look like this:

{
  "$schema": "https://raw.githubusercontent.com/plasmo-corp/bpp/v2/keys.schema.json",
  "chrome": {
    "clientId": "123",
    "refreshToken": "789",
    "extId": "abcd",
    "clientSecret":"efgh"
  },
  "edge": {
    "clientId": "aaaaaaa-aaaa-bbbb-cccc-dddddddddddd",
    "clientSecret": "abcdefg",
    "productId": "aaaaaaa-aaaa-bbbb-cccc-dddddddddddd",
    "accessTokenUrl": "https://login.microsoftonline.com/aaaaaaa-aaaa-bbbb-cccc-dddddddddddd/oauth2/v2.0/token"
  }
}

Save the key locally and keep it safe. Then copy the key's content and add it as a repository secret on GitHub named SUBMIT_KEYS . With the secret ready, we can now invoke our GitHub action. Open your GitHub repository page, and navigate to the action tab:

GitHub Action page

‎Click on the "Submit to Web Store" workflow from the GitHub action tab. Note that it will be an option in the "Select workflow" dropdown on a smaller screen (like the screenshot above). Upon selecting the workflow, a dropdown button should be presented for you on the right side of a banner that says "Run workflow." Click it to select the branch to run the workflow from, then click the inner "Run workflow" button:

Run workflow

‎Now, anytime you want to publish a new version of your extension project, bump the version number in the package.json file, push your code, and run this workflow from your GitHub page.

PRO TIPS: To automatically upload your extension bundle to the web store anytime you push code to your main branch, you can switch the workflow trigger event using the "on" property inside the submit.yml action file. We recommend configuring it to publish anytime a PR is merged to the main branch with a proper PR review process established.

With the automated pipeline set up, we have closed the end-to-end cycle of extension development, allowing you to focus on just the extension in future development!



Conclusion

We hope our works encourage and inspire more developers to experiment with web extensions and enrich the web browsing experience.

To follow the Plasmo framework's progress, please visit our GitHub repo and give us a ⭐

We wish you 🌠 and 🪄!

Read more posts like this in your inbox

Subscribe to the newsletter

browser extensionbeginner-friendlytutorial