Bolt.new Production Deployment - Technical Reference

Core Problem Analysis

Environment Mismatch

• WebContainer vs Real Servers: WebContainer runs Node.js in browser with different file systems, networking rules, and environment handling
• Impact: Development code fails in production due to different assumptions
• Failure Rate: 30-50% of deployments fail on first attempt

AI-Generated Code Issues

• Assumption Failures: AI assumes npm packages are installed, makes localhost API calls, uses inconsistent import paths
• Case Sensitivity: AI creates imports that work in development but fail on Linux production servers
• Missing Production Configs: No production environment variables, error boundaries, or CDN optimization

Critical Deployment Failures and Solutions

Build Failures

TypeError: fetch failed

• Cause: API calls to localhost or relative URLs that don't exist in production
• Detection: Look for fetch('/api/users') or fetch('http://localhost:3000/api')
• Fix: Replace with fetch(${process.env.NEXT_PUBLIC_API_URL}/api/users)
• Time to Fix: 30 minutes

Module not found errors

• Cause: Case sensitivity differences (WebContainer vs Linux servers)
• Detection: Import ./Component when file is ./component
• Fix: Verify exact filename and path case sensitivity
• Time to Fix: 1-2 hours for complex projects

Blank/white screen deployment

• Cause: JavaScript errors not shown in build logs, usually import path issues
• Detection: Check browser console on deployed site
• Fix: Correct import paths and verify index.html bundle references
• Time to Fix: 2-4 hours

Runtime Failures

Environment variables undefined

• Cause: WebContainer auto-loads variables that don't exist in production
• Detection: process.env.SUPABASE_KEY is undefined
• Fix: Set environment variables in deployment platform, use NEXT_PUBLIC_ prefix for client-side
• Time to Fix: 30 minutes

CORS policy blocks

• Cause: WebContainer doesn't enforce CORS like real browsers
• Detection: Access to XMLHttpRequest blocked by CORS policy
• Fix: Configure API server to allow production domain, update Supabase allowed origins
• Time to Fix: 1 hour

Database connection failures

• Cause: Localhost connection strings or IP range restrictions
• Detection: ECONNREFUSED or connection timeout errors
• Fix: Update to production database URLs, verify IP allowlists
• Time to Fix: 1-2 hours

Platform Success Rates and Issues

Platform	Success Rate	Common Issues	Fix Time
Netlify	70% first try	Environment variables, build commands	2 hours
Vercel	85% first try	API routes, serverless functions	1 hour
GitHub Pages	50% (static only)	No SSR, no APIs	4 hours
Railway	90% once configured	Initial setup complexity	3 hours
Render	85% reliable	Slower cold starts	2 hours

Nuclear Options (Last Resort Fixes)

Complete Rebuild Strategy

• When: Codebase too tangled with WebContainer assumptions
• Process:
  1. Export and analyze working vs broken components
  2. Start with production template (Create Next App/Vite)
  3. Port components individually
• Time Investment: 2-3 hours vs days of debugging
• Success Rate: 95%

Manual Deployment Bypass

• Static Sites: npm run build → upload build folder
• Next.js: npm run build && npm run export → deploy out folder
• Node.js: Push to GitHub → connect to Railway/Render
• Reliability: Higher than automated Bolt.new deployment

Environment Variable Audit

grep -r "process.env" . --include="*.js" --include="*.ts" --include="*.jsx" --include="*.tsx"
grep -r "import.meta.env" . --include="*.js" --include="*.ts"

• Purpose: Find all environment variable references
• Common Issue: 50% of deployment failures from missing/incorrect env vars

Dependency Cleanup

npm ls --depth=0
# Remove WebContainer-specific packages
npm uninstall <suspicious-package>

• Common Culprits: Packages assuming Node.js APIs in browser, dev-only packages in production

Critical Performance Thresholds

Build Time Limits

• Netlify: 15-minute build timeout
• Vercel: 10-minute hobby plan limit
• Impact: Large dependencies cause build failures

Bundle Size Impact

• UI Breaking Point: 1000+ spans make debugging distributed transactions impossible
• Performance Degradation: Bundle sizes >5MB cause slow initial loads
• Mobile Impact: Large bundles fail on 3G connections

Resource Requirements

Time Investment

• Simple Fix: 30 minutes - 1 hour (env vars, CORS)
• Complex Debugging: 2-4 hours (import paths, database)
• Nuclear Rebuild: 2-3 hours (vs days of debugging)
• Platform Migration: 1-3 hours depending on complexity

Expertise Requirements

• Basic: Understanding of environment variables, API endpoints
• Intermediate: Knowledge of build systems, import/export syntax
• Advanced: Linux file systems, server networking, database configuration

Hidden Costs

• Human Time: Debugging WebContainer differences requires manual inspection
• Platform Migration: May need to switch deployment platforms mid-project
• Database Recreation: Often requires manual schema rebuilding

Decision Criteria

When to Use Nuclear Options

• Rebuild: >4 hours spent debugging with no progress
• Manual Deployment: Automated deployment fails 3+ times
• Platform Switch: Current platform success rate <70%

Platform Selection Factors

• Vercel: Best for Next.js projects (85% success rate)
• Railway: Most reliable for full-stack apps (90% success)
• Netlify: Good for static sites with some backend (70% success)
• Avoid GitHub Pages: Unless purely static (50% success)

Critical Warnings

Production Readiness Gaps

• No Error Boundaries: Applications crash completely on errors
• Missing Monitoring: No visibility into production failures
• Hardcoded Values: Development URLs and keys in production code
• Insufficient Testing: Code works in WebContainer but fails under load

Breaking Points

• File System: Case-sensitive imports fail on Linux
• Networking: Localhost calls fail in serverless environments
• Environment: Missing variables cause silent failures
• Dependencies: WebContainer-specific packages break in production

Migration Pain Points

• Database Schemas: AI-generated schemas may have subtle production issues
• API Integration: Localhost assumptions require complete reconfiguration
• Build Configuration: WebContainer magic doesn't translate to real build systems
• Performance: What works for demos fails under real user traffic