Plasmo is an opinionated framework. However, there are cases when it favors flexibility:

  1. When it has yet to formulate a proper abstraction/opinion
  2. When the opinion greatly tampers with the developer's experience
  3. When the topic does not matter

Overriding the Manifest

The following fields from the package.json will be passed over to the generated extension manifest:

  • packageJson.version -> manifest.version
  • packageJson.displayName ->
  • packageJson.description -> manifest.description
  • ->
  • packageJson.homepage -> manifest.homepage_url

The Plasmo Framework extends the package.json with a manifest field that overrides the generated extension manifest. The primary use case is to enable features that the Plasmo framework does not yet natively support.

For instance, the Plasmo Framework might not understand that you need to have an activeTab permission. You'll need to modify your project's package.json like so:

"manifest": {
    "permissions": [

Shadowing the HTML Templates

To replace the default HTML templates, you can create an .html file with the same naming convention to the component file. For example, if you have a popup.tsx and would like to override the html, create a popup.html file:


<!DOCTYPE html>
    <meta charset="utf-8" />

If you have a popup/index.tsx file, create a popup/index.html file with content similar to above. Note that you do not need to include the root element or the script tag. The Plasmo Framework will handle that for you.

Using the src directory for source code

Instead of having your source code in the root directory, you can put it in a child src directory.

For TypeScript to work correctly, you will need to point the resolved paths for the ~* prefix in the tsconfig.json file to "./src/*".

The new configuration looks like this:

  "extends": "plasmo/templates/tsconfig.base",
  "exclude": ["node_modules"],
  "include": [".plasmo/**/*", "./**/*.ts", "./**/*.tsx"],
  "compilerOptions": {
    "paths": {
      "~*": ["./src/*"]
    "baseUrl": "."

Please ensure that ALL source files (including Plasmo's entry files such as popup.tsx, options.tsx, background.ts, etc.) are in the src directory. Otherwise, Plasmo will not know where to find the entry files, which will result in an empty extension!

NOTE: This customization only resolves ~ to /src for source code files with tsx and ts extension. Please see this note about asset resolving.

See with-src.

Last updated on July 27, 2022