build-start（构建开始）

Build & Start

Quick Start

When building or starting the application:

1. Development: npm run dev or npm run dev:turbo
2. Production Build: npm run build
3. Production Start: npm run start
4. Vercel Build: npm run build:vercel

Commands

Development Server

# Standard development server
npm run dev

# Development with Turbopack (faster)
npm run dev:turbo

Port: 3000 (default) Features: Hot reload, error overlay, fast refresh

Production Build

# Standard production build
npm run build

# Vercel-optimized build
npm run build:vercel

Output: .next directory Time: Typically 20-60 seconds Verification: Check for build errors and warnings

Production Server

# Start production server
npm run start

Port: 3000 (default) Environment: Requires NODE_ENV=production

Deploy y caché (Vercel)

Después del deploy, para que los assets y el HTML se actualicen rápido en todos los dispositivos:

# Purgar CDN + Data Cache (requiere Vercel CLI y vercel login)
npm run cache:purge

• Panel Vercel: Settings → Caches → Purge CDN Cache + Purge Data Cache.
• Assets: Las URLs de tenant llevan ?v=<commit-sha> (cache busting); /images y /tenants tienen caché 24h. Ver docs/CACHE_PURGE_ANTES_DEPLOY.md.
• Flujo recomendado: deploy → luego npm run cache:purge (o purgar desde el panel).

Build Process

Pre-build Steps

The build process includes automatic pre-build steps:

1. React Cache Polyfill: scripts/create-react-cache-polyfill.js

- Creates polyfill for react/cache compatibility - Required for Next.js 16 compatibility

Build Configuration

Key build settings in next.config.js:

• TypeScript: Build errors ignored (temporary)
• Compiler: Console removal in production
• Output: Optimized for Vercel deployment
• Bundle Analyzer: Enabled with ANALYZE=true
• Cache busting: NEXT_PUBLIC_ASSETS_VERSION (desde VERCEL_GIT_COMMIT_SHA en Vercel) para que las URLs de assets de tenant cambien en cada deploy

Common Build Issues

TypeScript Errors

If TypeScript errors block the build:

# Check TypeScript errors
npx tsc --noEmit

# Build ignores TypeScript errors (configured in next.config.js)
npm run build

Memory Issues

If build fails due to memory:

# Increase Node memory limit
NODE_OPTIONS="--max-old-space-size=4096" npm run build

Module Resolution Errors

If you see module resolution errors:

1. Clear .next directory: rm -rf.next
2. Clear node_modules: rm -rf node_modules && npm install
3. Rebuild: npm run build

Verification Checklist

After building:

• Build completes without errors
• No critical warnings in console
• .next directory created successfully
• Production server starts correctly
• Pages load without runtime errors
• Environment variables loaded correctly

Environment Variables

Required for production build:

• NEXT_PUBLIC_* variables (exposed to client)
• Database connection strings
• API keys and secrets
• Tenant configuration

Check .env.local.example for required variables.

Performance Targets

• Build Time: < 20s (target)
• First Load JS: < 500KB
• Bundle Size: Optimized with code splitting

Troubleshooting

Build Fails with React Cache Error

# Ensure polyfill script runs
node scripts/create-react-cache-polyfill.js
npm run build

Build Succeeds but Runtime Errors

1. Check browser console for errors
2. Verify environment variables are set
3. Check server logs for API errors
4. Verify database connections

Slow Build Times

1. Use Turbopack: npm run dev:turbo
2. Check for large dependencies
3. Review bundle analyzer output
4. Consider incremental builds

Key Files

• next.config.js - Build configuration (incl. env NEXT_PUBLIC_ASSETS_VERSION)
• package.json - Build scripts (cache:purge para purgar caché Vercel)
• scripts/create-react-cache-polyfill.js - Pre-build script
• docs/CACHE_PURGE_ANTES_DEPLOY.md - Guía purga de caché y actualización de assets
• .env.local - Environment variables