Plasmo Framework: a browser extension SDK that generates your manifest

The manifest file is the problem Plasmo removes

A browser extension is not one program. It is a background service worker, one or more content scripts injected into pages, a popup, an options page, and a set of assets, all of which must agree with a single JSON manifest that names entry points, permissions and host matches. Keeping that manifest in sync with the source tree is the tedious part of extension work, and it is where most first-time extension authors lose an afternoon.

Plasmo's answer is declarative development. The README points to a documentation page titled "Where is the manifest.json file", which tells you the short version: you do not write one. You create popup.tsx, options.tsx, content.ts and background.ts, and the build derives the manifest from those files. The README's own file listing shows the convention applied to directories as well, with popup/index.tsx, options/index.tsx and contents/site-one.ts standing in for the flat files.

The audience is TypeScript and React developers who already know how to build a web UI and do not want to learn manifest version differences before shipping anything. The README calls it "a battery-packed browser extension SDK made by hackers for hackers" and compares it to Next.js for browser extensions. That comparison is the clearest statement of intent in the repository: convention over configuration, with the framework owning the build.

How Plasmo builds an extension: Parcel, conventions and generated output

The repository is a pnpm workspace with turbo orchestrating the build. The root package.json declares workspaces for cli/*, api/*, core/*, packages/* and examples/*, and the scripts fan out with turbo run build --filter. The published CLI lives under cli/plasmo, which is why the root has a dev:cli script named turbo run dev --filter=plasmo.

The bundler is Parcel. The topic list on the repository includes parcel, and the root package.json pins @parcel/source-map to 2.1.1 through a pnpm override, which tells you Parcel is a direct dependency of the build rather than an abstraction Plasmo hides completely. React refresh is pinned the same way, at 0.16.0.

The data flow is conventional: you write entry files, the CLI scans the project, Parcel bundles each entry, and the framework emits a manifest plus a loadable extension directory. Features listed in the README that sit on top of that pipeline include live reloading with React HMR, .env* file support, a Storage API, a Messaging API, remote code bundling for things like Google Analytics, and content script UI. Optional Svelte and Vue support exists through separate repositories rather than in the core CLI.

The trade-off is that Parcel is not the most common bundler in this space, so advice written for webpack or Vite setups does not transfer. If your extension depends on a loader or plugin that only exists for another bundler, Plasmo's pipeline is not where you want to fight that battle.

Installing Plasmo and running your first dev build

The README requires Node.js 16.x or later on macOS, Windows or Linux, and strongly recommends pnpm. The scaffold command creates a project directory and pulls the template:

pnpm create plasmo example-dir
cd example-dir
pnpm dev

After pnpm dev starts, the README says the road ahead is straightforward: popup changes go in popup.tsx, options page changes go in options.tsx, content script changes go in content.ts, and background service worker changes go in background.ts. You should expect a build directory containing a generated manifest and the bundled entries, which you load as an unpacked extension from your browser's developer page.

The README also documents a directory layout for projects that outgrow flat files, including an assets folder holding icon.png alongside popup/, options/ and contents/ subdirectories. If you prefer keeping source out of the repository root, the documentation describes a src sub-directory arrangement, with the caveat that assets and other config files still need to live in the root. That caveat is the kind of detail worth reading before you restructure an existing project.

Plasmo is alpha software, and the README says so

The disclaimer at the bottom of the README is unusually direct: Plasmo is currently alpha software, some things might change from version to version, and you use it at your own risk. That is not boilerplate. It means the API surface you build against today is not promised to survive an upgrade, and it means version pinning is a real decision rather than a formality.

The release history supports reading the disclaimer literally. The three most recent releases listed are v0.90.5 from 2025-05-17, v0.90.2 from 2025-02-09 and v0.90.1 from 2025-02-09. A version series still in the 0.90 range after this much development is a signal about how the maintainers view stability. There is no 1.0 in the release list.

The wrong tool case is a team that needs a frozen manifest it controls by hand, for example an extension targeting a browser or manifest variant whose quirks the generator does not model. The README links to a documentation FAQ for the officially supported browser targets rather than listing them inline, so if your target is not mainstream, that page is the first thing to check. A second wrong-tool case is a project that does not want a bundler at all: if a few hundred lines of vanilla JavaScript and a hand-written manifest are enough, Plasmo adds a build dependency and a convention layer you will not use.

Plasmo against WXT, and what actually differs

The most common comparison people search for is Plasmo versus WXT, and the difference is mostly in the underlying machinery rather than the feature list. Both frameworks generate the manifest from a conventional file layout and both target multiple browsers. Plasmo builds on Parcel, which the repository's pnpm override and topic list make explicit. WXT is built on Vite. That choice propagates: the plugin ecosystem you can reach, the way hot module replacement behaves, and the configuration escape hatch all follow from the bundler underneath.

There is a second axis worth weighing. Plasmo ships a set of framework APIs of its own, including the Storage API and Messaging API named in the README, so some of your code is written against Plasmo rather than against the browser. That is convenient while you stay inside the framework, and it is the part most exposed to the alpha disclaimer. A framework that leans harder on the browser's own APIs leaves you with less to rewrite if you ever move.

Neither approach is strictly better. If you are already invested in Vite plugins or you want the smaller surface area, the Vite-based option is the more natural fit. If you want the conventions, the environment file handling and the deployment path in one package, Plasmo bundles more of that together.

Deployment, licence and the cost of upgrading

Plasmo's MIT licence is permissive, and the repository carries a LICENSE file at the root. MIT places few obligations on how you distribute a built extension, but it offers no warranty, which lines up with the alpha disclaimer rather than contradicting it. If your organisation has a policy about dependencies in the 0.x range, that policy will apply here. This is a description of the licence terms, not legal advice.

For publishing, the README points to automated deployment via BPP, the Browser Platform Publisher, which is a separate repository under the same organisation. The submit workflow is documented rather than described inline, so the exact configuration belongs to that documentation. There is also a commercial cloud offering called Itero, which the README introduces for instant beta testing. It is optional and separate from the open source CLI.

The upgrade cost is the part to budget for. The README's alpha warning plus a version series that has not reached 1.0 means you should pin the plasmo package version in your project rather than tracking latest, and re-read the release notes before moving that pin. Because the manifest is generated, an upgrade that changes how entries are detected can change your extension's permissions without any edit on your side. Reviewing the generated manifest after an upgrade is the concrete check that catches this.

Editorial conclusion

Adopt Plasmo if you are building a React or TypeScript extension and want the manifest, bundling and live reload handled for you, and if you accept the README's own alpha disclaimer. Do not adopt it if you need a stable API surface across versions or you must hand-tune the manifest for an unusual target. Before committing, scaffold with pnpm create plasmo, run pnpm dev, and confirm that the generated manifest covers every permission and host your extension actually needs.

Frequently asked questions

Official sources

1. License: MIT
2. PlasmoHQ/plasmo on GitHub
3. Project website
4. README
5. Releases