Tutorial de Node.js para principiantes: de cero a tu primera app

Home » Python » Tutorial de Node.js para principiantes: de cero a tu primera app

Si es tu primera toma de contacto con Node.js, aquí tienes una guía pensada para empezar con buen pie: iremos de lo más básico a un flujo de trabajo real, con ejemplos prácticos y explicaciones claras. Te acompañaré desde el mítico Hola Mundo hasta levantar una app web con Express, pasando por módulos del sistema, npm y el enfoque asíncrono que hace tan especial al ecosistema de Node.

Además de orientarte con requisitos previos, configuración en Visual Studio Code y primeros proyectos, verás cómo organizar un servidor HTTP, enrutar peticiones, manejar controladores, trabajar con datos POST sin bloquear el hilo y entender la filosofía event-driven. Todo con un lenguaje cercano, sin rodeos, y con el toque necesario para que no te pierdas.

Requisitos previos y qué esperar de Node.js

Necesitarás unos conocimientos básicos de JavaScript (tipos, variables, funciones, objetos) y ganas de probar cosas con la consola. Node.js es un entorno de ejecución de JavaScript fuera del navegador, basado en V8, con una librería estándar potente y un modelo de ejecución dirigido por eventos y no bloqueante. Esto le permite gestionar muchas conexiones concurrentes sin crear un hilo por cada petición.

Con Node puedes construir servidores web, APIs REST, herramientas de línea de comandos, apps en tiempo real (chat, notificaciones), integraciones con bases de datos y hasta proyectos IoT. Su fortaleza está en el manejo de E/S concurrente, lo que lo hace ideal para tráfico alto y experiencias interactivas.

Descarga e instalación

Descarga Node.js desde la web oficial en nodejs.org e instálalo para tu sistema operativo. En Windows, macOS o Linux tendrás instaladores y paquetes adecuados. Tras la instalación, confirma en terminal con: node -v y npm -v. npm es el gestor de paquetes de Node y te permitirá instalar librerías de terceros de forma sencilla.

Tu primer contacto: Hola Mundo con VS Code

Si usas Visual Studio Code, puedes abrir la carpeta del proyecto y lanzar el terminal integrado con total comodidad. Crea una carpeta de trabajo y entra en ella: mkdir HelloNode && cd HelloNode.

Ahora abre esa carpeta en VS Code con code .. Crea un archivo llamado app.js e introduce algo sencillo para arrancar: un mensaje por consola.

var msg = 'Hello World';
console.log(msg);

Para ejecutarlo, abre la terminal integrada en VS Code (Ver > Terminal, o atajo Ctrl+`), y lanza node app.js. Verás el clásico output “Hello World” en la consola; sí, sencillo, pero confirma que todo va bien.

De cero a servidor: un HTTP server mínimo

Node trae un módulo nativo llamado ‘http’ con el que puedes crear un servidor en pocas líneas. El corazón es http.createServer, que recibe una función callback que se ejecuta cada vez que llega una petición.

var http = require('http');

http.createServer(function (request, response) {
  response.writeHead(200, {'Content-Type': 'text/html'});
  response.write('Hola Mundo');
  response.end();
}).listen(8888);

Arráncalo con node server.js y visita http://localhost:8888/. La magia de Node está en su modelo orientado a eventos: pasas una función y el runtime la “llama de vuelta” (callback) cuando sucede el evento (una petición entrante).

Entendiendo callbacks, asincronía y flujo de ejecución

En JavaScript las funciones son ciudadanos de primera: se pueden pasar como argumentos, devolver y almacenar en variables. Este patrón encaja con el bucle de eventos de Node: tu código registra funciones que se ejecutan cuando ocurren sucesos (por ejemplo, llega una petición HTTP).

Es crucial entender la diferencia entre operaciones bloqueantes y no bloqueantes. Si introduces algo que ocupa la CPU durante segundos (por ejemplo, un bucle de espera), el proceso entero se detiene y todas las peticiones sufren. En Node, trabaja siempre que puedas con E/S asíncrona y callbacks o promesas para evitar bloquear el hilo.

Diseño modular: servidor, router y manejadores

Separar responsabilidades te ayudará a escalar el proyecto: un módulo para el servidor HTTP, otro para el enrutador y otros para los controladores (request handlers). Puedes exponer funciones con exports y requerir módulos locales con require('./miModulo').

Una estructura típica podría ser: index.js como punto de entrada, server.js con el HTTP server, router.js para decidir a qué función mandar cada ruta y requestHandlers.js con la lógica de cada endpoint. Esta organización mantiene el código legible y fácil de probar.

Extrayendo la ruta y enrutando

El objeto request tiene la URL solicitada. El módulo nativo url permite extraer el pathname y, si hace falta, la query. Con eso, el router podrá decidir qué controlador ejecutar.

var url = require('url');

function onRequest(request, response) {
  var pathname = url.parse(request.url).pathname;
  // route(pathname) ...
}

El router recibe el mapa de rutas a funciones (un objeto donde cada clave es una ruta, y el valor, el handler), junto con el pathname, y comprueba si hay una función asociada. Si existe, la ejecuta; si no, devuelve un 404.

Haciendo que el handler responda (el patrón correcto)

Una tentación habitual es hacer que el controlador retorne un string y que el servidor lo escriba. Pero esto falla cuando el handler necesita hacer algo asíncrono (como leer de disco o ejecutar un comando). La solución efectiva es inyectar el objeto response hasta el handler y que el propio handler escriba la respuesta cuando la tenga (por ejemplo, dentro del callback de una función asíncrona).

// router.js
function route(handle, pathname, response) {
  if (typeof handle[pathname] === 'function') {
    handle[pathname](response);
  } else {
    response.writeHead(404, {'Content-Type': 'text/html'});
    response.write('404 No Encontrado');
    response.end();
  }
}

Este enfoque permite responder justo cuando la E/S asíncrona concluye, sin bloquear el proceso ni forzar a devolver datos antes de tiempo.

Express: crea una app web en minutos

Express es un framework minimalista para Node.js que facilita gestionar rutas, vistas, middleware y utilidades HTTP. Con su generador puedes crear la estructura de un proyecto en segundos, con carpetas para rutas, vistas y recursos estáticos.

1. Crea una carpeta para tus proyectos: mkdir ExpressProjects && cd ExpressProjects.
2. Genera una plantilla: npx express-generator HelloWorld --view=pug crea la app con motor de vistas Pug.
3. Abre en VS Code con code . y revisa la estructura: bin (arranque), public (JS/CSS/imágenes), routes (controladores de rutas), views (plantillas), app.js (config), package.json (scripts y dependencias).
4. Instala dependencias con npm install en la carpeta del proyecto.
5. Inicia la app. Por ejemplo, con depuración: npx cross-env DEBUG=HelloWorld:* npm start.
6. Abre http://localhost:3000. Prueba a cambiar la vista principal: en views/index.pug, sustituye el título por h1 "Hello World!" y recarga.

Express incorpora lo necesario para gestionar GET, POST, PUT y DELETE, usar middleware, servir estáticos, renderizar vistas y estructurar una app de varias páginas con menos fricción.

npm y módulos incorporados de Node

npm es el gestor de paquetes de Node y te permite instalar librerías de terceros. Por ejemplo, para añadir Express: npm install express. Después podrás require('express') y utilizarlo en tu código. Esta flexibilidad es clave para crecer con tu proyecto.

Además, Node incluye módulos nativos para tareas comunes: fs (archivos), http/https (servidores), path (rutas), os (datos del sistema), url (parsing de URL) y muchos más. Puedes importarlos con require() sin instalar nada.

Probando un módulo nativo: información del sistema

El módulo ‘os’ ofrece datos del sistema operativo. Abre la consola y entra en el REPL de Node con node para probar funciones rápidamente sin crear archivos.

1. Escribe os.platform() para saber la plataforma (win32, linux, darwin…). Confirmarás el SO activo de forma directa.
2. Con os.arch() obtendrás la arquitectura (x64, arm64…). Útil para binarios o builds.
3. Usa os.cpus() para ver los núcleos disponibles. Ideal para equilibrar carga con clústeres o procesos hijos.
4. Sal del REPL con .exit o pulsando Ctrl+C dos veces. Rápido y sin residuos.

Biblioteca de terceros útil en el día a día

El ecosistema npm es enorme. Algunas utilidades populares: sharp (tratamiento de imágenes y compresión), PDFKit (generación de PDF), validator.js (validación de cadenas), imagemin y UglifyJS (minificación), spritesmith (sprites), winston (logging) y commander.js (CLI). Instálalas con npm install <paquete> cuando las necesites.

Cómo ejecutar código Node.js desde archivo

Guarda tu código en un archivo, por ejemplo app.js, y ejecútalo con node app.js en la terminal. Esto inicia tu programa y verás los resultados en consola o, si levantas un servidor, en tu navegador.

Del REPL a la aplicación real: flujo completo

Probar en el REPL es perfecto para funciones pequeñas, pero en cuanto tu código crece, te conviene pasar a archivos, organizar módulos y añadir scripts de npm. De esta forma podrás automatizar tareas con npm run y documentar los comandos de inicio en package.json.

Manejando datos POST sin bloquear

Cuando un usuario envía un formulario, el cuerpo de la petición puede llegar en varios trozos. En el servidor (callback de createServer) añade listeners data y end para ir acumulando el contenido y procesarlo al final. Indica también la codificación, por ejemplo UTF-8, para manipularlo correctamente.

request.setEncoding('utf8');
var postBody = '';
request.addListener('data', function(chunk) {
  postBody += chunk;
});
request.addListener('end', function() {
  // route(handle, pathname, response, postBody)
});

Si necesitas extraer campos individuales, usa el módulo ‘querystring’ para parsear el cuerpo cuando llega como application/x-www-form-urlencoded: querystring.parse(postBody).text, por ejemplo.

Operaciones costosas y exec no bloqueante

Para ejecutar comandos del sistema sin detener el servidor, utiliza child_process.exec y responde en el callback. Puedes añadir opciones como timeout o maxBuffer para controlar comandos pesados. El patrón es siempre el mismo: nada de bloquear, y responder cuando haya datos.

var exec = require('child_process').exec;

function handler(response) {
  exec('ls -lah', function(error, stdout, stderr) {
    response.writeHead(200, {'Content-Type': 'text/plain'});
    response.write(stdout);
    response.end();
  });
}

Si cambias el comando por algo más exigente, el resto de rutas seguirá respondiendo con normalidad siempre que no hagas trabajo sincrónico costoso en el hilo principal.

Subidas de ficheros: enfoque y herramientas

Para manejar uploads multiparte (imágenes u otros archivos) lo más práctico es recurrir a un paquete especializado. Módulos como formidable facilitan parsear formularios multipart/form-data, acceder a los archivos temporales y moverlos a su destino. La idea es la misma: callbacks/promesas y trabajar de forma segura con streams.

Aunque la implementación completa escapa a los primeros pasos, lo importante es que integres el upload en tu flujo: servidor que recibe el formulario, router que dirige a la ruta de subida, y handler que valida, guarda y responde con el resultado (por ejemplo, mostrando la imagen).

Estructura de vistas y contenido dinámico

Si optas por Express con Pug u otro motor, el controlador pasa datos a la vista y esta los renderiza. Para un formulario sencillo con un textarea enviado por POST y una ruta que lo muestra, basta con dos handlers: uno que sirve el formulario y otro que procesa y devuelve el contenido recibido.

Buenas prácticas de organización

Evita archivos monolíticos. Divide en módulos, nombra funciones con verbos que expresen acciones (por ejemplo, iniciar, subir, listar), y desacopla con inyección de dependencias cuando tenga sentido (pasando funciones o mapas de rutas al servidor y al router). Mantener las capas ligeras te permitirá crecer sin dolores.

Qué puedes construir con Node.js

Su modelo event-driven y non-blocking lo hace especialmente bueno para: servidores web, APIs REST, apps en tiempo real (chat, dashboards), bots y CLIs, integraciones con bases de datos, colas de trabajo, y control de hardware. La facilidad para manejar websockets y streaming lo convierte en una elección natural para experiencias interactivas.

• Servidores y sitios web con plantillas o SSR.
• REST APIs preparadas para alto tráfico.
• Tiempo real con sockets para chat, notificaciones o juegos.
• Herramientas de línea de comandos para automatizar tareas.
• Procesos con ficheros y bases de datos, colas y pipelines.
• IoT y hardware con librerías específicas.

Herramientas de aprendizaje y práctica

Existen entornos interactivos que muestran código y salida lado a lado, ideales para entender ejemplos rápidos. Aun así, podrás progresar sin crear cuentas: documentarte, copiar ejemplos y ejecutar en local con tu terminal es más que suficiente al principio.

Visual Studio Code: productividad sin salir del editor

El terminal integrado, el depurador y las extensiones de VS Code hacen que trabajar con Node sea muy cómodo. Desde “Ver > Terminal” puedes abrir shells, cambiar el predeterminado y ejecutar node o npm run sin abandonar el editor. Además, configurar launch.json te permitirá depurar paso a paso.

Apuntes de versión y estabilidad

Muchas guías clásicas se probaron con versiones antiguas de Node, pero los conceptos se mantienen vigentes: callbacks, módulos nativos, asincronía, enrutado y separación de responsabilidades. Hoy trabajarás con versiones actuales, más rápidas y seguras, y con un ecosistema npm aún más rico.

Descargas y recursos adicionales

Puedes ampliar estudio con documentación, PDFs y tutoriales. Revisa siempre la web oficial de Node para novedades y descarga, e identifica fuentes didácticas que incluyan ejercicios, quizzes y retos para afianzar conocimientos a medida que avances.

Si buscas material complementario, encontrarás guías introductorias y referencias prácticas con ejemplos, así como enlaces de descarga cuando sea necesario. Mantén tu foco en practicar: leer está bien; ejecutar, romper cosas y arreglarlas, mejor.

Ejemplo completo: mini app con router y handlers

Juntando piezas. Imagina un proyecto con index.js que arranca el servidor, server.js con HTTP y parsing de POST, router.js que decide qué función ejecutar y requestHandlers.js con dos rutas: una que muestra un formulario y otra que enseña el texto enviado.

// index.js
var server = require('./server');
var router = require('./router');
var handlers = require('./requestHandlers');

var handle = {};
handle['/'] = handlers.iniciar;
handle['/iniciar'] = handlers.iniciar;
handle['/subir'] = handlers.subir;

server.iniciar(router.route, handle);

// server.js
var http = require('http');
var url = require('url');

function iniciar(route, handle) {
  function onRequest(request, response) {
    var postData = '';
    var pathname = url.parse(request.url).pathname;

    request.setEncoding('utf8');
    request.addListener('data', function(chunk) { postData += chunk; });
    request.addListener('end', function() {
      route(handle, pathname, response, postData);
    });
  }

  http.createServer(onRequest).listen(8888);
}

exports.iniciar = iniciar;

// router.js
function route(handle, pathname, response, postData) {
  if (typeof handle[pathname] === 'function') {
    handle[pathname](response, postData);
  } else {
    response.writeHead(404, {'Content-Type': 'text/html'});
    response.end('404 No Encontrado');
  }
}

exports.route = route;

// requestHandlers.js
var querystring = require('querystring');

function iniciar(response) {
  var body = '<html>'+
    '<head><meta charset=\'UTF-8\' /></head>'+
    '<body>'+
    '<form action=\'/subir\' method=\'post\'>'+
    '<textarea name=\'text\' rows=\'10\' cols=\'40\'></textarea>'+
    '<input type=\'submit\' value=\'Enviar\' />'+
    '</form>'+
    '</body></html>';

  response.writeHead(200, {'Content-Type': 'text/html'});
  response.end(body);
}

function subir(response, postData) {
  var text = querystring.parse(postData).text || '';
  response.writeHead(200, {'Content-Type': 'text/html'});
  response.end('Tu enviaste: ' + text);
}

exports.iniciar = iniciar;
exports.subir = subir;

Con este esqueleto mínimo ya tienes un servidor funcional y no bloqueante, con rutas y controladores separados, preparado para crecer hacia vistas, uploads o integración con bases de datos.

La clave de Node está en pensar en “acciones”: pasar funciones, inyectar dependencias cuando convenga y mantener pequeños los bloques de responsabilidad. Así, tu aplicación será más fácil de mantener y adaptar conforme aumente su complejidad.

Todo lo visto te da una base sólida: desde instalar Node y ejecutar tu primer script, pasando por VS Code, un servidor HTTP nativo, enrutado propio, Express, npm, módulos nativos, REPL, asincronía sin bloqueos y manejo de formularios POST. Con práctica y pequeñas iteraciones, podrás construir proyectos cada vez más completos sin perder claridad en el código.