Build Chrome Extensions with Plasmo: Your Complete Q&A Guide

This handbook walks you through creating a Chrome extension from scratch using the Plasmo framework, TypeScript, and React. You'll build a Tab Grouper that organizes tabs by domain, learning core extension concepts along the way. Below are the most common questions answered in detail.

1. What is Plasmo and why should I use it for Chrome extensions?

Plasmo is an open-source framework that simplifies building browser extensions. Think of it as Create React App or Next.js, but specifically for Chrome extensions. Without Plasmo, you'd have to manually create a manifest.json file, configure build tools, and set up TypeScript and React. Plasmo does all that for you.

With a single command, you get a working project with TypeScript and React pre-configured. It automatically generates the manifest.json from your package.json, so you never edit it directly. During development, changes to your source files trigger automatic rebuilds and reloads in Chrome. Plus, full type safety for Chrome's APIs is included out of the box.

Importantly, Plasmo doesn't hide the underlying Chrome extension concepts. You still use chrome.tabs, chrome.runtime, and other APIs directly. It just removes the tedious scaffolding, letting you focus on building features. See project setup for how to get started.

2. What will I build by following this handbook?

You'll build a Tab Grouper Chrome extension that automatically organizes your browser tabs by grouping them based on their website domain. For example, if you have 20 tabs open—five from GitHub, four from YouTube, three from Stack Overflow, and eight from other sites—the extension will create colored groups for each domain with one click.

This practical project demonstrates real-world Chrome extension APIs like querying tabs, creating tab groups, and passing messages between different parts of an extension. By the end, you'll have working code and a clear understanding of how to extend it for your own ideas.

3. What are the prerequisites for building a Chrome extension with Plasmo?

To follow along, you'll need basic knowledge of JavaScript and familiarity with React and TypeScript is helpful but not required. You should have Node.js (version 16 or later) and a code editor installed. Also, you'll need Google Chrome for testing the extension.

No prior experience with Chrome extensions or Plasmo is assumed—the handbook starts from scratch. You'll learn the anatomy of an extension (manifest, background scripts, popups), how to load and test it in Chrome during development, and how to publish to the Chrome Web Store. Jump to setup to begin.

4. How do I set up a new Plasmo project?

Setting up a Plasmo project is straightforward. Open your terminal and run the following command:

npx create-plasmo-extension my-tab-grouper

Replace my-tab-grouper with your project name. This command scaffolds a new project with TypeScript and React already configured. Navigate into the folder:

cd my-tab-grouper

Then start the development server:

npm run dev

Plasmo will automatically generate a manifest.json based on your package.json. To load the extension in Chrome, go to chrome://extensions, enable Developer mode, click "Load unpacked", and select the build folder inside your project. Changes you make will reload automatically.

5. How does the background script work in a Plasmo extension?

Background scripts run persistently or as service workers to handle events and maintain state. In Plasmo, you define a background script by creating a file like src/background.ts. The framework automatically registers it in the manifest.

For our Tab Grouper, the background script listens for messages from the popup (like "group tabs") and uses Chrome's tabs and tabGroups APIs to query open tabs, extract domains, and create colored groups. It also handles tab updates or removals to keep groups clean.

Example: When the popup sends a groupTabs message, the background script reads all tabs via chrome.tabs.query, groups them by domain, and calls chrome.tabs.group to create groups. The script communicates back to the popup with results.

6. How do I build the popup UI for the Tab Grouper extension?

The popup UI is a small React component that appears when the user clicks the extension icon. In Plasmo, you create a src/popup.tsx file, which exports a React component. The popup is rendered in a small window (default size 800x600, but you can style it).

For the Tab Grouper, the popup contains a button labeled "Group Tabs". When clicked, it sends a message to the background script using chrome.runtime.sendMessage. You can also display a count of tabs grouped or an error message. Styling uses standard CSS or Tailwind if configured.

Example code snippet:

function Popup() {
  const handleGroup = () => {
    chrome.runtime.sendMessage({ type: 'groupTabs' });
  };
  return <button onClick={handleGroup}>Group Tabs</button>;
}
export default Popup;

Remember to import React.

7. How do I test my Plasmo extension during development?

Testing is easy thanks to Plasmo's hot-reload feature. After running npm run dev, any changes you make to source files are automatically reflected in Chrome without needing to manually reload the extension.

To load the extension for the first time, go to chrome://extensions, enable Developer mode, click "Load unpacked", and select the build folder. After that, every save triggers a rebuild and the extension reloads. You can inspect the background script's console via the extension's service worker inspector, and right-click the popup to inspect it.

Make sure to test core scenarios: clicking the popup button, verifying tab groups appear, and checking that groups update correctly when you close or open tabs. Learn about deployment when you're ready.

8. How do I deploy my Chrome extension to the Chrome Web Store?

Once your extension is complete, you need to prepare it for publishing. First, build a production version with npm run build. This creates an optimized bundle in the build folder.

Then, zip the contents of that folder (not the folder itself). You'll also need:

• A developer account on the Chrome Web Store (one-time fee of $5).
• Icons for your extension (at least 128x128 pixels).
• A detailed description and screenshots.

Go to the Chrome Web Store Developer Dashboard, click "New item", upload your zip, and fill out the listing details. After submission, it takes a few hours to a day for review. Once approved, your extension is live!