Reinicio automático en Node: node --watch y nodemon
Cambias una línea del servidor, vas al navegador, recargas… y no ha cambiado nada. Se te olvidó parar el servidor con Ctrl + C y volver a arrancarlo. Node carga el código al arrancar y no vuelve a leerlo.
El modo vigilancia es como una lavadora que se pone sola en marcha cada vez que echas ropa: tú solo guardas el fichero y el servidor se reinicia.
Opción 1: node --watch, sin instalar nada
Parte del servidor del artículo de instalación de Express.js, en un fichero app.js, y arráncalo así:
node --watch app.js
Node vigila el fichero de entrada (app.js) y todos los módulos que carga con require o import. Cuando guardas cualquiera de ellos, reinicia el proceso. Al cambiar el texto de la respuesta en app.js y guardar, la terminal muestra:
Example app listening on port 3000
Change detected in '/tmp/myapp/app.js'
Restarting 'app.js'
Example app listening on port 3000
Por defecto, Node borra la consola en cada reinicio, así que en tu terminal quizá solo veas las últimas líneas. Si quieres conservar lo anterior, añade --watch-preserve-output.
Opciones útiles:
| Opción | Qué hace |
|---|---|
--watch |
Reinicia al cambiar el fichero de entrada o sus módulos |
--watch-path=src |
Vigila solo esa carpeta (y deja de vigilar los módulos) |
--watch-preserve-output |
No borra la consola en cada reinicio |
--watch-kill-signal SIGINT |
Cambia la señal con la que se para el proceso antes de reiniciarlo (desde Node 24.4 y 22.18, todavía en desarrollo) |
--watch y --watch-path son estables desde Node 22.0 (y 20.13): ya no son experimentales y no muestran ningún aviso al arrancar. Si usas una versión anterior, actualiza Node o usa nodemon. Para cambiar de versión con facilidad, tienes NVM.
Vigilar una carpeta con --watch-path
--watch solo ve lo que el programa carga. Si tus plantillas HTML están en src/ y no se importan, cambiarlas no reinicia nada. --watch-path le dice a Node qué vigilar:
node --watch-path=src app.js
Example app listening on port 3000
Change detected in '/tmp/myapp/src/plantilla.html'
Restarting 'app.js'
Example app listening on port 3000
Ten en cuenta que, con --watch-path, Node deja de vigilar los módulos: en la misma prueba, un cambio en app.js ya no reinició el servidor. Si quieres las dos cosas, añade un --watch-path por cada carpeta, también la del código.
Variables de entorno con --env-file
Si cargas la configuración con --env-file, el modo vigilancia también reinicia al cambiar ese fichero. Con const port = process.env.PORT || 3000; en app.js, un .env con PORT=4000 y este comando:
node --env-file=.env --watch app.js
Al cambiar el .env a PORT=4001 y guardar:
Example app listening on port 4000
Change detected in '/tmp/myapp/.env'
Restarting 'app.js'
Example app listening on port 4001
También para los tests
El mismo modo sirve para el ejecutor de tests de Node: node --test --watch vuelve a pasar los tests cada vez que guardas. Con un suma.js y su suma.test.js:
// suma.test.js
const test = require('node:test');
const assert = require('node:assert');
const suma = require('./suma');
test('suma dos números', () => {
assert.strictEqual(suma(2, 3), 5);
});
node --test --watch
Si rompes suma.js (por ejemplo, cambiando a + b por a - b) y guardas, los tests se repiten solos y te avisan:
Restarted at 11/12/2026, 9:43:40 AM
✖ suma dos números (1.249431ms)
ℹ tests 1
ℹ pass 0
ℹ fail 1
Si quieres empezar con los tests en Node, tienes cómo instalar Jest en un proyecto de JavaScript; node:test hace lo mismo sin instalar nada.
Opción 2: nodemon
nodemon es la herramienta clásica para esto y sigue mantenida. Instálala solo en el proyecto, como dependencia de desarrollo:
npm install --save-dev nodemon
npx nodemon app.js
Al guardar un cambio en el código:
[nodemon] 3.1.14
[nodemon] to restart at any time, enter `rs`
[nodemon] watching path(s): *.*
[nodemon] watching extensions: js,mjs,cjs,json
[nodemon] starting `node app.js`
Example app listening on port 3000
[nodemon] restarting due to changes...
[nodemon] starting `node app.js`
Example app listening on port 3000
Frente a --watch, nodemon vigila toda la carpeta (no solo los módulos cargados), pero solo las extensiones de la lista: js,mjs,cjs,json. Para añadir otras, usa --ext:
npx nodemon --ext js,html app.js
[nodemon] watching extensions: js,html
Con eso, guardar un .html también reinicia. Además, nodemon deja elegir carpetas con --watch y reinicia cuando escribes rs y pulsas Intro.
Cuál elegir
| Situación | Elige |
|---|---|
| Proyecto nuevo con Node 22 o posterior | node --watch: una dependencia menos |
Quieres reiniciar también al cambiar ficheros que no se importan (plantillas, .yaml) |
nodemon con --ext, o node --watch-path apuntando a esa carpeta |
Cambias variables de entorno en un .env |
node --env-file=.env --watch |
| Necesitas reiniciar a mano sin parar el proceso | nodemon, escribiendo rs |
| Node 18 o anterior | nodemon (o, mejor, actualiza Node) |
Guárdalo como script de npm
Para no recordar el comando, añádelo a package.json:
{
"scripts": {
"start": "node app.js",
"dev": "node --watch app.js"
}
}
Con nodemon, el script dev sería "nodemon app.js". Arranca en desarrollo con npm run dev y en producción con npm start, sin vigilancia.
En desarrollo, que se reinicie solo; en producción, nunca.
Errores frecuentes
1. nodemon: command not found. Lo has instalado como dependencia del proyecto y lo llamas directamente:
bash: nodemon: command not found
Los programas de las dependencias locales no están en tu PATH. Llámalo con npx nodemon app.js o desde un script de package.json, donde npm sí los encuentra.
2. El puerto ya está ocupado. Si dejaste otro node app.js abierto en otra terminal, el servidor vigilado no puede arrancar. --watch no termina: se queda esperando a que cambies algo. Esta es la salida, recortada (… marca las líneas quitadas):
Error: listen EADDRINUSE: address already in use :::3000
…
code: 'EADDRINUSE',
errno: -98,
syscall: 'listen',
address: '::',
port: 3000
}
Node.js v24.22.3
Failed running 'app.js'. Waiting for file changes before restarting...
Cierra el otro proceso (si no sabes cuál es, mira cómo matar un proceso en Linux) y guarda cualquier fichero para que vuelva a intentarlo.
3. Guardas y no se reinicia. No sale ningún mensaje porque el fichero que has cambiado no está vigilado: con --watch, Node solo ve lo que se importa, y nodemon solo las extensiones de su lista. En la prueba, ni un notas.txt en la carpeta del proyecto reinició node --watch ni nodemon. Usa --watch-path, --env-file o --ext según el caso, como se explica arriba.
Cuándo no usarlo
- En producción. En un servidor real no quieres reinicios porque cambie un fichero: cada reinicio para el proceso, con las peticiones que esté atendiendo. Ahí se arranca con
npm starty se reinicia al desplegar, con el gestor de procesos o la plataforma que uses. - Cuando el arranque es lento. Si el servidor tarda en arrancar (conecta a una base de datos, carga datos…), cada vez que guardas lo pagas. Mantén los tests rápidos y separados del servidor.
Ejercicio de cinco minutos
- Arranca el servidor de Express con
npm run devusandonode --watch. - Crea un fichero
src/mensaje.txt, léelo en la ruta/confs.readFileSyncy cambia su texto: comprueba que el servidor no se reinicia. - Cambia el script a
node --watch-path=src --watch-path=. app.jsy repite la prueba.
Fuentes
- Documentación de Node.js, opciones de línea de comandos de la versión 24 y de la versión 26:
--watchy--watch-path(estables desde v22.0.0 y v20.13.0),--watch-preserve-output,--watch-kill-signal(añadida en v24.4.0 y v22.18.0, según la documentación de v26; en desarrollo activo) y el aviso de que--watch-pathsolo está soportado en macOS y Windows. Las dos versiones dicen lo mismo. - nodemon en npm: versión 3.1.14, la última publicada, comprobada con
npm view nodemon version.
Ejecutado el 12 de noviembre de 2026 en Docker con las imágenes oficiales node:24 (Node 24.22.3) y node:26 (Node 26.13.1), Express 5.3.0 y nodemon 3.1.14, con el mismo resultado en las dos: node --watch con cambios en app.js, en un módulo importado y en un fichero no importado; --watch-path en Linux; --env-file con --watch; node --test --watch; nodemon con y sin --ext, y los errores de este artículo. Las salidas son las reales de Node 24.22.3; las de Node 26.13.1 solo cambian en la versión. Las salidas de los procesos vigilados se capturaron redirigidas a un fichero.