Node.js / TypeScript - Entorno de Desarrollo¶
Guía completa para configurar un entorno de desarrollo Node.js/TypeScript para backend que permita a Claude Code trabajar eficazmente.
Requisitos del Sistema¶
| Componente | Versión Mínima | Recomendada |
|---|---|---|
| Node.js | 18.x LTS | 22.x LTS |
| npm | 9.x | 10.x |
| pnpm | 8.x | 9.x |
| TypeScript | 5.0 | 5.4+ |
Instalación de Node.js¶
Windows¶
# Opción 1: Winget (versión específica)
winget install OpenJS.NodeJS.LTS
# Opción 2: nvm-windows (recomendado para múltiples versiones)
winget install CoreyButler.NVMforWindows
# Después de instalar nvm:
nvm install 22
nvm install 20
nvm use 22 # Cambiar versión activa
nvm list # Ver versiones instaladas
# Verificar
node --version
npm --version
macOS¶
# Homebrew
brew install node@22
# O nvm (recomendado)
brew install nvm
mkdir ~/.nvm
# Añadir a ~/.zshrc
export NVM_DIR="$HOME/.nvm"
[ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && \. "/opt/homebrew/opt/nvm/nvm.sh"
# Instalar Node
nvm install 22
nvm use 22
nvm alias default 22
# Verificar
node --version
Linux¶
# nvm (recomendado)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# Reiniciar terminal o ejecutar:
source ~/.bashrc
# Instalar Node
nvm install 22
nvm use 22
nvm alias default 22
# Verificar
node --version
npm --version
Gestores de Paquetes¶
pnpm (Recomendado)¶
# Instalar pnpm globalmente
npm install -g pnpm
# O con corepack (incluido en Node 16.13+)
corepack enable
corepack prepare pnpm@latest --activate
# Verificar
pnpm --version
# Comandos básicos
pnpm install # Instalar dependencias
pnpm add express # Añadir dependencia
pnpm add -D typescript # Añadir dev dependency
pnpm remove express # Eliminar dependencia
pnpm run dev # Ejecutar script
pnpm dlx tsx app.ts # Ejecutar sin instalar globalmente
# Configuración global
pnpm config set store-dir ~/.pnpm-store
npm (Default)¶
# Actualizar npm
npm install -g npm@latest
# Comandos básicos
npm install
npm install express
npm install --save-dev typescript
npm run dev
npx tsx app.ts
Yarn (Alternativa)¶
# Instalar
corepack enable
corepack prepare yarn@stable --activate
# Verificar
yarn --version
# Comandos
yarn install
yarn add express
yarn add -D typescript
yarn dev
TypeScript Setup¶
Instalación y Configuración¶
# Instalar TypeScript
pnpm add -D typescript @types/node
# Crear tsconfig.json
npx tsc --init
# O usar configuración recomendada
pnpm add -D @tsconfig/node22
tsconfig.json recomendado para backend:
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"lib": ["ES2022"],
"outDir": "./dist",
"rootDir": "./src",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"resolveJsonModule": true,
"declaration": true,
"declarationMap": true,
"sourceMap": true,
"noImplicitAny": true,
"strictNullChecks": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"noImplicitReturns": true,
"noFallthroughCasesInSwitch": true,
"isolatedModules": true
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist"]
}
Herramientas de Ejecución¶
# tsx - Ejecutar TypeScript directamente (recomendado para desarrollo)
pnpm add -D tsx
pnpm tsx src/index.ts
pnpm tsx watch src/index.ts # Con hot reload
# ts-node (alternativa clásica)
pnpm add -D ts-node
pnpm ts-node src/index.ts
# Para producción: compilar a JS
pnpm tsc
node dist/index.js
IDE y Extensiones¶
Visual Studio Code¶
# Extensiones obligatorias
code --install-extension ms-vscode.vscode-typescript-next
code --install-extension dbaeumer.vscode-eslint
code --install-extension esbenp.prettier-vscode
# Extensiones recomendadas
code --install-extension bradlc.vscode-tailwindcss
code --install-extension prisma.prisma
code --install-extension mikestead.dotenv
code --install-extension christian-kohler.path-intellisense
code --install-extension usernamehw.errorlens
code --install-extension yoavbls.pretty-ts-errors
# Para testing
code --install-extension vitest.explorer
code --install-extension ms-playwright.playwright
# Para bases de datos
code --install-extension mtxr.sqltools
code --install-extension mtxr.sqltools-driver-pg
settings.json recomendado:
{
"editor.defaultFormatter": "esbenp.prettier-vscode",
"editor.formatOnSave": true,
"editor.codeActionsOnSave": {
"source.fixAll.eslint": "explicit",
"source.organizeImports": "explicit"
},
"typescript.preferences.importModuleSpecifier": "relative",
"typescript.updateImportsOnFileMove.enabled": "always",
"[typescript]": {
"editor.defaultFormatter": "esbenp.prettier-vscode"
},
"[javascript]": {
"editor.defaultFormatter": "esbenp.prettier-vscode"
}
}
Frameworks Backend¶
Express.js (Clásico)¶
# Dependencias
pnpm add express
pnpm add -D @types/express typescript tsx
# Estructura típica
src/
├── index.ts
├── routes/
│ └── users.ts
├── controllers/
├── middleware/
├── services/
└── types/
# package.json scripts
{
"scripts": {
"dev": "tsx watch src/index.ts",
"build": "tsc",
"start": "node dist/index.js"
}
}
NestJS (Enterprise - Recomendado)¶
# Instalar CLI
pnpm add -g @nestjs/cli
# Crear proyecto
nest new my-project
# Generar recursos
nest generate module users
nest generate controller users
nest generate service users
nest generate resource products # CRUD completo
# Estructura generada
src/
├── app.module.ts
├── main.ts
├── users/
│ ├── users.module.ts
│ ├── users.controller.ts
│ ├── users.service.ts
│ ├── dto/
│ │ ├── create-user.dto.ts
│ │ └── update-user.dto.ts
│ └── entities/
│ └── user.entity.ts
# Ejecutar
pnpm run start:dev
Fastify (Alto rendimiento)¶
# Dependencias
pnpm add fastify @fastify/cors @fastify/helmet
pnpm add -D typescript @types/node tsx
# Con TypeScript
pnpm add @fastify/type-provider-typebox @sinclair/typebox
# Ejecutar
pnpm tsx watch src/server.ts
Hono (Moderno, multi-runtime)¶
ORM y Bases de Datos¶
Prisma (Recomendado)¶
# Instalar
pnpm add prisma @prisma/client
pnpm add -D prisma
# Inicializar
npx prisma init
# Configurar schema.prisma
# datasource db {
# provider = "postgresql"
# url = env("DATABASE_URL")
# }
# Comandos de migración
npx prisma migrate dev --name init # Crear migración
npx prisma migrate deploy # Aplicar en producción
npx prisma generate # Generar cliente
npx prisma studio # UI para explorar datos
npx prisma db pull # Introspección de BD existente
npx prisma db push # Push sin migración (desarrollo)
# Ejemplo de uso
import { PrismaClient } from '@prisma/client'
const prisma = new PrismaClient()
Drizzle ORM (Alternativa ligera)¶
# Instalar
pnpm add drizzle-orm postgres
pnpm add -D drizzle-kit
# Configurar drizzle.config.ts
# Generar migraciones
npx drizzle-kit generate
npx drizzle-kit migrate
npx drizzle-kit studio
TypeORM¶
# Instalar
pnpm add typeorm reflect-metadata pg
pnpm add -D @types/node
# Inicializar
npx typeorm init --database postgres
Drivers de Base de Datos¶
# PostgreSQL
pnpm add pg # Para TypeORM, Drizzle
pnpm add postgres # Para Drizzle
pnpm add @prisma/client # Para Prisma
# MySQL
pnpm add mysql2
# SQLite
pnpm add better-sqlite3
# MongoDB
pnpm add mongodb
pnpm add mongoose # Con ODM
# Redis
pnpm add ioredis # Recomendado
pnpm add redis # Oficial
Testing¶
Vitest (Recomendado)¶
# Instalar
pnpm add -D vitest @vitest/coverage-v8
# vitest.config.ts
import { defineConfig } from 'vitest/config'
export default defineConfig({
test: {
globals: true,
environment: 'node',
coverage: {
reporter: ['text', 'json', 'html'],
},
},
})
# Ejecutar
pnpm vitest # Watch mode
pnpm vitest run # Single run
pnpm vitest --coverage
# package.json
{
"scripts": {
"test": "vitest",
"test:run": "vitest run",
"test:coverage": "vitest run --coverage"
}
}
Jest (Alternativa)¶
# Instalar
pnpm add -D jest @types/jest ts-jest
# Inicializar
npx ts-jest config:init
# Ejecutar
pnpm jest
pnpm jest --coverage
Supertest (Testing de APIs)¶
# Instalar
pnpm add -D supertest @types/supertest
# Ejemplo
import request from 'supertest'
import app from '../src/app'
describe('GET /users', () => {
it('should return users', async () => {
const res = await request(app).get('/users')
expect(res.status).toBe(200)
expect(res.body).toHaveLength(10)
})
})
Linting y Formateo¶
ESLint + Prettier¶
# Instalar
pnpm add -D eslint @eslint/js typescript-eslint
pnpm add -D prettier eslint-config-prettier eslint-plugin-prettier
# eslint.config.mjs (Flat Config - ESLint 9+)
import eslint from '@eslint/js'
import tseslint from 'typescript-eslint'
export default tseslint.config(
eslint.configs.recommended,
...tseslint.configs.recommended,
{
rules: {
'@typescript-eslint/no-unused-vars': 'error',
'@typescript-eslint/explicit-function-return-type': 'warn',
},
},
)
# .prettierrc
{
"semi": false,
"singleQuote": true,
"tabWidth": 2,
"trailingComma": "es5"
}
# package.json scripts
{
"scripts": {
"lint": "eslint src/",
"lint:fix": "eslint src/ --fix",
"format": "prettier --write \"src/**/*.ts\""
}
}
Biome (Alternativa todo-en-uno)¶
# Instalar
pnpm add -D @biomejs/biome
# Inicializar
npx @biomejs/biome init
# Ejecutar
npx @biomejs/biome check --apply .
npx @biomejs/biome format --write .
Docker para Node.js¶
Dockerfile¶
# Build stage
FROM node:22-alpine AS builder
RUN corepack enable && corepack prepare pnpm@latest --activate
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile
COPY . .
RUN pnpm build
# Production stage
FROM node:22-alpine AS runner
RUN corepack enable && corepack prepare pnpm@latest --activate
WORKDIR /app
ENV NODE_ENV=production
COPY --from=builder /app/package.json /app/pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile --prod
COPY --from=builder /app/dist ./dist
USER node
EXPOSE 3000
CMD ["node", "dist/index.js"]
Docker Compose¶
version: '3.8'
services:
api:
build: .
ports:
- "3000:3000"
environment:
- NODE_ENV=development
- DATABASE_URL=postgresql://postgres:postgres@db:5432/myapp
- REDIS_URL=redis://redis:6379
volumes:
- .:/app
- /app/node_modules
depends_on:
- db
- redis
command: pnpm dev
db:
image: postgres:16
environment:
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
POSTGRES_DB: myapp
ports:
- "5432:5432"
volumes:
- postgres_data:/var/lib/postgresql/data
redis:
image: redis:7-alpine
ports:
- "6379:6379"
volumes:
postgres_data:
Comandos que Claude Code Ejecutará¶
# Gestión de paquetes
pnpm install
pnpm add <package>
pnpm add -D <package>
pnpm remove <package>
pnpm update
# Desarrollo
pnpm dev # Servidor desarrollo
pnpm tsx src/index.ts # Ejecutar TS directamente
pnpm tsx watch src/index.ts # Con hot reload
# Build y producción
pnpm build
pnpm start
node dist/index.js
# Testing
pnpm test
pnpm test:run
pnpm test:coverage
# Linting
pnpm lint
pnpm lint:fix
pnpm format
# Prisma
npx prisma migrate dev --name <name>
npx prisma generate
npx prisma studio
npx prisma db push
# NestJS
nest generate resource <name>
nest build
nest start:dev
# Docker
docker build -t myapp .
docker compose up -d
Verificación del Entorno¶
#!/bin/bash
# verify-node-env.sh
echo "=== Verificación Entorno Node.js ==="
echo -e "\n--- Node.js ---"
node --version
echo -e "\n--- npm ---"
npm --version
echo -e "\n--- pnpm ---"
pnpm --version 2>/dev/null || echo "pnpm no instalado"
echo -e "\n--- nvm ---"
nvm --version 2>/dev/null || echo "nvm no instalado"
echo -e "\n--- TypeScript ---"
npx tsc --version 2>/dev/null || echo "TypeScript no instalado"
echo -e "\n--- Herramientas Globales ---"
npm list -g --depth=0
echo -e "\n--- PostgreSQL Client ---"
psql --version 2>/dev/null || echo "psql no encontrado"
echo -e "\n=== Verificación Completa ==="
Troubleshooting¶
"EACCES: permission denied"¶
# Cambiar directorio de npm global
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc