Plasmo Framework Guide: Building Chrome Extensions with React and TypeScript

Plasmo is a framework designed to simplify the development of browser extensions, offering a configuration‑free experience similar to Next.js.

Features

Supports React + TypeScript.

Declarative development automatically generates manifest.json (MV3).

Hot reloading, .env* support, remote code bundling, and automated deployment via BPP.

System Requirements

Node.js 16.x or higher.

macOS, Windows, or Linux.

pnpm is recommended (see the linked article for details).

Basic Usage

Initialize a project with:

pnpm dlx plasmo init
# OR npm v7
npm x plasmo init

The command creates a minimal Plasmo extension structure, including popup.tsx , assets , package.json , .prettierrc.cjs , .gitignore , readme.md , and tsconfig.json .

You can provide a name to skip the prompt, e.g., pnpm dlx plasmo init "My Awesome Extension" .

Development Server

Run the development environment with hot‑loading:

pnpm dev
# OR npm run dev
# OR plasmo dev

This creates a development build in build/chrome-mv3-dev that updates automatically on file changes.

Building for Production

Generate a production package with:

pnpm build
# OR npm run build
# OR plasmo build

Add the --zip flag to produce a zip file ready for Chrome Web Store upload.

Loading the Extension in Chrome

Navigate to chrome://extensions and enable Developer Mode.

Click Load Unpacked and select the build/chrome-mv3-dev (or build/chrome-mv3-prod ) folder.

Pin the extension to the toolbar to view the popup.

Content Scripts

Content scripts run in the page context and can scrape data, modify the DOM, or inject UI. Create a content.ts file for a single script or a contents folder for multiple scripts. Export a configuration object to customize matches, frames, etc.

import type { PlasmoContentScript } from "plasmo";
export const config: PlasmoContentScript = {
  matches: ["
"],
  all_frames: true
};

Environment Variables

Plasmo uses .env files with the dotenv package. Only variables prefixed with PLASMO_PUBLIC_ are exposed to the extension. Example:

PLASMO_PUBLIC_SHIP_NAME=ncc-1701
PLASMO_PUBLIC_SHIELD_FREQUENCY=42
PRIVATE_KEY=xxx

Access them in code via process.env.PLASMO_PUBLIC_SHIP_NAME .

Internationalization (i18n)

Place locale JSON files under assets/_locales/{lang}/messages.json and set default_locale in the manifest. Retrieve strings with chrome.i18n.getMessage and reference them in package.json using __MSG_... placeholders.

Remote Code Imports

Import remote scripts directly, optionally using environment variables for IDs:

import "https://www.googletagmanager.com/gtag/js?id=$PLASMO_PUBLIC_GTAG_ID"

Automation (BPP)

Plasmo includes a GitHub Action called Browser Platform Publish (BPP) that can automatically publish the built extension to supported stores. Configure a keys.json file with the appropriate schema before use.

References

Numerous example repositories are linked throughout the article (e.g., with‑popup, with‑options, with‑content‑script, etc.) providing ready‑to‑run samples for each feature.