A Practical Guide to Environment Variables and Secrets

A configuration value tells an application where or how to run. A secret grants authority. An API base URL and an API credential may sit beside each other in a setup screen, but they should not receive the same treatment. Before creating another environment file, classify each value by what a person could do if they obtained it. This guide shows how to keep setup understandable while reducing accidental exposure.

Make a configuration inventory

Write down variable name, purpose, consumer, sensitivity, owner, and source. Consumer means the process that needs the value: browser build, web server, background worker, or deployment job. Avoid placing actual secrets in the inventory. A row for PAYMENT_API_KEY can explain its purpose and retrieval location without containing the credential itself. Add the environment it belongs to so staging and production do not become interchangeable by accident.

Separate settings into public configuration, operational configuration, and credentials. Public configuration might include an application origin. Operational configuration might include a queue name or timeout. Credentials include passwords, signing keys, and bearer tokens. The categories are a practical editorial method; sensitivity still depends on your system. An internal hostname may deserve restricted access even when it cannot authorize a request by itself.

Keep a sample file with harmless values and comments about required formats. Explain whether an empty value is valid, how booleans are parsed, and what units a timeout uses. Startup validation should name missing variables without printing their values. Failing early with a useful error is easier to diagnose than an application that starts successfully and fails only when the first customer reaches a particular feature.

Understand the browser boundary

Vite's environment-variable documentation explains that variables prefixed with VITE_ are exposed to client code, are strings, and are replaced during bundling. That makes them suitable for public configuration, not confidential API credentials. A variable stored in a private build environment can still become public if the build inserts it into a downloaded bundle.

Draw the flow from secret storage to runtime. If the browser needs to call a service using a confidential credential, introduce an appropriate server-side boundary rather than disguising the key in JavaScript. The server must still authorize the caller and constrain the requested operation. A proxy that forwards arbitrary URLs with an administrator key merely moves the exposure into a more powerful form.

1. List variable names, owners, consumers, and sensitivity without values.
2. Keep public build settings separate from server credentials.
3. Provision environment-specific access through an approved channel.
4. Validate presence and format without logging the secret.
5. Practice replacement and revocation, then document emergency access.

Manage authority across the whole lifecycle

OWASP's secrets-management guidance covers creation, rotation, revocation, expiration, and auditing. It recommends minimum privileges and revoking secrets that are no longer needed or may be compromised. Treat these as lifecycle requirements rather than assuming a protected file solves everything. Different credential types have different replacement mechanisms and acceptable lifetimes.

For a small service, use the hosting platform's supported secret facility or another managed system your team can operate reliably. Limit access to the applications and people that need it. Keep development credentials separate from production credentials, and avoid a single shared administrator key for every automation. An access inventory should show what breaks if a credential is disabled and which owner can replace it.

Plan replacement as a sequence. Provision the replacement, update the intended consumer, verify the specific operation, and revoke the previous credential when the provider's model permits that overlap. Some systems require a different order or have no overlap, so inspect the provider instructions. Do not automatically apply a generic rotation schedule to every password, signing key, or certificate without considering its semantics.

A hypothetical email worker

Imagine a hypothetical background worker that sends account-verification messages. It needs a mail-service credential and a public website origin. The browser needs only the public origin. The team places the origin in public build configuration and delivers the mail credential only to the worker. A sample configuration contains MAIL_API_KEY=example-not-a-real-key and explains where an authorized operator obtains the real value.

The worker's startup check confirms that the key exists but logs only that configuration validation succeeded. A synthetic delivery exercise uses a test inbox and records the provider message identifier rather than the credential or full message body. These are proposed checks, not claims of a completed delivery. If a key appears in an error report, the response starts by restricting its authority, not by merely deleting the visible report.

The team also asks how the worker behaves when the secret service is unavailable. A cached value may keep an existing process running while a newly started instance cannot initialize. That operational difference belongs in the recovery notes. Emergency access should be deliberate, limited, and auditable; otherwise the unofficial workaround becomes a second, poorly maintained secret-distribution system.

Checklist for the next configuration change

• Identify the exact process that consumes each value.
• Confirm whether the build embeds the value into public files.
• Keep real credentials out of sample files, tickets, screenshots, and logs.
• Use separate environments and the smallest practical permissions.
• Validate required variables and document types and units.
• Document replacement, revocation, and affected consumers.
• Review recovery access when the main credential service is unavailable.

Environment variables are a delivery mechanism, not a universal vault. Their suitability depends on platform access controls, process visibility, diagnostics, and runtime behavior. The durable habit is to follow a value from creation to deletion and ask who can read it or act with it at every step. That produces a setup another maintainer can understand without spreading its authority.