El Proyecto | Sobre nosotros | Contribuir | Donaciones | Licencia
HOME Mis cursos Finalizados
◄ Anterior
◄

Instalación y Configuración del Entorno

Siguiente ►
►

Ya sabemos qué es Node.js y por qué encaja con una plataforma como Escena Viva. Toca instalarlo. Podría parecer un trámite —descargar un instalador y siguiente, siguiente, siguiente— pero la forma en que instales Node.js condiciona el resto de tu vida como desarrollador: si mañana un cliente exige la versión 22 y otro la 24, si tu equipo debe reproducir exactamente tu entorno, o si te encuentras con el clásico error de permisos al instalar una herramienta global.

En esta lección instalaremos Node.js de la forma correcta (con un gestor de versiones), verificaremos que todo funciona, configuraremos el editor y crearemos la estructura inicial de la carpeta escena-viva/, que nos acompañará hasta el final del curso.

Contenido

  1. Las tres formas de instalar Node.js
  2. Instalación con nvm en Linux y macOS
  3. Instalación en Windows: nvm-windows y fnm
  4. Verificación: qué se instala junto a Node
  5. Elegir versión para un proyecto real: LTS vs Current
  6. El fichero .nvmrc del proyecto
  7. Configuración del editor y de la terminal
  8. Creación de la carpeta del proyecto Escena Viva
  9. Permisos: por qué nunca debes usar sudo npm install -g

  1. Las tres formas de instalar Node.js

Método Cómo funciona Ventajas Inconvenientes ¿Recomendado?
Instalador oficial (nodejs.org) Descargas un .msi, .pkg o binario y lo instalas en el sistema Muy sencillo; sirve para probar en 2 minutos Una sola versión a la vez; instala en directorios del sistema (origen de problemas de permisos); actualizar es reinstalar Solo para una prueba rápida
Gestor de paquetes del sistema (apt, dnf, brew, winget, choco) Node se instala como cualquier otro programa del sistema Integrado con las actualizaciones del sistema Las distribuciones suelen ir por detrás en versiones; a veces empaquetan npm por separado; cambiar de versión es doloroso Aceptable en servidores gestionados, no en tu equipo de desarrollo
Gestor de versiones (nvm, fnm, Volta, nvm-windows) Instala varias versiones de Node en tu carpeta personal y conmuta entre ellas Varias versiones conviviendo; cambio instantáneo; sin sudo; versión por proyecto vía .nvmrc Un paso extra de instalación inicial Sí. Es la opción de esta lección.

La razón de fondo para preferir un gestor de versiones es sencilla: los proyectos reales tienen ciclos de vida distintos. La API antigua de Escena Viva puede estar en Node 22 mientras el nuevo panel de organizadores se desarrolla en Node 24. Sin un gestor de versiones, eso te obliga a desinstalar y reinstalar constantemente.

Comparativa de los gestores más habituales:

Gestor Plataformas Lenguaje Velocidad Nota
nvm Linux, macOS, WSL script de shell Media El más extendido; el estándar de facto
nvm-windows Windows Go Media Proyecto distinto de nvm, comandos parecidos pero no idénticos
fnm Linux, macOS, Windows Rust Muy alta Compatible con .nvmrc; excelente alternativa moderna
Volta Linux, macOS, Windows Rust Alta Fija la versión en package.json y la aplica automáticamente

En este curso usaremos nvm como referencia (y fnm o nvm-windows en Windows), porque .nvmrc es un fichero que entienden todos ellos.

  1. Instalación con nvm en Linux y macOS

Paso 1: instalar nvm

# Descarga e instala nvm en tu carpeta personal (~/.nvm)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

El script añade unas líneas a tu fichero de configuración de shell (~/.bashrc, ~/.zshrc o ~/.profile) que cargan nvm al abrir la terminal. Cierra y vuelve a abrir la terminal, o recárgala:

# Recarga la configuración del shell sin cerrar la terminal
source ~/.bashrc     # si usas bash
source ~/.zshrc      # si usas zsh

Comprueba que nvm responde:

command -v nvm
# Debe imprimir: nvm

Si imprime vacío, el script no se ha cargado. Revisa que las líneas de nvm estén en el fichero de configuración que tu terminal lee realmente (en macOS con zsh es ~/.zshrc).

Paso 2: instalar la última versión LTS

# Instala la última versión con soporte a largo plazo
nvm install --lts

nvm descarga el binario, lo coloca en ~/.nvm/versions/node/ y lo activa en la sesión actual.

# Ver todas las versiones instaladas en tu equipo
nvm ls

Salida de ejemplo:

->     v24.5.0
default -> lts/* (-> v24.5.0)
node -> stable (-> v24.5.0)
lts/* -> lts/krypton (-> v24.5.0)

Paso 3: fijar la versión por defecto

Sin este paso, cada terminal nueva abrirá sin ninguna versión activa.

# Que toda terminal nueva use la última LTS
nvm alias default 'lts/*'

Paso 4: conmutar entre versiones

nvm install 22          # Instalar también la línea 22 (LTS en mantenimiento)
nvm use 22              # Activarla en esta terminal
node -v                 # v22.x.y
nvm use --lts           # Volver a la LTS activa
node -v                 # v24.x.y

Resumen de comandos de nvm:

Comando Qué hace
nvm install --lts Instala la última versión LTS
nvm install 24.5.0 Instala una versión exacta
nvm use 24 Activa la 24 más reciente instalada, solo en esta terminal
nvm use Lee .nvmrc del directorio actual y activa esa versión
nvm ls Lista las versiones instaladas
nvm ls-remote --lts Lista las LTS disponibles para descargar
nvm alias default 'lts/*' Define la versión por defecto de las terminales nuevas
nvm uninstall 20 Elimina una versión que ya no necesitas
nvm current Muestra la versión activa

  1. Instalación en Windows: nvm-windows y fnm

En Windows, el nvm de Linux no funciona (es un script de shell). Tienes dos buenas opciones.

Opción A: nvm-windows

Descarga nvm-setup.exe desde el proyecto coreybutler/nvm-windows y ejecútalo. Después, en PowerShell como administrador la primera vez (nvm-windows crea un enlace simbólico en C:\Program Files\nodejs):

nvm install lts
nvm use 24.5.0
node -v

Diferencias respecto a nvm de Linux que conviene conocer:

  • No admite nvm alias default; la versión activa es global, no por terminal.
  • nvm use no lee .nvmrc automáticamente.
  • Requiere permisos de administrador para conmutar.

Opción B: fnm (recomendada si empiezas de cero)

fnm funciona igual en Windows, Linux y macOS, es muy rápido y sí lee .nvmrc.

# Con winget (incluido en Windows moderno)
winget install Schniz.fnm

# Instalar la última LTS y activarla
fnm install --lts
fnm use --lts
fnm default lts-latest

Para que fnm cambie de versión automáticamente al entrar en una carpeta con .nvmrc, añade a tu perfil de PowerShell (notepad $PROFILE):

fnm env --use-on-cd | Out-String | Invoke-Expression

Opción C: WSL

Si desarrollas para servidores Linux, la experiencia más fiel es usar WSL 2 (Windows Subsystem for Linux) e instalar dentro nvm siguiendo el apartado 2. Evita muchos problemas de rutas, permisos y finales de línea.

Aviso: no mezcles instalaciones. Si ya tenías Node instalado con el instalador oficial o con Chocolatey, desinstálalo antes de usar un gestor de versiones. Dos instalaciones compitiendo en el PATH producen errores desconcertantes ("tengo la 24 pero node -v dice 18").

  1. Verificación: qué se instala junto a Node

Abre una terminal nueva y ejecuta:

node -v     # v24.5.0
npm -v      # 11.x.y
npx -v      # 11.x.y

Si los tres responden, la instalación es correcta. Esto es lo que has obtenido:

Herramienta Qué es Ejemplo de uso
node El intérprete: ejecuta ficheros .js y abre el REPL node src/catalogo.js
npm Gestor de paquetes: instala dependencias y ejecuta scripts npm install express
npx Ejecuta un paquete sin instalarlo permanentemente npx cowsay hola
corepack Gestor de gestores: activa yarn o pnpm en la versión que pida el proyecto corepack enable pnpm

Sobre corepack: viene incluido con Node pero desactivado. Sirve para que, si un proyecto declara que usa [email protected], tú no tengas que instalarlo a mano. Se activa así:

corepack enable

En este curso usaremos npm, que es lo que trae Node por defecto. El detalle de npm y package.json es el objeto del Módulo 5; aquí solo verificamos que existe.

Una comprobación adicional útil: ejecutar código directamente desde la terminal.

node -e "console.log('Escena Viva listo en Node', process.version)"
Escena Viva listo en Node v24.5.0

  1. Elegir versión para un proyecto real: LTS vs Current

Recordemos la regla que vimos en la lección anterior y llevémosla a una decisión concreta:

Situación Versión recomendada Razón
Proyecto nuevo que irá a producción Última Active LTS Estabilidad, soporte de librerías y de proveedores de alojamiento
Proyecto heredado en producción La LTS que ya usa, con plan de migración No mezcles cambio de versión con cambio funcional
Probar una novedad del lenguaje Current en una carpeta aparte Nunca en el proyecto principal
Curso o aprendizaje Última Active LTS Es lo que encontrarás en el trabajo

Para Escena Viva elegimos la línea 24.x (Active LTS). Y, muy importante, lo dejamos escrito en el repositorio para que no dependa de la memoria de nadie.

  1. El fichero .nvmrc del proyecto

.nvmrc es un fichero de texto plano, en la raíz del proyecto, con una sola línea: la versión de Node que el proyecto necesita. Lo entienden nvm, fnm, Volta y la mayoría de sistemas de integración continua.

# Desde la raíz del proyecto, escribe la versión activa en .nvmrc
node -v > .nvmrc

Contenido resultante:

v24.5.0

También es válido y más flexible escribirlo a mano con la línea mayor, para recibir parches sin tocar el fichero:

lts/krypton

o simplemente:

24

A partir de ahora, cualquier persona que clone el repositorio de Escena Viva solo tiene que hacer:

cd escena-viva
nvm use          # Lee .nvmrc y activa la versión correcta
Found '/home/usuario/escena-viva/.nvmrc' with version <24>
Now using node v24.5.0 (npm v11.4.2)

Truco muy recomendable: configura tu shell para que ejecute nvm use automáticamente al entrar en una carpeta con .nvmrc. Con fnm basta la línea --use-on-cd que vimos antes; con nvm, la documentación oficial incluye una función cd para bash y zsh que hace lo mismo.

  1. Configuración del editor y de la terminal

Visual Studio Code

VS Code es el editor más habitual en el ecosistema Node, y funciona sin configuración. Estas extensiones marcan la diferencia:

Extensión Para qué sirve
ESLint Detecta errores y malos hábitos mientras escribes
Prettier Formatea el código automáticamente al guardar
npm Intellisense Autocompleta nombres de módulos en los require/import
DotENV Colorea ficheros .env (los usaremos en el Módulo 11)
REST Client o Thunder Client Prueba tus endpoints HTTP sin salir del editor (Módulos 4 y 6)
Error Lens Muestra el error en la propia línea, no solo en el panel
MongoDB for VS Code Útil a partir del Módulo 7

Ajustes recomendados para el proyecto. Crea escena-viva/.vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "files.eol": "\n",
  "files.trimTrailingWhitespace": true,
  "javascript.preferences.quoteStyle": "single",
  "terminal.integrated.defaultProfile.windows": "PowerShell"
}

"files.eol": "\n" merece una explicación: fuerza finales de línea de estilo Unix. Si trabajas en Windows y despliegas en Linux (lo normal), esto evita diferencias absurdas en el control de versiones y errores en scripts.

Ejecución integrada

Tienes tres formas de ejecutar un script desde VS Code:

  1. Terminal integrada (Ctrl+Ñ o Ctrl+`` ): escribe node src/catalogo.js. Es la forma que usaremos en el curso.
  2. Botón "Run": con un fichero .js abierto, F5 lanza el depurador de Node integrado.
  3. launch.json: configuración reutilizable. La veremos con detalle en Depuración de Aplicaciones Node.js.

La terminal

Recomendaciones prácticas:

  • Linux/macOS: bash o zsh, indistintamente. Añade el autocambio de versión con .nvmrc.
  • Windows: usa Windows Terminal con PowerShell 7, o directamente WSL. Evita cmd.exe.
  • Aprende dos atajos que usarás cada día: Ctrl+C para detener un proceso en marcha (un servidor, por ejemplo) y la flecha arriba para repetir el comando anterior.

  1. Creación de la carpeta del proyecto Escena Viva

Vamos a crear el esqueleto del proyecto. Elige una carpeta de trabajo (por ejemplo ~/proyectos) y ejecuta:

# Crear la estructura inicial de Escena Viva
mkdir -p escena-viva/src
mkdir -p escena-viva/datos
mkdir -p escena-viva/informes
cd escena-viva

En Windows con PowerShell:

New-Item -ItemType Directory -Path escena-viva\src, escena-viva\datos, escena-viva\informes -Force
Set-Location escena-viva

Fijamos la versión de Node del proyecto y arrancamos el control de versiones:

# Versión de Node del proyecto
node -v > .nvmrc

# Repositorio git (opcional pero muy recomendable)
git init

Creamos también un .gitignore mínimo. Aunque todavía no instalaremos dependencias, más vale prevenir:

printf 'node_modules/\n.env\ninformes/*.csv\n*.log\n' > .gitignore

Estructura resultante:

escena-viva/
├── .gitignore        # Qué no se sube al repositorio
├── .nvmrc            # Versión de Node del proyecto
├── datos/            # Ficheros de datos (eventos.json, ventas.csv)
├── informes/         # Salidas generadas por el programa
└── src/              # Código fuente JavaScript

Comprueba que todo está en su sitio:

ls -la

Sobre package.json: cuando ejecutes npm init -y tendrás un fichero package.json que describe el proyecto y sus dependencias. Aún no lo necesitamos: los primeros programas del curso funcionan solo con lo que trae Node. Lo estudiaremos a fondo en el Módulo 5.

  1. Permisos: por qué nunca debes usar sudo npm install -g

Este es el error de configuración más habitual en principiantes, y merece su propio apartado.

El síntoma

Instalas Node con el instalador oficial o con apt. Node queda en /usr/local o /usr, que pertenece a root. Intentas instalar una herramienta global:

npm install -g nodemon
npm error code EACCES
npm error syscall mkdir
npm error path /usr/lib/node_modules/nodemon
npm error errno -13
npm error Error: EACCES: permission denied

La reacción instintiva es anteponer sudo. No lo hagas.

Por qué es mala idea

Problema Consecuencia
Ejecutas scripts de terceros como root Un paquete malicioso o comprometido tiene control total de tu máquina; muchos paquetes ejecutan scripts postinstall
Se crean ficheros propiedad de root en tu caché Errores EACCES posteriores incluso en instalaciones normales, y una caché ~/.npm corrupta
Mezclas ámbitos de sistema y de usuario Actualizar o desinstalar se vuelve impredecible

La solución correcta

Usar un gestor de versiones. Con nvm o fnm, Node y los paquetes globales viven en tu carpeta personal (~/.nvm/versions/node/v24.5.0/lib/node_modules), donde ya tienes permisos. El error EACCES simplemente deja de existir:

npm install -g nodemon      # Sin sudo, sin errores

Si por alguna razón debes conservar una instalación de sistema, la alternativa oficial es cambiar el prefijo global a tu carpeta personal:

# Crear una carpeta propia para los paquetes globales
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global

# Añadirla al PATH (en ~/.bashrc o ~/.zshrc)
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Si ya has hecho el estropicio y tienes ficheros de root en tu caché, se repara así:

sudo chown -R $(whoami) ~/.npm

Regla de oro: en tu equipo de desarrollo, npm no debería necesitar sudo nunca. Si lo necesita, el problema está en cómo instalaste Node, no en npm.

Errores Comunes y Consejos

Error 1: command not found: nvm tras instalarlo. El script de nvm se carga desde el fichero de configuración del shell. Si usas zsh pero el instalador escribió en ~/.bashrc, no se cargará. Abre el fichero correcto y comprueba que contienen las líneas export NVM_DIR=... y el source de nvm.sh. Después, abre una terminal nueva.

Error 2: node -v devuelve una versión distinta a la que acabas de activar. Casi siempre hay dos instalaciones compitiendo. Diagnostícalo con:

which -a node     # Linux/macOS: muestra TODAS las rutas de node en el PATH
where.exe node    # Windows

Si aparece /usr/bin/node antes que la ruta de ~/.nvm, desinstala la versión del sistema.

Error 3: cada terminal nueva no tiene Node. Falta nvm alias default 'lts/*'.

Error 4: nvm use dice que no encuentra .nvmrc. Estás en un directorio que no es la raíz del proyecto. nvm use busca .nvmrc en el directorio actual y sus padres, no en subcarpetas hermanas.

Error 5: instalar Node desde el gestor del sistema en Ubuntu y encontrarse con una versión antiquísima. Los repositorios de las distribuciones estables suelen ir muy por detrás. Comprueba siempre con node -v qué versión ha entrado realmente.

Consejo 1: fija la versión también en el servidor. El .nvmrc no solo sirve en local; los sistemas de CI y muchas PaaS lo leen (Módulo 11).

Consejo 2: documenta el arranque. Aunque todavía no tengamos README, apunta en algún sitio los tres comandos necesarios para trabajar en el proyecto: nvm use, npm install, npm start. Tu yo futuro te lo agradecerá.

Consejo 3: no acumules versiones. Ejecuta nvm ls de vez en cuando y desinstala las que ya no usa ningún proyecto; cada una ocupa decenas de megabytes.

Ejercicios

Ejercicio 1: instalación verificada

  1. Instala Node.js con nvm (o fnm/nvm-windows si estás en Windows).
  2. Instala dos versiones: la última LTS y la línea 22.
  3. Fija la LTS como versión por defecto.
  4. Escribe los comandos que usarías para comprobar, desde cero en una terminal nueva, que todo está bien: versión de Node, de npm, de npx, y la lista de versiones instaladas.

Ejercicio 2: el esqueleto de Escena Viva

Crea la carpeta escena-viva/ con:

  • Subcarpetas src/, datos/ e informes/.
  • Un fichero .nvmrc con la versión LTS que has instalado.
  • Un .gitignore que excluya node_modules/, .env y los ficheros .log.

Después, escribe la secuencia de comandos que ejecutaría un compañero recién llegado para situarse en el proyecto con la versión de Node correcta, y comprueba que nvm use (o fnm use) responde leyendo el .nvmrc.

Ejercicio 3: diagnóstico de un entorno roto

Una compañera del equipo de Escena Viva te escribe: "He instalado nvm y he hecho nvm install --lts, pero cuando abro una terminal nueva node -v me dice v18.19.0. Además, si intento npm install -g nodemon me da EACCES y solo funciona con sudo."

  1. ¿Cuál es el diagnóstico más probable?
  2. ¿Qué comando le pedirías ejecutar para confirmarlo?
  3. Redacta los pasos de la solución.

Soluciones

Solución 1

# 1 y 2. Instalación de dos versiones
nvm install --lts        # Instala la última LTS (24.x)
nvm install 22           # Instala la última 22.x

# 3. Versión por defecto
nvm alias default 'lts/*'

# 4. Verificación en una terminal NUEVA
node -v      # v24.x.y  -> debe ser la LTS, no la 22
npm -v       # 11.x.y
npx -v       # 11.x.y
nvm ls       # Debe listar v22.x.y y v24.x.y, con default -> lts/*

Comprobación adicional de que el cambio funciona:

nvm use 22 && node -v     # v22.x.y
nvm use --lts && node -v  # v24.x.y

Solución 2

# Crear estructura
mkdir -p escena-viva/src escena-viva/datos escena-viva/informes
cd escena-viva

# Fijar versión del proyecto
node -v > .nvmrc
cat .nvmrc                # v24.5.0

# Ignorados de git
printf 'node_modules/\n.env\n*.log\n' > .gitignore
git init

Secuencia para el compañero recién llegado:

git clone <url-del-repositorio> escena-viva
cd escena-viva
nvm install     # Instala la versión de .nvmrc si no la tiene
nvm use         # La activa en esta terminal
node -v         # Debe coincidir con el contenido de .nvmrc

Nota: nvm use falla si la versión del .nvmrc no está instalada; por eso el nvm install previo (sin argumentos, también lee .nvmrc).

Solución 3

  1. Diagnóstico: hay una instalación previa de Node (del instalador oficial o del gestor de paquetes del sistema) en un directorio del sistema, y aparece antes que nvm en el PATH. Esa instalación es de root, lo que explica a la vez la versión inesperada (v18) y el error EACCES al instalar paquetes globales.

  2. Comando de confirmación:

which -a node
# Salida esperada, con la del sistema primero:
# /usr/bin/node
# /home/usuario/.nvm/versions/node/v24.5.0/bin/node

También ayuda npm config get prefix: si devuelve /usr o /usr/local, confirma el diagnóstico.

  1. Solución:
# a) Desinstalar la versión del sistema (ejemplo en Debian/Ubuntu)
sudo apt remove --purge nodejs npm
sudo apt autoremove

# b) Reparar la caché de npm si se usó sudo alguna vez
sudo chown -R $(whoami) ~/.npm

# c) Abrir una terminal NUEVA y verificar
which -a node    # Solo debe aparecer la ruta bajo ~/.nvm
node -v          # La LTS instalada con nvm
npm install -g nodemon    # Ahora funciona SIN sudo

Si por política de la empresa no puede desinstalar la versión del sistema, la alternativa es asegurarse de que la línea de nvm en ~/.bashrc se ejecuta al final del fichero, para que su ruta quede primera en el PATH.

Conclusión

Ya tienes un entorno de desarrollo profesional. Hemos visto que existen tres formas de instalar Node.js y por qué un gestor de versiones (nvm, fnm o nvm-windows) es la única que soporta bien la realidad de trabajar con varios proyectos: permite instalar varias versiones, conmutar entre ellas al instante y —detalle nada menor— elimina de raíz los problemas de permisos que llevan a la mala práctica de sudo npm install -g.

Has instalado la última Active LTS, has comprobado que node, npm, npx y corepack responden, has configurado el editor con las extensiones que usarás durante el curso y has creado la carpeta escena-viva/ con sus directorios src/, datos/ e informes/, un .gitignore y un .nvmrc que documenta la versión del proyecto para todo el equipo.

La carpeta está creada pero vacía. En la siguiente lección, Tu Primer Programa en Node.js, escribiremos src/catalogo.js: el primer programa real de Escena Viva, que define el catálogo de eventos del Teatro Almendra, la Sala Bóveda y el Auditorio Ribera, lo muestra formateado por consola y aprende a recibir argumentos desde la línea de comandos.

◄ Anterior
◄
Siguiente ►
►

Curso de Node.js: De Principiante a Avanzado

Módulo 1: Introducción a Node.js

Módulo 2: Conceptos Básicos

Módulo 3: Sistema de Archivos y E/S

Módulo 4: HTTP y Servidores Web

Módulo 5: NPM y Gestión de Paquetes

Módulo 6: Framework Express.js

Módulo 7: Bases de Datos y ORMs

Módulo 8: Autenticación y Autorización

Módulo 9: Pruebas y Depuración

Módulo 10: Temas Avanzados

Módulo 11: Despliegue y DevOps

Módulo 12: Proyectos del Mundo Real

El Proyecto | Sobre nosotros | Contribuir | Donaciones | Licencia
© Copyright 2026. Todos los derechos reservados