Build & Start

Quick Start

When building or starting the application:

• Development: npm run dev or npm run dev:turbo

• Production Build: npm run build

• Production Start: npm run start

• 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:

• 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:

• Clear .next directory: rm -rf .next

• Clear node_modules: rm -rf node_modules && npm install

• 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

• Check browser console for errors

• Verify environment variables are set

• Check server logs for API errors

• Verify database connections

Slow Build Times

• Use Turbopack: npm run dev:turbo

• Check for large dependencies

• Review bundle analyzer output

• 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