//
Busca en todas las páginas de la documentación
Comandos de terminal que todo desarrollador de React, TypeScript y Node.js necesita — gestión de paquetes, configuración del entorno, herramientas de compilación y depuración.
Tarjeta de referencia rápida lista para copiar y pegar.
# Gestión de paquetes
npm install # instalar todas las dependencias
npm install zod # agregar una dependencia
npm install -D vitest # agregar una dependencia de desarrollo
npm run dev # iniciar servidor de desarrollo
npm run build # compilación de producción
# Gestión de versiones de Node
nvm install 22 # instalar Node 22
nvm use 22 # cambiar a Node 22
node -v # verificar versión de Node
# Entorno
export PORT=3001 # establecer variable de entorno para esta sesión
cat .env.local # ver archivo de entorno
echo $NODE_ENV # verificar entorno actual
# Comprobaciones rápidas
npx tsc --noEmit # type-check sin compilar
npx next lint # ejecutar linter
npx vitest run # ejecutar pruebas una vezCuándo usarlo: Flujo de trabajo de desarrollo diario — instalación de paquetes, gestión de versiones de Node, ejecución de compilaciones, comprobación de tipos y depuración de problemas.
# Configurar un nuevo proyecto Next.js desde cero
npx create-next-app@latest my-app --typescript --tailwind --app --src-dir
cd my-app
npm install zustand zod react-hook-form @hookform/resolvers
npm install -D vitest @testing-library/react
npm run dev
# Aplicación ejecutándose en http://localhost:3000Lo que esto demuestra:
npx ejecuta un paquete sin instalarlo globalmenteinstall e install -D separados para dependencias de runtime vs desarrollo# Instalar
npm install # instalar desde package.json
npm install --legacy-peer-deps # resolver conflictos de dependencias pares
npm ci # instalación limpia (usa el lockfile exactamente, más rápido en CI)
# Agregar/eliminar paquetes
npm install lucide-react # agregar dependencia
npm install -D prettier # agregar dependencia de desarrollo
npm uninstall lodash # eliminar un paquete
# Instalar pnpm
npm install -g pnpm
# Comandos equivalentes
pnpm install # instalar todo
pnpm add zod # agregar dependencia
pnpm add -D vitest # agregar dependencia de desarrollo
pnpm remove lodash # eliminar
pnpm dev # ejecutar script (sin "run" necesario)
# Instalar nvm (macOS/Linux)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
# Instalar y usar una versión de Node
nvm install 22
nvm install 20
nvm use 22
nvm alias default 22 # establecer predeterminado para nuevas terminales
# Usar versión del archivo .nvmrc
echo "22" > .nvmrc
# Establecer solo para comando actual
PORT=3001 npm run dev
NODE_ENV=production npm run build
# Establecer para sesión actual
export DATABASE_URL="postgresql://localhost:5432/mydb"
# Ver variables de entorno actuales
env | grep NODE
printenv PORT
# Estructura de archivo .env (Next.js)
# Type-check sin compilar
npx tsc --noEmit
# Type-check en modo watch
npx tsc --noEmit --watch
# Generar archivos de declaración
npx tsc --declaration --emitDeclarationOnly
# Verificar tsconfig
npx tsc --showConfig
# Encontrar errores de tipo específicos
npx tsc --noEmit 2>&1 | grep
# Compilación de producción de Next.js
npm run build
# Muestra tamaños de rutas, estático vs dinámico, desglose de bundle
# Analizar tamaño de bundle
npm install -D @next/bundle-analyzer
ANALYZE=true npm run build
# Verificar tamaño de paquete antes de instalar
npx package-size zustand zod lodash
# o usar https://bundlephobia.com
# Medir tiempo de compilación
# Depurador de Node.js
node --inspect server.js # adjuntar Chrome DevTools
node --inspect-brk server.js # romper en primera línea
# Depurar una aplicación Next.js
NODE_OPTIONS='--inspect' npm run dev
# Perfil de memoria
node --max-old-space-size=4096 server.js # aumentar heap a 4GB
node --heap-prof server.js # generar perfil de heap
# Probar un endpoint de API
curl http://localhost:3000/api/health
curl -s http://localhost:3000/api/users | jq .
# POST con cuerpo JSON
curl -X POST http://localhost:3000/api/users \
-H "Content-Type: application/json" \
-d '{"name": "Alice", "email": "alice@example.com"}'
# POST con encabezado de autenticación
curl -H "Authorization: Bearer $TOKEN
Cosas que te van a causar problemas. Cada problema incluye qué sale mal, por qué sucede y la solución.
Puerto ya en uso — EADDRINUSE: address already in use :::3000. Solución: lsof -ti :3000 | xargs kill -9 o usa un puerto diferente: PORT=3001 npm run dev.
Desincronización de versión de Node — La compilación funciona localmente pero falla en CI o para compañeros de equipo. Solución: Agrega un archivo .nvmrc y un campo engines en package.json: "engines": { "node": ">=22" }.
npm install vs npm ci — npm install puede actualizar el lockfile, causando cambios inesperados. Solución: Usa npm ci en pipelines de CI — usa el lockfile exactamente y es más rápido.
Prefijo NEXT_PUBLIC_ faltante — El código del lado del cliente obtiene undefined para variables de entorno. Solución: Las variables de entorno accedidas en el navegador deben comenzar con NEXT_PUBLIC_. Las variables solo del servidor no necesitan el prefijo.
Conflictos de paquetes globales — Las instalaciones globales de next, typescript, etc. entran en conflicto con versiones del proyecto. Solución: Usa npx en lugar de instalaciones globales. Elimina globales: npm uninstall -g next.
Heap sin memoria — Las compilaciones grandes se cuelgan con FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed. Solución: NODE_OPTIONS="--max-old-space-size=8192" npm run build.
Otras formas de resolver el mismo problema — y cuándo cada una es la mejor opción.
| Alternativa | Usa Cuando | No Uses Cuando |
|---|---|---|
pnpm | Instalaciones más rápidas, monorepos, resolución de dependencias estricta | Proyectos simples donde npm es suficiente |
yarn | Proyectos existentes que ya usan yarn | Nuevos proyectos (pnpm o npm son preferidos) |
bun | Máxima velocidad, test runner integrado | La estabilidad de producción es crítica (runtime más nuevo) |
fnm | Cambio de versión de Node más rápido que nvm | Ya usando nvm y funciona bien |
volta | Cambio automático de versión de Node por proyecto | Proyectos simples con una versión de Node |
npm install y npm ci?npm install lee package.json y puede actualizar package-lock.jsonnpm ci usa el lockfile exactamente, elimina node_modules primero y es más rápidonpm ci en pipelines de CI para compilaciones reproduciblesnpx en lugar de instalar un paquete globalmente?npx para comandos de una sola vez como npx create-next-app o npx tsc --noEmitnpx siempre usa la versión local del proyecto si está disponibleecho "22" > .nvmrc
nvm usenvm use lee .nvmrc y cambia a esa versiónnvm alias default 22undefined para una variable de entorno?NEXT_PUBLIC_DATABASE_URL) no se exponen al navegadorlsof -ti :3000 | xargs kill -9PORT=3001 npm run dev.nvmrc con la versión de Node (por ejemplo, 22)engines en package.json: "engines": { "node": ">=22" }npm install -D @next/bundle-analyzer
ANALYZE=true npm run buildnpx depcheck para encontrar dependencias no utilizadasNODE_OPTIONS='--inspect' npm run devchrome://inspect en Chrome y haz clic en "inspect" en tu proceso Node--inspect-brk para romper en la primera líneaNODE_OPTIONS="--max-old-space-size=8192" npm run buildnpx tsc --noEmit--noEmit ejecuta el verificador de tipos sin generar archivos .js--watch para verificación continua durante el desarrollonpx tsc --noEmit 2>&1 | grep "error TS" | wc -lgrep "error TS" para aislar errores de tipo de otra salidapnpm y npm?pnpm usa un almacén direccionable por contenido, por lo que las dependencias compartidas no se duplican en discopnpm tiene resolución de dependencias más estricta (previene dependencias fantasma)pnpm es más rápido para instalaciones, especialmente en monoreposnpm viene preinstalado con Node y tiene familiaridad más amplia del ecosistema