Frontend Environment Variables: Configure Vite, Next.js, and Node Apps Without Leaking Secrets

Overview

An environment variable is a named value supplied outside an application’s source code. In local development, it may come from a .env file. In a deployment, it may be configured in a hosting dashboard, a container definition, a CI workflow, or the server process itself.

The most important distinction is whether the value is used by browser code or server code. Anything sent to a browser can be inspected by users through built JavaScript, source maps, network requests, or browser developer tools. A public API base URL, analytics identifier, or non-sensitive feature flag may be appropriate for frontend exposure. A database password, private API key, signing secret, or service credential is not.

Frontend frameworks usually replace public variables during the build. That means changing a hosting variable after a static build has been generated may not change the already-built JavaScript. You may need to rebuild and redeploy. Server-side Node code can instead read variables when the process starts, depending on the deployment setup.

Prefixes are conventions enforced by the framework or build tool, not security mechanisms by themselves. Treat every value with a public prefix as public.

Checklist by scenario

When configuring a Vite app

1. Put browser-safe values in a file such as .env.local using the VITE_ prefix.
2. Read them with import.meta.env.VITE_API_URL, not process.env.VITE_API_URL.
3. Restart the development server after changing a .env file.
4. Keep secrets in a separate backend or server-side function. Removing the prefix does not make a value available to browser code.
5. Check the selected mode when using files such as .env.production or .env.development.

Vite loads general and mode-specific files, with local variants intended for machine-specific values. Existing environment variables supplied by the process can also take precedence. Check the Vite documentation for the exact loading order used by the version in your project when values appear to be overridden.

When configuring a Next.js app

1. Use NEXT_PUBLIC_ only for values that may be embedded in browser code.
2. Read server-only values in server components, route handlers, server actions, or other server-side execution contexts according to your application architecture.
3. Do not assume that a variable is private merely because it is read in a component. A component that runs in the browser cannot safely access a secret.
4. Configure production variables in the deployment environment and rebuild when public values are embedded at build time.
5. Use separate values for development, preview, and production where the environments have different services or permissions.

Next.js supports several environment file names and applies environment-specific precedence rules. The practical rule is to avoid storing real production secrets in committed files, use local-only files for developer overrides, and verify the framework version’s loading behavior during an upgrade.

When configuring a Node application

1. Define required settings such as PORT, database URLs, and private service credentials in the process environment or an approved secret store.
2. If you use a .env loader, initialize it before importing modules that read configuration.
3. Validate required variables at startup and fail with a clear error rather than allowing an undefined value to travel into a database or external request.
4. Keep server configuration separate from values returned by API endpoints or rendered into HTML.
5. Document variable names and safe examples in a file such as .env.example, without including real credentials.

A Node server can read runtime configuration when it starts, but the behavior still depends on how the process is launched and deployed. Test the same startup path used by production instead of relying only on a local shell.

What to double-check

• Build versus runtime: Determine whether a value is substituted during bundling or read when a server starts. Static frontend output generally requires a rebuild for public values to change.
• Correct prefix: Confirm the framework-specific prefix and access syntax. A correctly named variable used with the wrong API often appears as undefined.
• File location and mode: Check that the file is at the project root expected by the tool and that the active command uses the mode you intended.
• Precedence: Look for a shell variable, hosting dashboard setting, or mode-specific file that overrides the value you edited.
• Formatting: Watch for accidental spaces, unmatched quotes, line breaks, and values containing characters that need quoting. Do not print sensitive values while debugging.
• Availability: Confirm the variable exists in the actual build environment, not just on your laptop. CI and hosting systems often have separate settings for build and runtime.
• Type and validation: Environment variables arrive as strings. Parse ports, booleans, lists, and numeric limits explicitly, and validate URLs before using them.

For frontend debugging, browser developer tools can show the final network URL and the generated application behavior. They cannot make a private credential safe to expose. For related debugging workflows, see the React DevTools guide and the JSON formatter and validator guide.

Common mistakes

Putting a secret behind a public prefix

A prefix changes exposure behavior; it does not encrypt a value. If a secret has reached a client bundle, remove it from the application, revoke or rotate it, inspect logs and build artifacts, and replace it with a server-side proxy or controlled backend operation.

Committing local environment files

Keep personal and production files out of version control where they contain credentials. Commit a sanitized example containing variable names and placeholder values. Also check generated archives, CI logs, screenshots, and copied configuration when investigating an accidental disclosure.

Expecting a frontend change without rebuilding

Changing a hosting dashboard value does not necessarily modify an existing static bundle. Confirm whether the platform injects values at runtime or during its build step, then rebuild if required.

Using one API key in every environment

Separate development, preview, and production credentials where the service supports it. Limit permissions and scope, and avoid placing privileged credentials in a browser request merely because the request is convenient.

Debugging only with logs

Logging the complete configuration can expose secrets. Prefer logging the variable name, whether it is present, and a non-sensitive characteristic such as the selected mode. Never include tokens, passwords, or full connection strings.

When to revisit

Use this checklist before every production deployment, environment migration, framework upgrade, or incident review. Revisit it when your app changes from a client-only SPA to a server-rendered application, when a new preview environment is added, or when an API moves behind a proxy. It is also worth reviewing before seasonal planning cycles if deployment ownership, hosting, or secret-management workflows change.

Before acting, complete these final checks:

1. List every required variable and mark it as public, server-only, or build-system configuration.
2. Confirm prefixes, access syntax, file precedence, and the active mode for the framework version in use.
3. Inspect the built assets and source maps for accidental secrets, without uploading sensitive files to an untrusted online tool.
4. Verify that CI, hosting, and local development each provide the required values through the intended path.
5. Test an intentional missing-variable failure so configuration errors are detected early.
6. Rotate any credential that may have been exposed, then document the change and update the sanitized example file.

Environment variables are most useful when treated as an explicit configuration contract rather than a hidden collection of strings. Naming conventions, exposure boundaries, validation, and deployment checks make that contract easier to maintain as a React or Node application grows.