# How to Configure Environment Variables Using the @extension/env Package

> Learn how to configure environment variables with @extension/env for your Chrome extension. Load .env files and override with CLI flags for type-safe access to constants like IS_DEV.

- Repository: [JongHak Seo/chrome-extension-boilerplate-react-vite](https://github.com/jonghakseo/chrome-extension-boilerplate-react-vite)
- Tags: how-to-guide
- Published: 2026-03-05

---

**The `@extension/env` package centralizes environment management by loading `.env` files prefixed with `CEB_`, supporting CLI overrides via `CLI_CEB_` flags, and exporting typed constants like `IS_DEV` for type-safe access throughout your Chrome extension codebase.**

The `jonghakseo/chrome-extension-boilerplate-react-vite` repository streamlines Chrome extension development through a monorepo architecture where environment configuration is isolated in a dedicated package. When you configure environment variables using the `@extension/env` package, you gain validation, TypeScript autocomplete, and runtime safety across content scripts, background workers, and popup components. The package uses `@dotenvx/dotenvx` internally and enforces strict naming conventions to prevent collisions with system variables.

## Defining Variables in the .env File

All extension-specific environment variables must use the **`CEB_`** prefix to be recognized by the validation logic. This naming convention ensures that only intended values are injected into the build while keeping system environment variables separate.

### The CEB_ Prefix Requirement

Create or edit the `.env` file in the repository root and add your variables:

```bash
CEB_API_KEY=your_secret_key_here
CEB_API_ENDPOINT=https://api.example.com
CEB_DEBUG_MODE=true

```

Without the `CEB_` prefix, variables are ignored by the loading mechanism in [`packages/env/lib/config.ts`](https://github.com/jonghakseo/chrome-extension-boilerplate-react-vite/blob/main/packages/env/lib/config.ts).

### Configuration Loading Mechanism

The package loads these values at build time through **[`packages/env/lib/config.ts`](https://github.com/jonghakseo/chrome-extension-boilerplate-react-vite/blob/main/packages/env/lib/config.ts)**, which uses `@dotenvx/dotenvx` to parse the file:

```ts
// packages/env/lib/config.ts
import { config } from '@dotenvx/dotenvx';
export const baseEnv = config({
  path: `${import.meta.dirname}/../../../../.env`,
}).parsed ?? {};

```

This `baseEnv` object becomes the foundation for all derived constants and type definitions exported by the package.

## Overriding Values from the Command Line

For temporary overrides during development or CI/CD pipelines, the repository supports CLI-based environment injection without modifying the `.env` file permanently.

### Using CLI_CEB_ Prefixes

Pass variables with the **`CLI_CEB_`** prefix to override values for a single command execution. These take precedence over the `.env` file but do not persist after the script completes.

```bash
pnpm set-global-env CLI_CEB_API_KEY=tmp_staging_key
pnpm dev

```

Valid boolean flags include `CLI_CEB_DEV` and `CLI_CEB_FIREFOX`, which control build-time behavior.

### The set-global-env Helper Script

The **[`bash-scripts/set_global_env.sh`](https://github.com/jonghakseo/chrome-extension-boilerplate-react-vite/blob/main/bash-scripts/set_global_env.sh)** script validates the prefix and rewrites the `.env` file temporarily to place CLI values under a dedicated read-only section. This script checks for the `CLI_CEB_` pattern and validates boolean flags before injection, ensuring that only approved configuration keys reach the build process.

## Accessing Environment Variables in Extension Code

Once defined, you can access these values through two primary mechanisms: direct `process.env` access for arbitrary keys or typed imports for common boolean flags.

### Direct process.env Access

Any variable starting with `CEB_` is available on `process.env` with full TypeScript autocomplete support:

```ts
// src/feature.ts
console.log(process.env.CEB_API_KEY);
// Alternative syntax for dynamic keys
console.log(process.env['CEB_API_ENDPOINT']);

```

As documented in **[`packages/env/README.md`](https://github.com/jonghakseo/chrome-extension-boilerplate-react-vite/blob/main/packages/env/README.md)**, both bracket and dot notation work correctly within the Vite build system.

### Typed Boolean Constants

For frequently checked flags, import typed constants from **[`packages/env/lib/const.ts`](https://github.com/jonghakseo/chrome-extension-boilerplate-react-vite/blob/main/packages/env/lib/const.ts)**:

```ts
import { IS_DEV, IS_FIREFOX, IS_PROD, IS_CI } from '@extension/env';

if (IS_DEV) {
  console.log('Development mode active');
}

if (IS_FIREFOX) {
  // Firefox-specific polyfills
}

```

These constants are derived from CLI flags and environment values:

```ts
// packages/env/lib/const.ts
export const IS_DEV = process.env['CLI_CEB_DEV'] === 'true';
export const IS_PROD = !IS_DEV;
export const IS_FIREFOX = process.env['CLI_CEB_FIREFOX'] === 'true';
export const IS_CI = process.env['CEB_CI'] === 'true';

```

### Dynamic Derived Values

You can compute complex environment values in **[`packages/env/lib/index.ts`](https://github.com/jonghakseo/chrome-extension-boilerplate-react-vite/blob/main/packages/env/lib/index.ts)** by extending the `dynamicEnvValues` object. The default implementation sets `CEB_NODE_ENV` based on the `CEB_DEV` flag:

```ts
// packages/env/lib/index.ts
export const dynamicEnvValues = {
  CEB_NODE_ENV: baseEnv.CEB_DEV === 'true' ? 'development' : 'production',
} as const;

```

Add custom derived keys here to expose computed URLs, version strings, or feature flags. These values become part of the exported `EnvType` defined in **[`packages/env/lib/types.ts`](https://github.com/jonghakseo/chrome-extension-boilerplate-react-vite/blob/main/packages/env/lib/types.ts)**.

## Build Script Integration

The root [`package.json`](https://github.com/jonghakseo/chrome-extension-boilerplate-react-vite/blob/main/package.json) wires the environment helper into standard npm scripts to ensure flags are populated before Vite executes:

- **`pnpm dev`** runs `pnpm set-global-env CLI_CEB_DEV=true && pnpm base-dev`
- **`pnpm build`** runs `pnpm set-global-env && pnpm base-build`
- **`pnpm build:firefox`** runs `pnpm set-global-env CLI_CEB_FIREFOX=true && pnpm base-build`

These commands guarantee that `IS_DEV` and `IS_FIREFOX` are correctly set during the build lifecycle, enabling conditional compilation and runtime branching.

## Summary

- **Prefix requirement**: All custom variables must start with `CEB_` in the `.env` file to be loaded by [`packages/env/lib/config.ts`](https://github.com/jonghakseo/chrome-extension-boilerplate-react-vite/blob/main/packages/env/lib/config.ts).
- **CLI overrides**: Use `CLI_CEB_` prefixes with `pnpm set-global-env` to temporarily override values without editing files.
- **Typed access**: Import `IS_DEV`, `IS_FIREFOX`, and other booleans from `@extension/env` for type-safe runtime checks.
- **Dynamic values**: Extend `dynamicEnvValues` in [`packages/env/lib/index.ts`](https://github.com/jonghakseo/chrome-extension-boilerplate-react-vite/blob/main/packages/env/lib/index.ts) to expose computed environment properties.
- **Build integration**: The `set-global-env` script runs automatically via `pnpm dev` and `pnpm build` to ensure consistent environment state.

## Frequently Asked Questions

### How do I add a new environment variable to the Chrome extension?

Add the variable to your root `.env` file with the `CEB_` prefix, such as `CEB_NEW_FEATURE=true`. The `@dotenvx/dotenvx` loader in [`packages/env/lib/config.ts`](https://github.com/jonghakseo/chrome-extension-boilerplate-react-vite/blob/main/packages/env/lib/config.ts) will automatically pick it up, and you can access it via `process.env.CEB_NEW_FEATURE` in any extension script.

### What is the difference between CEB_ and CLI_CEB_ prefixes?

Variables with the `CEB_` prefix are read from the `.env` file and represent persistent configuration. The `CLI_CEB_` prefix is used for temporary overrides passed through the command line via `pnpm set-global-env`, which rewrites the environment only for the current command execution without persisting changes to the repository.

### Can I use process.env directly instead of importing from @extension/env?

Yes, direct `process.env` access works for any `CEB_` prefixed variable, and the package provides TypeScript definitions for autocomplete. However, importing typed constants like `IS_DEV` from `@extension/env` is recommended for boolean flags because they provide compile-time type safety and cleaner syntax than checking `process.env['CLI_CEB_DEV'] === 'true'` manually.

### Where are the TypeScript types for environment variables defined?

The type definitions live in **[`packages/env/lib/types.ts`](https://github.com/jonghakseo/chrome-extension-boilerplate-react-vite/blob/main/packages/env/lib/types.ts)**, which exports `EnvType` combining `baseEnv` and `dynamicEnvValues`. This ensures that TypeScript knows which keys are available on `process.env` when you import the package, enabling IntelliSense autocomplete for custom `CEB_` variables you add to the system.