Nivel inicial9 min de lectura · Publicado el

Reinicio automático en Node: node --watch y nodemon

Reinicio automático del servidor Node: al guardar app.js, node --watch lo reinicia solo y muestra Restarting 'app.js'. Guardas y Node se reiniciarubentejera.com --watchapp.jsguardasse reinicia solaRestarting 'app.js'
Echar ropa es guardar app.js: con node --watch, Node vigila el fichero y los módulos que carga y reinicia el servidor solo, sin Ctrl + C. Si quieres más control, nodemon hace lo mismo con más opciones.

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 start y 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

  1. Arranca el servidor de Express con npm run dev usando node --watch.
  2. Crea un fichero src/mensaje.txt, léelo en la ruta / con fs.readFileSync y cambia su texto: comprueba que el servidor no se reinicia.
  3. Cambia el script a node --watch-path=src --watch-path=. app.js y 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: --watch y --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-path solo 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.