• Browser Extension SDK
  • Environment Variables

Environment Variables

Built-in Environment Variables

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

  • NODE_ENV: Either development or production
  • PLASMO_TARGET: The specified target, e.g. chrome-mv3
  • PLASMO_BROWSER: The name of the target browser, e.g. chrome
  • PLASMO_MANIFEST_VERSION: The manifest version, e.g. mv3
  • 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, developer 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. .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.

Prioritized Env

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

plasmo build --env=.env.important

Using Environment Variables

Environment variable is a powerful feature that allows you to customize your extension to fit the need of each browser from the same codebase.

In Source Code

To reference an environment variable in your source code modules, 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
console.log(process.env.PRIVATE_KEY)

To override a variable in the production build with plasmo build, supply a .env.production file. Since Plasmo cascades .env files, you only need to specify the variable that gets replaced.

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 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. 😎

NOTE: Plasmo will omit the key if it can't find the environment variable.

Last updated on December 4, 2022