Tired of your Next.js app’s AI features working locally but breaking on Vercel because of missing API keys? Here’s a senior engineer’s guide to managing environment variables and secrets the right way, from quick fixes to production-grade solutions.

Stop Exposing Your AI Keys: A Senior Engineer’s Guide to Next.js Environment Variables

I remember a frantic Tuesday morning. A PagerDuty alert screams about maxed-out API usage on our OpenAI account. Turns out, a junior engineer, trying to get their new AI feature working on a preview branch, hardcoded an API key and pushed it to a public fork of our repo. We spent the next four hours in a war room, rotating keys, invalidating sessions, and calculating the damage. That little “annoying problem” of getting an API key to work cost us a few thousand dollars in fraudulent usage and a whole lot of trust. This isn’t just an inconvenience; it’s a critical security and operational failure waiting to happen.

The “Why”: Why Your Variables Vanish in the Cloud

The core of this problem isn’t Next.js or Vercel being difficult. It’s about a fundamental misunderstanding of environments. Your laptop is not Vercel’s build server. Your local .env.local file is, by design, never committed to Git. When Vercel pulls your code, that file doesn’t exist. It has its own separate, secure system for managing environment variables.

Furthermore, Next.js has a strict separation between server-side variables (accessible only in API routes, `getServerSideProps`, etc.) and client-side variables (which must be prefixed with NEXT_PUBLIC_). Mixing these up is the second most common reason your app breaks on deployment. Your AI key should NEVER be prefixed with NEXT_PUBLIC_.

The Solutions: From Duct Tape to Fort Knox

Let’s walk through the options, from the quick-and-dirty fix to the way we do it on our production systems.

Solution 1: The Quick Fix (The Manual Sync)

This is the most common approach for personal projects and early-stage startups. It’s simple but relies entirely on manual effort and discipline.

1. Local Setup: You have your .env.local file that you never commit.

   # .env.local (DO NOT COMMIT THIS FILE!)
   OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx"
   DATABASE_URL="postgresql://user:pass@localhost:5432/mydb"

2. Vercel Setup: You go to your Vercel project’s dashboard, navigate to Settings > Environment Variables, and manually add each one. You’ll add OPENAI_API_KEY and DATABASE_URL, copying the values from your local file.

The Catch: It’s a pain. Every time you add a new variable, you have to remember to add it to Vercel. Forget one, and you’ll be debugging a broken deployment. It’s simply not scalable for a team.

Solution 2: The Permanent Fix (CLI Sync & Secrets Management)

This is the professional approach. We treat environment variables as part of the infrastructure, managed via code or a dedicated service. This is the minimum standard for any serious project.

You can use the Vercel CLI to manage variables directly from your terminal, which is much faster and less error-prone than the web UI.

First, install the Vercel CLI: npm i -g vercel

Then, you can add secrets for production, preview, and development environments:

# Add a secret to all environments
vercel env add OPENAI_API_KEY

# Add a secret ONLY to the production environment
vercel env add DATABASE_URL production

To pull down the latest variables for local development (into a new .env.local file):

vercel env pull .env.local

Pro Tip: For even better security and management, especially on a team, integrate a dedicated secrets manager like Doppler, HashiCorp Vault, or AWS Secrets Manager. These services provide versioning, access controls, and automatic rotation, which is what we use for our critical services like `prod-db-01`. Vercel has integrations for many of these, making it the truly robust solution.

Solution 3: The ‘Nuclear’ Option (Runtime Fetching)

Sometimes, you don’t want your secrets sitting in Vercel’s environment variables at all, perhaps due to strict compliance requirements or complex key rotation policies. In this advanced scenario, your application fetches its secrets at runtime (or build time) from a secure vault.

This is a conceptual example of how you might fetch a secret from AWS Secrets Manager inside an API route. You’d only need to store the AWS access credentials in Vercel, not the sensitive AI key itself.

// pages/api/ai-proxy.js
import { SecretsManagerClient, GetSecretValueCommand } from "@aws-sdk/client-secrets-manager";

async function getOpenAIKey() {
  // This logic would be cached in a real app
  const secret_name = "production/MyAiApp/OpenAIKey";
  const client = new SecretsManagerClient({ region: "us-east-1" });
  const command = new GetSecretValueCommand({ SecretId: secret_name });
  
  try {
    const data = await client.send(command);
    if ("SecretString" in data) {
      const secret = JSON.parse(data.SecretString);
      return secret.OPENAI_API_KEY;
    }
  } catch (error) {
    console.error("Failed to fetch secret:", error);
    throw error;
  }
}

export default async function handler(req, res) {
  const apiKey = await getOpenAIKey();
  // ... now use the apiKey to call the OpenAI API
  res.status(200).json({ message: "Success" });
}

This is overkill for a small project, but it’s a pattern we use when an application’s security posture is paramount. It completely decouples the application from the secret’s storage plane.

So, next time you’re building that cool AI feature, take five extra minutes. Think about your environment variables. Your future self—and your company’s finance department—will thank you.

Darian Vance

Lead Cloud Architect & DevOps Strategist

With over 12 years in system architecture and automation, Darian specializes in simplifying complex cloud infrastructures. An advocate for open-source solutions, he founded TechResolve to provide engineers with actionable, battle-tested troubleshooting guides and robust software alternatives.

🤖 Frequently Asked Questions