Conceptos básicos de Node.js

10 ejemplos para empezar con los Fundamentos de Node.js: 7 básicos y 3 intermedios.

Requisitos previos

• Instala Node.js 24.18.0 (LTS activa) a través de fnm, nvm o Volta.
• Verifica con node --version y npm --version (npm 10+ se incluye con Node 24).
• Los nuevos proyectos deben usar "type": "module" en package.json para ESM por defecto.

Ejemplos básicos

1. Comprueba tu versión de Node

Confirma el entorno de ejecución antes de ejecutar cualquier script o desplegar.

console.log(process.version);       // v24.18.0
console.log(process.versions.v8);   // V8 engine version
console.log(process.versions.uv);   // libuv version

• process.version es la cadena autoritativa del entorno de ejecución; regístrala al inicio en producción.
• process.versions expone V8, libuv, OpenSSL y otros enlaces nativos.
• Las imágenes de CI y Docker deben coincidir con la versión fijada en engines de package.json.

Relacionado: Instalación y gestión de versiones - fija la versión LTS en todos los equipos | Política de lanzamiento y LTS de Node.js - qué puede ejecutarse en producción

2. Ejecuta un script con node

La forma más sencilla de ejecutar un archivo TypeScript compilado o JavaScript plano.

// hello.mjs
console.log('Hello from Node.js', process.version);

node hello.mjs

• Guarda como .mjs o establece "type": "module" en package.json para la sintaxis ESM.
• node file.ts funciona con tsx en desarrollo; la producción se compila con tsc primero.
• El código de salida 0 significa éxito; un valor distinto de cero indica un fallo a los shells y CI.

Relacionado: Ejecución de scripts y Shebang - haz que los scripts sean ejecutables

3. Usa la función fetch incorporada

Node 18+ incluye una función fetch global; no se requiere el paquete node-fetch.

const response = await fetch('https://nodejs.org/dist/index.json');
const releases = await response.json() as Array<{ version: string; lts: string | false }>;
const lts = releases.find((r) => r.lts !== false);
console.log('Current LTS tag:', lts?.lts, lts?.version);

• fetch devuelve objetos Response estándar web, la misma API que los navegadores.
• Siempre verifica response.ok o response.status antes de analizar el cuerpo.
• Para la transmisión de grandes descargas, usa response.body como un Web ReadableStream.

Relacionado: Cómo funciona Node.js - donde la E/S se ejecuta fuera del hilo principal

4. Lee las variables de entorno

La configuración pertenece al entorno, no codificada en el código fuente.

const port = Number(process.env.PORT ?? 3000);
const nodeEnv = process.env.NODE_ENV ?? 'development';
 
console.log(`Starting on port ${port} in ${nodeEnv} mode`);

• process.env es un objeto plano de valores de cadena; convierte los tipos explícitamente.
• Usa ?? para los valores predeterminados; la cadena vacía "" es verdadera y no pasará por ||.
• Valida las variables requeridas al inicio con Zod o una biblioteca de esquemas antes de aceptar tráfico.

5. Importa un módulo ES

ESM es el camino a seguir; usa import estático al principio de los archivos.

import { readFile } from 'node:fs/promises';
import { fileURLToPath } from 'node:url';
import path from 'node:path';
 
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
 
const pkg = await readFile(path.join(__dirname, 'package.json'), 'utf8');
console.log(JSON.parse(pkg).name);

• Prefija las importaciones incorporadas con node: para mayor claridad y preparación para el futuro.
• import.meta.url reemplaza a __filename y __dirname de CJS.
• await de nivel superior está permitido en módulos ESM en el ámbito del módulo.

Relacionado: Cómo funciona Node.js - V8 y el cargador de módulos

6. Maneja errores con try/catch

Los errores asíncronos en las expresiones await se propagan como las excepciones síncronas.

async function loadConfig(): Promise<Record<string, string>> {
  try {
    const res = await fetch(process.env.CONFIG_URL!);
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    return await res.json() as Record<string, string>;
  } catch (err) {
    console.error('Config load failed:', err);
    throw err; // vuelve a lanzar para que el proceso se cierre o un supervisor lo reinicie
  }
}

• Las promesas rechazadas sin manejar pueden bloquear Node en producción; siempre adjunta .catch() o usa try/catch.
• Registra el error con contexto (URL, estado) antes de volver a lanzarlo.
• Para los servidores HTTP, asigna los errores a respuestas JSON estructuradas en lugar de rastreos de pila.

7. Experimento rápido con REPL

Prototipa APIs de forma interactiva sin crear un archivo.

node

> await fetch('https://httpbin.org/get').then(r => r.json())
> Object.keys(process.versions)
> .exit

• El REPL admite await de nivel superior cuando se inicia con node (no se necesita el indicador -e en Node 24).
• Usa .save filename para guardar una sesión y .load filename para reproducirla.
• La finalización con tabulador y .help listan todos los comandos con punto.

Relacionado: El REPL y experimentos rápidos - flujos de trabajo REPL más profundos

Ejemplos intermedios

8. Escribe un servidor HTTP mínimo

node:http está incorporado; no se requiere un framework para comprobaciones de estado y sondeos.

import { createServer } from 'node:http';
 
const server = createServer((req, res) => {
  if (req.url === '/health') {
    res.writeHead(200, { 'content-type': 'application/json' });
    res.end(JSON.stringify({ status: 'ok', version: process.version }));
    return;
  }
  res.writeHead(404).end();
});
 
server.listen(3000, () => console.log('Listening on :3000'));

• La devolución de llamada createServer se ejecuta en cada solicitud; mantenla sin bloqueo.
• Establece content-type explícitamente; los clientes asumen text/plain de lo contrario.
• Para APIs de producción, actualiza a Express 5 o Fastify 5 para enrutamiento y validación.

9. Ejecuta pruebas con node:test

El ejecutor de pruebas incorporado de Node no necesita la instalación de Jest para las pruebas unitarias.

// math.test.ts
import { test, describe } from 'node:test';
import assert from 'node:assert/strict';
 
function add(a: number, b: number): number {
  return a + b;
}
 
describe('add', () => {
  test('sums two numbers', () => {
    assert.equal(add(2, 3), 5);
  });
});

node --import tsx --test math.test.ts

• node:test admite describe, hooks y pruebas asíncronas de forma nativa.
• Usa node:assert/strict para comprobaciones de igualdad estrictas.
• Combínalo con tsx en desarrollo para TypeScript; compila antes de CI si prefieres la salida de tsc.

10. Salida de proceso elegante

Escucha las señales para que los contenedores y orquestadores puedan drenar el trabajo de forma limpia.

let shuttingDown = false;
 
function shutdown(signal: string): void {
  if (shuttingDown) return;
  shuttingDown = true;
  console.log(`Received ${signal}, draining...`);
  setTimeout(() => process.exit(0), 2000);
}
 
process.on('SIGTERM', () => shutdown('SIGTERM'));
process.on('SIGINT', () => shutdown('SIGINT'));

• Kubernetes envía SIGTERM antes de eliminar un pod; tienes aproximadamente 30 segundos para drenar.
• Cierra los grupos de bases de datos y los servidores HTTP antes de llamar a process.exit.
• Los manejadores de apagado idempotentes evitan errores de doble cierre en señales repetidas.

Relacionado: Cómo funciona Node.js - modelo de un solo hilo y manejo de señales

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.