> ## Documentation Index > Fetch the complete documentation index at: https://extension.js.org/llms.txt > Use this file to discover all available pages before exploring further. # Environment variables in browser extensions > Use .env files and browser-specific environment values safely in Chrome, Firefox, and Edge extensions. Keep secrets out of bundled extension code. Use one extension codebase across browsers and environments without hardcoding values. ## 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 compiled `manifest.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` new-env template screenshot

See environment variables in action with a new-tab extension that reads `EXTENSION_PUBLIC_*` values. ```bash npm theme={null} npx extension@latest create my-extension --template=newtab-env ``` ```bash pnpm theme={null} pnpx extension@latest create my-extension --template=newtab-env ``` ```bash yarn 2+ theme={null} yarn dlx extension@latest create my-extension --template=newtab-env ``` ```bash bun theme={null} bunx extension@latest create my-extension --template=newtab-env ``` ```bash deno theme={null} deno run -A npm:extension@latest create my-extension --template=newtab-env ``` Repository: [extension-js/examples/newtab-env](https://github.com/extension-js/examples/tree/main/examples/newtab-env) ### `content-env` content-env template screenshot

Use environment variables inside content scripts injected into web pages. ```bash npm theme={null} npx extension@latest create my-extension --template=content-env ``` ```bash pnpm theme={null} pnpx extension@latest create my-extension --template=content-env ``` ```bash yarn 2+ theme={null} yarn dlx extension@latest create my-extension --template=content-env ``` ```bash bun theme={null} bunx extension@latest create my-extension --template=content-env ``` ```bash deno theme={null} deno run -A npm:extension@latest create my-extension --template=content-env ``` Repository: [extension-js/examples/content-env](https://github.com/extension-js/examples/tree/main/examples/content-env) ## How it works ### Extension bundles (compile time) When building your extension, the compiler chooses **one** env file from your extension package folder by the first match in this order: 1. `.env.[browser].[mode]` (for example, `.env.chrome.development`) 2. `.env.[browser]` 3. Engine-family variants of the two above (see the note below) 4. `.env.[mode]` 5. `.env.local` 6. `.env` Browser-scoped files resolve **per engine family**, matching [browser-specific manifest fields](/docs/features/browser-specific-fields). After the exact browser name, Chromium-family targets (`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 selected file's variables. Finally, **system** `process.env` takes highest precedence for overlapping keys. Selection is a **single** env file from the list above (plus `.env.defaults`), not a full cascade through every file. `.env.example` is documentation only and is never loaded as a value source. 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. 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. **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, weakest to strongest: 1. `.env.defaults` 2. `.env` 3. `.env.local` 4. `.env.development` 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`. Extension.js does **not** use browser-scoped files such as `.env.chrome` or `.env.chrome.development` for this preload step. Instead, set values through plain `process.env` in your shell or continuous integration (CI) pipeline. 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). This split exists because configuration loading is browser-agnostic at file-read time, while the bundler knows the active browser and mode.