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

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

Creating a Web Extension

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

1pnpm create plasmo

This command will ask for an "Extension name:"

‎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:

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

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

‎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:

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

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

‎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:

Visit Plasmo Examples

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:

1pnpm build --zip

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

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

• Chrome Webstore: https://developer.chrome.com/docs/webstore/publish/
• Edge Add-on: https://docs.microsoft.com/en-us/microsoft-edge/extensions-chromium/publish/publish-extension
• Mozilla Firefox Add-on: https://extensionworkshop.com/documentation/publish/

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

1pnpm 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:

Join our Discord Server

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:

1{
2  "$schema": "https://raw.githubusercontent.com/PlasmoHQ/bpp/v2/keys.schema.json"
3}

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:

1{
2  "$schema": "https://raw.githubusercontent.com/plasmo-corp/bpp/v2/keys.schema.json",
3  "chrome": {
4    "clientId": "123",
5    "refreshToken": "789",
6    "extId": "abcd",
7    "clientSecret":"efgh"
8  },
9  "edge": {
10    "clientId": "aaaaaaa-aaaa-bbbb-cccc-dddddddddddd",
11    "clientSecret": "abcdefg",
12    "productId": "aaaaaaa-aaaa-bbbb-cccc-dddddddddddd",
13    "accessTokenUrl": "https://login.microsoftonline.com/aaaaaaa-aaaa-bbbb-cccc-dddddddddddd/oauth2/v2.0/token"
14  }
15}

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:

‎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:

---

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

```text
submit.yml
```

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.

Visit Plasmo GitHub Repo

We wish you 🌠 and 🪄!

Back to Blog