Comandos de Desarrollador Node.js
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.
Receta
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.
Ejemplo Funcional
# 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:
npxejecuta un paquete sin instalarlo globalmenteinstalleinstall -Dseparados para dependencias de runtime vs desarrollo- Flags de Next.js para TypeScript, Tailwind, App Router y directorio src
Análisis Profundo
Gestión de Paquetes (npm)
# 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
# Inspeccionar
npm list --depth=0 # paquetes instalados de nivel superior
npm outdated # buscar actualizaciones
npm audit # vulnerabilidades de seguridad
npm audit fix # auto-corregir vulnerabilidades
# Scripts
npm run dev
npm run build
npm run start
npm test
npm run lint
# Ver un paquete antes de instalar
npm info zustand # detalles del paquete
npm info zustand versions # todas las versiones publicadas
# Vincular un paquete local para desarrollo
cd ../my-library && npm link
cd ../my-app && npm link my-libraryGestión de Paquetes (pnpm — alternativa más rápida)
# 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)
pnpm build
# Comandos de workspace (monorepo)
pnpm -r build # ejecutar build en todos los paquetes
pnpm --filter @app/web dev # ejecutar dev en paquete específicoGestión de Versiones de Node (nvm)
# 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
nvm use # lee .nvmrc
# Listar versiones instaladas
nvm ls
# Listar versiones disponibles
nvm ls-remote | grep "Latest LTS"Variables de Entorno
# 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)
# .env — todos los entornos (confirmado)
# .env.local — sobrescrituras locales (gitignored)
# .env.development — solo desarrollo
# .env.production — solo producción
# .env.test — solo pruebas
# Acceder en Next.js
# Servidor: process.env.DATABASE_URL
# Cliente: process.env.NEXT_PUBLIC_API_URL (debe tener prefijo NEXT_PUBLIC_)
# Verificar qué variables de entorno ve tu aplicación
node -e "console.log(process.env.NODE_ENV)"Comandos de TypeScript
# 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 "error TS"
# Contar errores de tipo
npx tsc --noEmit 2>&1 | grep "error TS" | wc -l
# Verificar un archivo específico
npx tsc --noEmit src/lib/utils.tsAnálisis de Compilación y Bundle
# 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
time npm run build
# Verificar qué hay en node_modules
du -sh node_modules # tamaño total
du -sh node_modules/* | sort -rh | head -20 # paquetes más grandes
npx depcheck # encontrar dependencias no utilizadasDepuració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
# REPL rápido para pruebas
node
> const { z } = require('zod')
> z.string().email().safeParse('test@example.com')
# Ejecutar un one-liner
node -e "console.log(Date.now())"
node -e "console.log(require('./package.json').version)"
node -p "require('os').cpus().length" # -p imprime el resultado
# Verificar resolución de módulos
node -e "console.log(require.resolve('react'))"Pruebas de Red y API
# 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" \
http://localhost:3000/api/protected
# Tiempo de solicitud
curl -o /dev/null -s -w "Total: %{time_total}s\nTTFB: %{time_starttransfer}s\n" \
http://localhost:3000
# Observar un puerto
lsof -i :3000 # qué está usando puerto 3000
kill -9 $(lsof -ti :3000) # matar lo que está en puerto 3000Problemas Comunes
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 -9o 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
.nvmrcy un campoenginesenpackage.json:"engines": { "node": ">=22" }. -
npm installvsnpm ci—npm installpuede actualizar el lockfile, causando cambios inesperados. Solución: Usanpm cien 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
undefinedpara variables de entorno. Solución: Las variables de entorno accedidas en el navegador deben comenzar conNEXT_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: Usanpxen 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.
Alternativas
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 |
Preguntas Frecuentes
¿Cuál es la diferencia entre npm install y npm ci?
npm installleepackage.jsony puede actualizarpackage-lock.jsonnpm ciusa el lockfile exactamente, eliminanode_modulesprimero y es más rápido- Usa
npm cien pipelines de CI para compilaciones reproducibles
¿Cuándo debo usar npx en lugar de instalar un paquete globalmente?
- Usa
npxpara comandos de una sola vez comonpx create-next-apponpx tsc --noEmit - Las instalaciones globales pueden entrar en conflicto con versiones locales del proyecto
npxsiempre usa la versión local del proyecto si está disponible
¿Cómo cambio versiones de Node para diferentes proyectos?
echo "22" > .nvmrc
nvm usenvm uselee.nvmrcy cambia a esa versión- Establece un predeterminado con
nvm alias default 22
¿Por qué mi código del lado del cliente obtiene undefined para una variable de entorno?
- En Next.js, las variables de entorno del lado del cliente deben tener prefijo
NEXT_PUBLIC_ - Las variables solo del servidor (por ejemplo,
DATABASE_URL) no se exponen al navegador - Esta es una característica de seguridad para evitar filtrar secretos
¿Cómo mato un proceso que está usando puerto 3000?
lsof -ti :3000 | xargs kill -9- O usa un puerto diferente:
PORT=3001 npm run dev
Problema Común: Mi compilación funciona localmente pero falla en CI con una versión diferente de Node. ¿Cómo lo arreglo?
- Agrega un archivo
.nvmrccon la versión de Node (por ejemplo,22) - Agrega un campo
enginesenpackage.json:"engines": { "node": ">=22" } - Asegúrate de que tu configuración de CI instale la versión coincidente
¿Cómo analizo el tamaño de mi bundle de Next.js?
npm install -D @next/bundle-analyzer
ANALYZE=true npm run build- Abre un treemap interactivo mostrando qué hay en cada bundle
- Usa
npx depcheckpara encontrar dependencias no utilizadas
¿Cómo depuro una aplicación Next.js con Chrome DevTools?
NODE_OPTIONS='--inspect' npm run dev- Abre
chrome://inspecten Chrome y haz clic en "inspect" en tu proceso Node - Usa
--inspect-brkpara romper en la primera línea
Problema Común: Mi compilación se cuelga con "heap out of memory." ¿Qué debo hacer?
NODE_OPTIONS="--max-old-space-size=8192" npm run build- Aumenta el límite de heap V8 a 8GB
- Si esto sigue sucediendo, investiga fugas de memoria o dependencias grandes
¿Cómo hago type-check de un proyecto TypeScript sin producir salida de compilación?
npx tsc --noEmit--noEmitejecuta el verificador de tipos sin generar archivos.js- Agrega
--watchpara verificación continua durante el desarrollo
¿Cómo encuentro y cuento todos los errores de TypeScript en el proyecto?
npx tsc --noEmit 2>&1 | grep "error TS" | wc -l- Canaliza a través de
grep "error TS"para aislar errores de tipo de otra salida
¿Cuál es la diferencia entre pnpm y npm?
pnpmusa un almacén direccionable por contenido, por lo que las dependencias compartidas no se duplican en discopnpmtiene resolución de dependencias más estricta (previene dependencias fantasma)pnpmes más rápido para instalaciones, especialmente en monoreposnpmviene preinstalado con Node y tiene familiaridad más amplia del ecosistema
Relacionado
- Sysadmin Essentials — Gestión de procesos, disco, red y servicios
- Search & Regex — Encontrar archivos, buscar contenido y usar patrones regex
- Shell Productivity — Pipes, redirección, scripting y consejos de flujo de trabajo
- ESLint Setup — Configurar linting para tu proyecto