Environment variables in browser extensions
Browser extensions ship code that runs on your users’ machines. That makes the line between configuration and secrets sharper than in a typical web app. Anyone who installs your extension can read anything you bundle into JavaScript, HTML, or the compiledmanifest.json.
Extension.js handles this with two environment loading paths. One serves compiled extension bundles (browser and mode aware). The other runs while loading extension.config.* in Node.
Both paths matter depending on where you read your variables.
Template examples
new-env

EXTENSION_PUBLIC_* values.
content-env

How it works
Extension bundles (compile time)
When building your extension, the compiler reads the env files in your extension package folder that match the browser and mode. From the release after 4.1.41, it reads every matching file, and a stronger file overrides a weaker one key by key. Earlier releases read only the strongest match. Strongest first:.env.[browser].[mode](for example,.env.chrome.development).env.[browser]- Engine-family variants of the two above (see the note below)
.env.[mode].local(from the release after 4.1.41).env.[mode].env.local.env
chromium, chrome, edge, chromium-based, the Chromium forks, and Safari builds) also try .env.chromium, .env.chrome, .env.edge, and .env.chromium-based (each with their .[mode] variants first). Gecko-family targets also try .env.firefox and .env.gecko-based. A single .env.chromium file therefore covers a chrome, edge, or brave build, and an exact browser file always wins over family files.
Extension.js always merges .env.defaults first when present, then the matching files’ variables. Finally, system process.env takes highest precedence for overlapping keys.
.env.example is documentation only and is never loaded as a value source.E_ENV_FILE_UNREADABLE. The message names the file.
If env files exist next to your project but none match the current browser and mode, the build prints a warning naming the files it found and the candidates it looked for, so a misspelled browser suffix fails loudly instead of silently shipping without values. A file named for another mode or browser, such as .env.development in a production build, is left alone without a warning, and the warning calls the values undefined only when nothing else, such as extension.config.js, defined them.
From the release after 4.2.0, a file whose name ends in the extension of a file the build ships or compiles, such as .env.css or .env.side.html, is not an env file, and neither is .envrc. The endings, matched in any letter case, are pages (html, htm), stylesheets (css, scss, sass, less, styl), scripts and components (js, mjs, cjs, jsx, ts, mts, cts, tsx, vue, svelte), data and text (json, json5, jsonc, xml, yml, yaml, toml, md, txt), images (png, jpg, jpeg, gif, svg, webp, avif, ico, bmp), fonts (woff, woff2, ttf, otf, eot), media (mp3, mp4, webm, ogg, wav), plus map, wasm, pdf, and zip. Those files are assets that start with .env, so the warning no longer names them or fires for them alone. A name that ends in a browser or a mode, such as .env.chrome or .env.production, always counts as an env file.
Secrets never take the EXTENSION_PUBLIC_ prefix
Every EXTENSION_PUBLIC_* value is written into the built JavaScript. Anyone who installs the extension can read it, and so can every store review. Code that reads import.meta.env as a whole object carries every public value, even the ones it never names.
An API key for an LLM or any other paid service belongs on a server that your extension calls. Give it a name without the EXTENSION_PUBLIC_ prefix, so the bundle never contains it.
A production build warns when an EXTENSION_PUBLIC_* variable with a value has a name that looks secret. A name looks secret when it contains SECRET, TOKEN, PASSWORD, or PRIVATE. It also looks secret when KEY comes right after API, ACCESS, AUTH, or SECRET. A name that contains PUBLISHABLE is skipped. If the value is public by design, such as a Firebase web API key, the warning does not apply to it. This warning needs 4.1.39 or later.
If no matching file exists next to the project, Extension.js repeats the same search from the nearest workspace root. That root is the closest ancestor folder containing pnpm-workspace.yaml. Extensions inside monorepos can share root-level env files for bundle injection. A package whose only env file is .env.defaults also takes the root’s files. The root .env.defaults loads first, and the package’s own .env.defaults wins key by key.
Monorepo constraint: Workspace fallback only runs when a pnpm-workspace.yaml marker exists on an ancestor. If you use pure npm or Yarn workspaces that rely only on package.json "workspaces", this automatic root lookup does not apply. In that case, keep env files beside the extension package, or add a pnpm-workspace.yaml at the repository root.
extension.config.* (Node, before your configuration runs)
extension.config.js / .mjs / .cjs runs in Node. Before Extension.js evaluates the file, it preloads a small set of files into process.env so the configuration can read them. From the release after 4.1.41, the last file follows the command that runs. dev reads the development file. build, start, and preview read the production file.
Every file that exists loads, and a later file overrides the values of an earlier one. A variable your shell or CI exported always wins over every file. An
.mjs config that reads import.meta.env sees the same winners as process.env. build --mode development reads the development files.
A build no longer reads .env.development. A key that exists only in that file is undefined in the configuration of build, start, and preview. Releases up to 4.1.41 preloaded .env.development for every command, so a build configuration read development values.
From the release after 4.1.41, build, start, and preview also preload the browser’s files, such as .env.chrome and .env.chrome.production. The configuration then sees the same values as the bundle. Releases up to 4.2.0 loaded the dev configuration before they knew the browser, so dev read no browser file. From the release after 4.2.0, dev reads the browser’s files on its first load of the configuration, such as .env.chrome and .env.chrome.development.
From the release after 4.1.41, extension.config.js runs once per command. When the configuration names the browser itself, it can run a second time. That happens only if the browser’s files change a variable it read.
You can also rely on bundle-time env (described above) to inject EXTENSION_PUBLIC_* values into extension code.
Workspace fallback: If none of those files exist in the extension package folder, the same preload runs from the nearest folder containing pnpm-workspace.yaml (same constraint as above).
From the release after 4.1.41, a package whose only env file is .env.defaults falls back the same way. The root .env.defaults loads first, and the package’s own .env.defaults wins key by key.
Built-in environment variables
Extension.js injects built-in variables at compile time, so browser and mode are always available in your extension code.
All built-ins above are available through both
process.env.* and import.meta.env.*.
Extension.js replaces these names with their values at compile time. The replacement covers your files and every dependency in the bundle. A dependency that reads process.env.MODE or process.env.BROWSER therefore gets the build mode or the browser target. Three more names get the same treatment:
- A
globalthat the code does not declare becomesglobalThis. import.meta.dirnameandimport.meta.filenamebecomeundefined.
.env file that sets EXTENSION_PUBLIC_BROWSER, EXTENSION_BROWSER, EXTENSION_PUBLIC_MODE, or EXTENSION_MODE to another value prints a W_ENV_NAME_RESERVED warning that names the file. The build target wins, so the file value is ignored.
Environment variable inventory
Public/runtime variables (user-defined)
Static placeholder variables
Built-in/alias variables
CLI and dev-server operational variables
From the release after 4.1.39, every browser resolves its binary in one order. The binary flag comes first, then the variable, the managed binary, and the system install. A variable that names a missing or non-executable path fails the launch with
E_BROWSER_BINARY_INVALID. See How the binary is chosen.
Telemetry control variables
EXTENSION_TELEMETRY=1 is also the explicit opt-in for CI, where telemetry is otherwise off by default. See Telemetry and privacy for the full consent contract.
Scaffolding (extension create) variables
From the release after 4.1.41,
EXTENSION_ALLOW_HTTP_TEMPLATE and EXTENSION_SKIP_INTERNAL_INSTALL accept 1 or true in any letter case, and spaces around the value are ignored. Earlier releases accept only true.
See Templates for how the pinned corpus works.
Browser transport tuning variables
These variables override internal Chrome DevTools Protocol (CDP) and Remote Debugging Protocol (RDP) timeouts. They are useful for slow continuous integration (CI) environments, Docker containers, or debugging flaky browser connections.Browser-specific environment variables
The rules below apply to compile-time / bundle env selection (see Extension bundles above). They do not apply to the narrowextension.config.* preload in Node.
Need different values per browser? Extension.js supports browser-scoped env files such as .env.chrome (Chrome extension environment variables) and .env.firefox (Firefox extension environment variables). You can also combine browser and mode for a single build variant:
.env.chrome.development: Extension.js applies this only when running the extension in Chrome during development mode..env.firefox.production: Extension.js applies this only when building the extension for Firefox in production mode.
.env.[browser].[mode].env.[browser]- Engine-family variants (for example,
.env.chromiumfor any Chromium-family target) .env.[mode].env.local.env
.env.chromium covers chrome, edge, and the Chromium forks, and .env.firefox covers the Gecko forks. Add an exact browser file (such as .env.edge) only when one target needs different values from the rest of its family.
Example files
Custom environment variables
You can define custom variables in env files at project root.Extension.js only injects variables prefixed with
EXTENSION_PUBLIC_ into JavaScript bundles (process.env / import.meta.env).
EXTENSION_PUBLIC_ into JS bundles.However, placeholders in emitted
.json/.html files can resolve $EXTENSION_* tokens, so avoid referencing secrets in static asset templates.
Using environment variables
You can use environment variables inmanifest.json, locales, HTML, and JavaScript/TypeScript files.
1. In manifest.json
manifest.json does not natively support environment variables, but Extension.js replaces supported placeholders during build. For example:
$EXTENSION_PUBLIC_API_URL with the resolved env value.
The value is escaped for the place where it lands, so the emitted file stays valid. In a JSON string, a quote or a backslash in the value is escaped. In HTML text and attributes, &, <, >, and quotes become entities. Inside a <script> string, the value is escaped as a JavaScript string. A value that would still break a JSON file stops the build with E_JSON_INVALID, and the message names the file and the variable.
Keep a local origin out of the production manifest
The same placeholders work in match patterns, which is how a development mock server stays out of the store package. Put the origin in a placeholder and give each mode its own value:extension dev reads .env.development and matches http://localhost:4322/*. extension build reads .env and ships only https://example.com/*. A production build that still names localhost, 127.0.0.1, [::1], or 0.0.0.0 in content_scripts, host_permissions, externally_connectable, or web_accessible_resources prints a warning with the code W_PROD_LOOPBACK_ORIGIN and ships the pattern as written, since a production build pointed at a local server can be on purpose.
2. In locale files
You can also use placeholders in locale files when values should change by environment. For example:$EXTENSION_PUBLIC_SITE_URL with resolved values.
From the release after 4.2.0, a token in _locales/<locale>/messages.json that is followed at once by a second $, such as $EXTENSION_MODE$, is the browser’s own message placeholder, so the build leaves it as written.
3. In HTML files
You can also use placeholders in static HTML files (for example, underpages/):
$EXTENSION_PUBLIC_API_URL in the output HTML.
From the release after 4.2.0, the build fills the same placeholders in every .json and .html file it copies from your project as written. That covers a file listed in web_accessible_resources, a file your background opens with chrome.runtime.getURL(), and a page reached by a root-absolute link such as /options.html. Each value is escaped the way it is in a compiled page. A copied file without a placeholder keeps its exact bytes. Releases up to 4.2.0 shipped those copies with the placeholders left as written.
From the release after 4.2.0, an emitted .json or .html file with no placeholder ships byte for byte, whatever its encoding. A file that holds a placeholder but is not UTF-8 also ships as written, with a W_ENV_ASSET_NOT_UTF8 warning.
From the release after 4.2.0, a placeholder in an inline <script> that is not inside quotes takes the value as written, so the value must be JavaScript itself. When the script no longer parses after the value is filled in, the build fails with E_INLINE_SCRIPT_SYNTAX, and the message names the file and the placeholder. Quote the placeholder, as in "$EXTENSION_PUBLIC_API_URL", to get a string.
4. In JSX components
In React/JSX/TS files, read env values withprocess.env:
process.env.EXTENSION_PUBLIC_X = "v" stays valid code and reaches the env object at run time. The build warns with W_ENV_DEFINE_WRITTEN for your own code, because each dotted read of that name keeps the build value. Keep a value that changes at run time in a variable of your own.
import.meta support
For ECMAScript Module (ESM) workflows, Extension.js also supports import.meta.env:
service_worker.mjs
import.meta.env and process.env have parity for injected env keys.
Reading a key that no env file defines yields undefined instead of crashing: Extension.js defines the bare import.meta.env as an object of every injected variable (Vite parity), so import.meta.env.MISSING_KEY and destructuring like const {FOO} = import.meta.env are both safe in any output format.
import.meta.url at runtime
Before 4.1.19, the bundler replaced import.meta.url with the source file’s file:// path. That path put folder names from the build machine into the shipped bundle. From 4.1.19, Extension.js resolves a bare import.meta.url at runtime instead, in dev and in production builds alike, and the value never contains a build machine path:
A module counts as loaded at runtime when your code reaches it through
chrome.runtime.getURL, importScripts, executeScript({files}), or a root-absolute <script src>. Before 4.1.21 such a module took the value of the context that loaded it.
new URL("./image.png", import.meta.url) still works. The bundler emits the file and points the URL at the emitted copy. import.meta.dirname and import.meta.filename are undefined in extension code, because no file system path exists at runtime.
Secrets in browser extension builds
Browser extensions run on your users’ machines. Anyone who installs your extension can inspect any value you bundle into JavaScript, HTML, or the compiledmanifest.json. Treat the bundle as public.
A few rules to follow:
- Never put API secrets, signing keys, or auth tokens behind
EXTENSION_PUBLIC_*. The prefix exists to mark a value as safe to ship, not to hide it. - Avoid
$EXTENSION_*placeholders in staticmanifest.json, locale, or HTML templates when the value is sensitive. Those expand at build time and end up in the artifact. - Move anything privileged behind a backend you own and call it from the extension at runtime.
- For continuous integration (CI), keep build secrets in
process.env(not committed env files) and rely on.env.defaultsfor safe shared values.
Best practices
- Expose only what must ship: Prefix only client-safe keys with
EXTENSION_PUBLIC_. - Use
.env.defaultsfor shared defaults: Keep predictable team defaults while allowing local/system overrides. - Keep secrets out of static placeholders: Avoid putting secret
$EXTENSION_*tokens in HTML/JSON templates. - Version control hygiene: Commit
.env.exampleas documentation (the build never reads it as a value source) and ignore real env files (.env,.env.local, browser/mode variants). A scaffold fromextension createalready does this: its.gitignoreignores every.env*file, then re-allows.env.example,.env.*.exampleand the.env.<name>files the template itself ships.
Next steps
- Review browser targeting in Browsers available.
- Configure shared defaults in
extension.config.js. - Build for release with
extension build.

