Environment Variables and Configuration

Scopes

Each variable can be set for Production, Preview and Development separately. Use different keys per environment: preview deployments are often shared links, so they must never hold production secrets or write to production data.

Public vs secret

Frameworks expose variables with a special prefix to the browser bundle:

Anything with the public prefix is visible to every visitor. Secrets (API keys, database URLs) must not have the prefix and must only be used in server code (server components, route handlers, functions).

Changing variables

Environment variables are read at build time for static output and at runtime for functions. After changing them, redeploy so the new values take effect.

Project settings worth checking

• Root directory for monorepos (for example apps/web).
• Node.js version to match your local version.
• Build and output settings if auto-detection is wrong.
• Ignored build step to skip deploys when only unrelated files changed.

vercel.json

Optional configuration in the repository:

{
  "redirects": [
    { "source": "/blog/:slug", "destination": "/articles/:slug", "permanent": true }
  ],
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        { "key": "X-Content-Type-Options", "value": "nosniff" },
        { "key": "Referrer-Policy", "value": "strict-origin-when-cross-origin" }
      ]
    }
  ]
}

Framework-level configuration (for example next.config.js redirects and headers) is often preferable because it travels with the app.

Exercise

Add a public variable (an analytics site ID) and a secret (an email API key used in a route handler) with different values for preview and production, and confirm the secret never appears in the browser's JavaScript files.

Check yourself

• Why use different secrets for previews?
• What happens to a variable with the NEXT_PUBLIC_ prefix?
• When do variable changes take effect?