Hardcoded localhost URLs in Production: A Classic Vibe Coding Bug

Why This Happens in AI-Generated Code

Bolt, Lovable, Cursor, and v0 generate code based on context - and the context they have is your local development environment. When you describe a feature that calls an API, the AI generates a working example with a concrete URL rather than a placeholder. The most concrete, reliable URL it knows about is http://localhost:3000 - the default port for Next.js, Vite, and most Node.js dev servers.

The result is code that works perfectly during local development and breaks completely on first deployment. This is one of the most common support issues for founders deploying AI-generated apps to Vercel or Netlify for the first time.

According to a 2024 Stack Overflow Developer Survey analysis, hardcoded environment-specific configuration is identified as a code smell by 78% of senior engineers but appears in the majority of first-deployment codebases from non-professional developers. For vibe-coded applications, the rate is effectively 100% without deliberate correction.

The Patterns AI Tools Generate

// ❌ BAD - Hardcoded localhost URL in fetch call
const response = await fetch('http://localhost:3000/api/users');

// ❌ BAD - Hardcoded in a constant (slightly better but still wrong)
const API_BASE = 'http://localhost:3000';
const response = await fetch(`${API_BASE}/api/users`);

// ❌ BAD - Hardcoded in Next.js API route
export async function POST(req: Request) {
  const webhookUrl = 'http://localhost:3000/api/webhook/stripe';
  await registerWebhook(webhookUrl);
}

// ❌ BAD - Hardcoded CORS origin in Express/Node.js backend
app.use(cors({ origin: 'http://localhost:3000' }));

// ❌ BAD - Hardcoded database or service URL
const SUPABASE_URL = 'http://localhost:54321';

Each of these patterns causes silent or loud failures in production. The fetch calls return network errors. The CORS configuration rejects all production traffic. The Supabase URL points to a local Docker container that doesn't exist on the production server.

The Correct Pattern: Environment Variables

// ✅ GOOD - Environment variable with fallback for local dev
const API_BASE = process.env.NEXT_PUBLIC_API_URL ?? 'http://localhost:3000';
const response = await fetch(`${API_BASE}/api/users`);

// ✅ GOOD - Server-side environment variable (not exposed to browser)
export async function POST(req: Request) {
  const appUrl = process.env.APP_URL;
  if (!appUrl) throw new Error('APP_URL environment variable is not set');
  await registerWebhook(`${appUrl}/api/webhook/stripe`);
}

// ✅ GOOD - CORS origin from environment variable
app.use(cors({
  origin: process.env.ALLOWED_ORIGIN ?? 'http://localhost:3000'
}));

// ✅ GOOD - .env.local for development, .env.production for production
// .env.local
NEXT_PUBLIC_API_URL=http://localhost:3000
APP_URL=http://localhost:3000

// Vercel dashboard environment variables (production):
NEXT_PUBLIC_API_URL=https://yourapp.vercel.app
APP_URL=https://yourapp.vercel.app

Environment Variable Strategy by Deployment Platform

A critical detail for Next.js: only environment variables prefixed with NEXT_PUBLIC_ are included in the browser-side JavaScript bundle. URLs for client-side fetch calls need the NEXT_PUBLIC_ prefix. URLs used only in server-side code (API routes, Server Components, Server Actions) should not use the prefix, keeping them out of the client bundle entirely.

The .env.example File Pattern

A best practice that AI tools almost never generate is the .env.example file. This is a committed, non-secret file that lists every required environment variable with placeholder values. It serves as documentation for anyone deploying the app:

// ✅ GOOD - .env.example committed to Git
NEXT_PUBLIC_API_URL=https://your-app-domain.com
APP_URL=https://your-app-domain.com
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key-here
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key-here
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...

The actual .env.local file with real values must be in .gitignore. The example file uses placeholder strings so developers know what variables to configure without exposing real credentials.

How to Find and Fix Hardcoded URLs in Your Codebase

1. Search your source files for localhost: Run a text search for localhost across all .ts, .tsx, .js, and .jsx files. Every occurrence in a string literal is a candidate for replacement.
2. Check for port-specific patterns: Look for patterns like :3000, :8080, :4000 - these are almost always hardcoded dev server addresses.
3. Review your .env files: Ensure .env.local, .env.development, and .env.production have the correct values, and that none of them are committed to Git.
4. Run automated scanning: Tools like VibeDoctor (vibedoctor.io) automatically scan your codebase for hardcoded localhost URLs and environment configuration issues (CFG-002, CFG-005, CFG-006, CFG-007) and flag specific file paths and line numbers. Free to sign up.
5. Create .env.example: After identifying all environment variables your app needs, create this file in your project root and commit it. Future deployments become self-documenting.

FAQ