Environment Variables in JavaScript Apps: Local Setup, Build-Time Behavior, and Security Tips

Overview

Use this section to build a simple mental model before you touch any configuration files.

An environment variable is a string value supplied by the runtime or deployment environment rather than hardcoded in source code. In JavaScript projects, that usually means one of three things:

• Server runtime variables used by Node.js processes, API servers, CLI tools, jobs, and scripts.
• Build-time variables read while bundling a frontend app, then inlined into the generated client bundle.
• Framework-scoped public variables intentionally exposed to browser code through a naming convention or config layer.

The most important distinction is this: browser code cannot safely read true private environment variables at runtime unless a server provides the value. If a value is bundled into client-side JavaScript, users can usually inspect it. That makes environment-variable handling less about syntax and more about deciding where a value is allowed to exist.

A durable rule set looks like this:

1. Keep secrets on the server. API keys with write access, database credentials, private tokens, signing secrets, and internal URLs should stay in server-only code.
2. Treat frontend env values as public configuration. Base API URLs, feature flags, public analytics IDs, and non-sensitive build labels are reasonable candidates.
3. Separate local defaults from committed examples. Use a real local file that is ignored by version control and a checked-in example file that documents required variables.
4. Validate required variables at startup. Fail early rather than discovering missing configuration after deployment.
5. Document who owns each variable. A small project can survive guesswork; a growing project usually cannot.

If your app also spans multiple tools, lock your runtime versions first. Team-wide differences in Node versions can change startup behavior or package scripts. A separate guide on Node version managers can help standardize that part of the setup.

Checklist by scenario

This is the return-to-it section: pick the scenario that matches your app and work through the checklist before shipping.

1. Node.js backend or script

For backend code, environment variables are typically read from process.env. That gives you runtime configuration without bundling values into public assets.

Checklist:

• Store secrets only in the server environment, not in source files.
• Use a local .env file for development if needed, and load it at process startup.
• Commit a .env.example file with placeholder names and safe sample values.
• Read variables once during startup and centralize them in a config module.
• Validate required variables immediately.
• Convert string values to the types your app expects, such as numbers, booleans, or URLs.

Example pattern:

import 'dotenv/config';

function required(name) {
  const value = process.env[name];
  if (!value) throw new Error(`Missing environment variable: ${name}`);
  return value;
}

export const config = {
  nodeEnv: process.env.NODE_ENV || 'development',
  port: Number(process.env.PORT || 3000),
  databaseUrl: required('DATABASE_URL'),
  jwtSecret: required('JWT_SECRET'),
  logLevel: process.env.LOG_LEVEL || 'info',
  featureXEnabled: process.env.FEATURE_X_ENABLED === 'true'
};

This pattern avoids sprinkling process.env reads throughout the codebase. It also makes testing easier because configuration has one entry point.

2. Frontend app built with a bundler

In a frontend build, env values are often replaced during compilation. That means the final JavaScript bundle contains the values you exposed. If a user can load the app, they can usually inspect those values.

Checklist:

• Expose only non-sensitive values to client code.
• Use the framework or bundler's required public prefix for variables intended for the browser.
• Assume every bundled value is visible to users.
• Keep secret API tokens on your backend and proxy requests if necessary.
• Restart the dev server after changing env files if hot reload does not pick them up.
• Verify values in the built output, not only in local development.

Examples of safe-ish public config:

• Public app name
• Public API base URL
• Analytics measurement ID
• Feature flag labels that do not reveal sensitive internals
• Build environment label such as staging or production

Examples that should stay server-side:

• Database passwords
• JWT signing secrets
• Private third-party API keys
• Webhook secrets
• Internal admin endpoints

3. Vite env variables

Vite is explicit about what reaches the client. Browser-exposed variables usually need a public prefix such as VITE_, and they are read through import.meta.env.

Checklist:

• Use the expected prefix for any variable you want available in browser code.
• Read client variables from import.meta.env, not process.env.
• Do not put secrets in prefixed variables.
• Use separate files for local and environment-specific values if your workflow needs them.
• Test the production build because build-time replacement can differ from dev behavior.

Example:

const apiBaseUrl = import.meta.env.VITE_API_BASE_URL;
const appEnv = import.meta.env.VITE_APP_ENV || 'development';

Vite's model is useful because it forces a clear line between public and private configuration. Even so, the rule remains the same: a prefixed value intended for client code is not secret.

4. Next.js env variables

Next.js projects often mix server and client execution, which makes env handling feel simple until a value crosses the wrong boundary. The key is to decide whether a variable belongs to server-only code or browser code.

Checklist:

• Keep sensitive values in server components, API routes, server actions, or backend-only utilities.
• Use the framework's public prefix only for values you intentionally expose to the browser.
• Audit shared modules to ensure server-only variables are not imported into client code.
• Check both local dev and production deployment behavior.
• Review preview, staging, and production environment settings separately.

Because framework behavior evolves, the safest habit is to think in boundaries: server imports server secrets; client imports public config. If a module is shared across both, treat it with extra care.

5. Full-stack app with frontend and backend in one repo

Monorepos and mixed full-stack apps can become messy if every package names variables differently or redefines the same concept. Establish a convention early.

Checklist:

• Split variables into server-only, client-public, and build/deployment categories.
• Use package-level example files if separate services start independently.
• Create a shared naming scheme such as API_BASE_URL for backend use and a distinct public variant for the frontend.
• Document where each variable is set: local file, CI, container config, host dashboard, or secret manager.
• Avoid reusing private variable names in client packages even if values differ.

A small naming map helps:

server:
  DATABASE_URL
  JWT_SECRET
  INTERNAL_API_TOKEN

client:
  VITE_PUBLIC_API_BASE_URL
  NEXT_PUBLIC_APP_ENV
  PUBLIC_ANALYTICS_ID

6. CI, deployment, and preview environments

Many env-related bugs only appear after a branch is built remotely. The app works locally, but staging points at the wrong service or production is missing one required value.

Checklist:

• Make a list of required variables per environment.
• Keep local, test, staging, preview, and production values separate.
• Never assume a variable available locally exists in CI.
• Add startup validation to fail builds or boot processes early.
• Use deployment-specific secrets storage rather than committing real values.
• Rebuild after changing build-time variables; a simple restart may not be enough.

If configuration differences are causing subtle behavior changes, tools that compare JSON or config output can help isolate drift. A practical companion is this guide to JSON diff tools.

What to double-check

Before merging or deploying, review these items. They catch a large share of real-world mistakes.

Variable visibility

• Is this value meant for server code only?
• If it appears in browser code, are you comfortable with users seeing it?
• Did a shared utility accidentally pull a private variable into a client bundle?

Build-time versus runtime behavior

• Does the value get read during bundling or when the server process starts?
• If you changed a build-time variable, did you actually rebuild the app?
• Are you expecting runtime changes in a static frontend that cannot see them without a rebuild?

Type conversion

Every environment variable starts as a string. That creates quiet bugs.

• "false" is still a non-empty string unless you parse it.
• Ports and timeouts need number conversion.
• JSON blobs need parsing and error handling.
• URLs should be validated if they control network calls.

Good pattern:

const isEnabled = process.env.FEATURE_FLAG === 'true';
const timeoutMs = Number(process.env.TIMEOUT_MS || 5000);
if (Number.isNaN(timeoutMs)) throw new Error('Invalid TIMEOUT_MS');

File handling

• Is .env ignored by version control?
• Did you commit only the example file and not real secrets?
• Are local overrides documented for other developers?

Naming consistency

• Do variable names explain scope and purpose?
• Are public variables clearly marked as public?
• Do different apps in the repo use the same name for the same idea?

Developer onboarding

• Can a new team member clone the repo and know what to set?
• Does the README explain required variables and where to obtain them?
• Is there a startup error message that points to the missing config rather than failing later with a vague network error?

Common mistakes

These are the issues worth checking first when environment variables behave strangely.

Putting secrets in frontend env variables

This is the most important mistake. If a key is bundled into client code, it should be treated as exposed. Public identifiers are fine; private credentials are not. When a browser needs access to protected data, route the request through your server or an authenticated backend layer instead.

Expecting runtime changes in a statically built frontend

Many frontend apps read env variables during build, not every time a user loads the page. If you update the deployment environment but do not rebuild, the app may continue using stale values.

Using process.env everywhere

Direct reads scattered across dozens of files make debugging harder and testing inconsistent. Centralized config modules are easier to validate, mock, and review.

Forgetting that all values are strings

Boolean flags and numeric settings often fail silently when not parsed. Be especially careful with values such as 0, false, and empty strings.

Committing real env files

A leaked .env file creates cleanup work far beyond one repository. Even in private projects, assume committed secrets may need rotation. Safer practice is to commit a template and keep real values in ignored local files or managed secrets storage.

Different variable names across environments

If local uses API_URL, staging uses APP_API_URL, and production uses SERVICE_URL, someone will eventually wire the wrong one. Pick one name and use it consistently.

Hiding configuration bugs behind CORS or network errors

Frontend misconfiguration often shows up as failed API calls. The visible error may look like a CORS problem when the underlying issue is simply the wrong base URL or missing token. If debugging gets messy, this CORS error fix guide is a useful companion.

When to revisit

Do not treat env setup as a one-time task. Revisit it whenever the inputs change, especially before releases, migrations, or tooling updates.

Review your environment-variable setup when:

• You add a new deployment target such as staging, preview, or region-specific hosting.
• You adopt a new framework, bundler, or hosting platform.
• You move logic from client to server or from server to edge/runtime-specific code.
• You integrate a third-party service that introduces new keys, callbacks, or endpoints.
• You rotate secrets or change access scopes.
• You rename packages, split a monolith, or create a monorepo.
• You onboard new developers and setup friction becomes obvious.
• You prepare for seasonal planning or a broader infrastructure cleanup.

Practical maintenance checklist:

1. Open your .env.example file and remove dead variables.
2. Verify every required variable is documented with a short purpose note.
3. Confirm ignored local files are still ignored.
4. Run a production build and inspect which values are present in client output.
5. Check startup validation messages for clarity.
6. Rotate any secret that may have been exposed through logs, commits, or client bundles.
7. Review public prefixes and confirm they are used only for intentionally exposed values.
8. Update team docs so setup instructions match the current workflow.

A reliable environment-variable strategy is not about memorizing one framework's current syntax. It is about preserving a few stable principles: know where code runs, decide what can be public, validate configuration early, and keep docs close to the code. If you follow that checklist, your setup will remain understandable even as JavaScript tooling changes.