Environment Variables

This page covers how environment variables work in frontend and Node.js projects — naming conventions, the critical distinction between build-time and runtime variables, and how to manage secrets safely in local development, CI/CD, and production. This is the deeper coverage referenced from Web Security Essentials.

.env file naming conventions

File	Purpose	Commit?
`.env`	Shared defaults for all environments	Only if it contains no secrets
`.env.local`	Personal local overrides — never shared	❌ Always gitignore
`.env.development`	Development-only overrides	✅ Safe if no secrets
`.env.production`	Production-only overrides	✅ Safe if no secrets
`.env.test`	Test environment overrides	✅ Safe if no secrets
`.env.example`	Template: all keys, no real values	✅ Always commit
`.env.*.local`	Any `.local` variant	❌ Always gitignore

tip

The .local suffix is the universal gitignore signal. Vite, Next.js, and other frameworks all treat files ending in .local as machine-specific overrides that should never be committed. Add *.local and .env to your .gitignore at project creation.

caution

Committing a .env file is only safe if it contains zero secrets — e.g., VITE_API_BASE_URL=https://api.example.com or NODE_ENV=development. When in doubt, don't commit it. Use .env.example as the documented template instead.

Build-time vs runtime variables

Build-time substitution (Vite, VITE_*): Vite statically replaces import.meta.env.VITE_FOO with the literal string value at build time. The value is embedded in the JavaScript bundle that ships to the browser. Anyone with DevTools can read it. These are public values by design.
Runtime environment variables (Node.js, process.env): The variable exists only in the server process at runtime. The browser never sees it. API keys, database credentials, and tokens must live here — accessed only by your backend.

danger

VITE_ and NEXT_PUBLIC_ prefixes mean public — not "available to the frontend". Values bundled at build time are visible to anyone who opens DevTools → Sources. Never assign a secret to an environment variable with these prefixes. If your frontend needs to call a protected API, proxy the call through your backend instead.

Vite's environment variable handling

Vite includes dotenv and dotenv-expand out of the box — no install needed. It exposes variables to browser code through import.meta.env, but only those prefixed with VITE_.

Load order (highest priority first):

File	Loaded when
`.env.[mode].local`	Always (machine-specific, highest priority)
`.env.[mode]`	Always (mode-specific)
`.env.local`	Always except `test` mode
`.env`	Always (lowest priority)

Default modes: development (dev server), production (build), test (Vitest).
import.meta.env.MODE contains the current mode string.
import.meta.env.DEV and import.meta.env.PROD are built-in booleans.

src/config.ts
// ✅ Correct: VITE_ prefix — available in browser bundle
const apiBase = import.meta.env.VITE_API_BASE_URL;

// ❌ Wrong: no VITE_ prefix — will be undefined in the browser
const secret = import.meta.env.API_SECRET;

TypeScript autocompletion — extend ImportMetaEnv in src/vite-env.d.ts:

src/vite-env.d.ts
/// <reference types="vite/client" />

interface ImportMetaEnv {
  readonly VITE_API_BASE_URL: string;
  // add further VITE_ variables here
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

GitHub Actions secrets

Setting secrets: Repository-level: Settings → Secrets and variables → Actions → New repository secret. For per-environment isolation: Settings → Environments → [env name] → Add secret.
Using in workflows: Reference as ${{ secrets.SECRET_NAME }}. GitHub automatically masks the literal value in all log output.
Fork PR protection: Secrets are not passed to workflows triggered by pull requests from forks — this prevents fork PRs from exfiltrating secrets.

.github/workflows/deploy.yml
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - name: Build
        env:
          VITE_API_BASE_URL: ${{ secrets.VITE_API_BASE_URL }}
        run: npm run build

      - name: Deploy to Cloud Run
        env:
          GCP_SA_KEY: ${{ secrets.GCP_SA_KEY }}
        run: # ... gcloud deploy command

caution

GitHub Actions masks the exact literal string of each secret in logs. It does not mask secrets that are base64-encoded, split across lines, or printed inside a JSON object. Avoid echoing secrets via echo $SECRET or logging full request/response bodies that may contain secret fields.

Production secrets management

For Aliz projects:

GitHub Actions secrets — for build-time values and deploy credentials (GCP service account keys, npm tokens)
Google Cloud Secret Manager — for runtime secrets accessed by Cloud Run services (database passwords, API keys). Secrets are IAM-controlled, versioned, and have audit logs.

Tool	Best for	Notes
GitHub Actions secrets	CI/CD credentials, deploy tokens	Aliz default for CI/CD; no cost; no runtime access
Google Cloud Secret Manager	Cloud Run runtime secrets	IAM-controlled, versioned, audit logs; pairs with Aliz's GCP stack
Doppler	Central dashboard for all envs	SaaS; GitHub Actions + Cloud Run integrations; good for larger teams
HashiCorp Vault	Enterprise / self-hosted	High complexity; best when already in your infrastructure

tip

On Cloud Run, mount a Secret Manager secret directly as an environment variable in the service configuration — no code changes needed. The Cloud Run service account needs the secretmanager.secretAccessor IAM role on the relevant secret.

Rotation and auditing

Rotate secrets on team member departure and on any suspected exposure.
Cloud Audit Logs records every Secret Manager access by identity and time.
GitHub Actions has no native secret access audit log — use environment protection rules (required reviewers for production deployments) as a compensating control.

Common mistakes

Committing .env — the most common mistake. If it happens, the file must be purged from Git history with git filter-repo (not git rm) and every secret in it rotated immediately. Adding .env to .gitignore after the fact does not remove it from history.
Using VITE_* for secrets — a misreading of the prefix as "make this available to my app" rather than "expose this publicly". Variables that need to reach the frontend must be non-secret.
Adding VITE_ to "fix" an undefined process.env — accessing a server-side variable in frontend code. The fix is to move the logic to the backend, not to expose the variable in the bundle.
console.log in CI bypassing log masking — logging an object that contains a secret field (console.log(config)) prints the secret even if GitHub masks the raw literal, because the formatted output differs from the masked string.
Missing .env.example — new developers waste time figuring out which variables are needed, and typos in variable names cause silent failures because process.env.TYPO returns undefined rather than throwing.
Storing secrets in localStorage or sessionStorage — accessible to any JavaScript on the page. XSS directly exfiltrates them. Tokens should live in httpOnly cookies.
Hardcoding secrets as default values — const key = process.env.API_KEY ?? 'sk-real-key-here' defeats the entire point of environment variables and often ends up committed.

.env file naming conventions​

Build-time vs runtime variables​

Vite's environment variable handling​

GitHub Actions secrets​

Production secrets management​

Rotation and auditing​

Common mistakes​

Further Reading​