Environment Variables

Plasmo offers first-class support for environment variables. This allows you to customize your extension to fit the need of each browser and development environment from the same codebase.

Examples

• with-env (opens in a new tab)

Built-in Environment Variables

Plasmo framework provides the following built-in client-side environment variables:

• NODE_ENV: Either development or production depending on the build command
• PLASMO_TARGET: The specified target, e.g. chrome-mv3, specified by the --target flag
• PLASMO_BROWSER: The name of the target browser, e.g. chrome
• PLASMO_MANIFEST_VERSION: The manifest version, e.g. mv3 or mv2
• PLASMO_TAG: The build tag, e.g. dev, prod or a custom one specified by the --tag flag

Custom Environment Variables

To add environment variables accessible to the extension, create a .env file:

PLASMO_PUBLIC_SHIP_NAME=ncc-1701
PLASMO_PUBLIC_SHIELD_FREQUENCY=42
 
PRIVATE_KEY=xxx

Only environment variables prefixed with PLASMO_PUBLIC_ will be exposed in the built extension bundle.

NODE_ENV Specific Env

To separate environment variables between dev and build, you can use the following files:

• .env.development
• .env.production

If there is a CRX_PUBLIC_KEY environment variable in .env.development but not in .env.production or .env, it will only be available in plasmo dev but not plasmo build.

Bundle Specific Env

Plasmo Framework also provides environment variables specific to a certain build target or build tag when creating the final bundle. Given the following build command:

plasmo build --target=safari-mv3 --tag=alpha

The following env files will be considered, ordered by priority:

• .env.safari
• .env.alpha
• .env

Local Env

Plasmo also supports the following environment file names (Next.js developers will find these familiar):

• .env.<browser>.local
• .env.<tag>.local
• .env.<NODE_ENV>.local
• .env.local

Files with .local at the end of their names have a higher priority than non-local ones. For example, .env.local has higher priority than .env.production and .env.development.

Within the same namespace, however, the cascading order is as expected. This feature utilizes a cascading/overriding strategy for environment variables using the dotenv package (opens in a new tab).

Prioritized Env

To include an environment file that is prioritized above all, use the --env flag. The name of this file can be named anything:

plasmo build --env=.env.important

Using Environment Variables

Environment variables are a powerful feature that allow you to customize your extension to fit the needs of each browser and development environment from the same codebase.

In Source Code

To reference an environment variable in your source code, use the full path process.env.<ENV_NAME>. For example:

// For TSX (popups, option page):
const FrontHull = () => <h1>{process.env.PLASMO_PUBLIC_SHIP_NAME}</h1>
 
// For TS (content scripts or background-scripts):
const shield = new Shield(process.env.PLASMO_PUBLIC_SHIELD_FREQUENCY)
 
// Will be undefined because it's not prefixed with PLASMO_PUBLIC_
console.log(process.env.PRIVATE_KEY)

To enjoy Typescript IntelliSense with your environment variables, create an index.d.ts file:

declare namespace NodeJS {
  interface ProcessEnv {
    PLASMO_PUBLIC_SHIP_NAME?: string
    PLASMO_PUBLIC_SHIELD_FREQUENCY?: number
  }
}

See with-env-files (opens in a new tab) for more details about using .env variables.

In Remote Code Import

Use public environment variables if you are importing remote code:

import "https://www.plasmo.com/js?id=$PLASMO_PUBLIC_ITERO"

In Content Scripts Config

You can also use environment variables in the content script config exports:

export const config: PlasmoContentScript = {
  matches: ["$PLASMO_PUBLIC_SITE_URL/"]
}

In Manifest Overrides

Plasmo lets you override the final generated extension manifest via the manifest property of the package.json file. Taking one step further, Plasmo also parses any environment variables used in the manifest overrides:

"manifest": {
  "key": "$CRX_PUBLIC_KEY"
}

You can use public (prefixed with PLASMO_PUBLIC) and private environment variables in your manifest override. 😎