Plasmo Framework CLI

Common errors

• Error: ENOENT: no such file or directory, stat '<path>'

  cause A file system operation, often involving internal asset handling, failed because a required file or directory was not found.
  fix Upgrade Plasmo to `v0.90.5` or later, which includes improved error handling for ENOENT. Ensure all files referenced in your project exist at the correct paths.

• TypeError: `defineManifest` must return an object (Got type string)

  cause The `manifest.ts` file is not correctly exporting a manifest object. This typically occurs if `defineManifest` is not used or if its return value is not a plain object.
  fix Ensure your `manifest.ts` explicitly uses `export default defineManifest({ ... })` and that the object passed to `defineManifest` is well-formed.

• Refused to create a Trusted Type policy because the name 'plasmo' is not a valid policy name. (Browser Console Error)

  cause A Content Security Policy (CSP) restriction is preventing Plasmo's internal loading indicator from creating a necessary TrustedTypePolicy in the browser environment.
  fix Upgrade Plasmo to `v0.90.1` or later, as this version includes specific bug fixes to address TrustedTypePolicy CSP compatibility issues. Review your extension's CSP if the issue persists on older Plasmo versions.

Warnings

• breaking Plasmo versions prior to `v0.90.1` may not fully support React 19. Using newer React versions with older Plasmo releases could lead to build or runtime inconsistencies.
  Fix: Upgrade Plasmo to `v0.90.1` or later to ensure compatibility with React 19. Also, confirm `react` and `react-dom` versions are aligned with the Plasmo update.
• gotcha Content Security Policy (CSP) restrictions and `TrustedTypePolicy` creation could cause runtime errors, particularly affecting loading indicators in browser extensions built with Plasmo versions before `v0.90.1`.
  Fix: Upgrade Plasmo to `v0.90.1` or later, as this release includes specific fixes for CSP and TrustedTypePolicy related issues.
• gotcha In Plasmo versions before `v0.89.3`, the framework's internal new version check mechanism could inadvertently block or significantly delay `plasmo dev` and `plasmo build` commands, hindering the development workflow.
  Fix: Upgrade Plasmo to `v0.89.3` or later to resolve the blocking behavior associated with the version check.
• gotcha Updates to native dependencies like `sharp` (e.g., in `v0.90.2`) can sometimes introduce platform-specific build failures. If you encounter build issues after a Plasmo update, especially on different operating systems, native module conflicts might be the cause.
  Fix: Perform a clean install of node modules by deleting `node_modules` and your lock file (`pnpm-lock.yaml`, `package-lock.json`, or `yarn.lock`), then reinstalling dependencies with `pnpm install` (recommended) or `npm install`.

Install

• npm install plasmo npm
• yarn add plasmo yarn
• pnpm add plasmo pnpm

Imports

• defineManifest

  import { defineManifest } from 'plasmo'

  Used in `manifest.ts` to programmatically define and configure the browser extension's manifest file.
• PlasmoCSUI

  import type { PlasmoCSUI } from 'plasmo'

  Type definition for Content Script UI components, typically imported for type checking when creating React/TSX content script entrypoints.
• PlasmoExtensionManifest

  import type { PlasmoExtensionManifest } from 'plasmo'

  Type definition representing the structure of a Plasmo browser extension manifest, useful for ensuring type safety in `manifest.ts`.

Quickstart

Initializes a new Plasmo extension project, installs dependencies, and demonstrates how to start the development server and build for production.

npx plasmo init my-extension
cd my-extension
pnpm install # Or npm install / yarn install

# Start development server with live-reloading
plasmo dev

# Build for production, e.g., for Chrome, Manifest V3, and create a zip file
plasmo build --target=chrome-mv3 --zip