node-hmr

node-hmr

🔥 Hot Module Replacement for Node.js

This module adds hot module replacement support for node.js applications, it intended as an alternative to such tools like nodemon. Reloading modules while an application is running significantly faster than full reloading which in some cases may add additional downtime to a development process.

Inspired by this article https://codeburst.io/dont-use-nodemon-there-are-better-ways-fc016b50b45e

API

hmr(callback, [options])

• callback Function which will be called each time when some file was changed
• options Options object. Optional
  • debug Show list of modules which was removed from the cache. Default: false
  • watchDir Relative path to the directory to be watched recursively. Default: directory of the current module
  • watchFilePatterns Files that will trigger reload on change. Default: JS files
  • chokidar Chokidar options

Usage

const hmr = require('node-hmr');

hmr(() => {
  require('./path_to_your_script');
});

How to use it with frameworks

You should split your application into two parts first is server setup and second is application module. Below are examples of how to use it with some popular frameworks.

Typescript + Express.js example

app.ts

import express, { Application, Request, Response, NextFunction, } from 'express';
const app: Application = express();

app.get('/', (req: Request, res: Response, next: NextFunction) => {
  res.send('Express app');
});

export default app;

index.ts

import http from 'http';
import hmr from 'node-hmr';

let app: http.RequestListener;

hmr(async () => {
  console.log('Reloading app...');
  ({ default: app } = await import('./app'));
});

const server = http.createServer((req, res) => app(req, res));

server.listen(3000);

Express.js example

app.js

const express = require('express');
const app = express();

app.get('/', (req, res, next) => {
  res.send('Express');
});

module.exports = app;

bin/www

const http = require('http');
const hmr = require('node-hmr');

let app;

hmr(() => {
  app = require('../app');
}, { watchDir: '../', watchFilePatterns: ['**/*.js'] });

const server = http.createServer((req, res) => app(req, res));

server.listen(3000);

Koa.js with HMR example

app.js

const Koa = require('koa');
const app = new Koa();

app.use(async ctx => {
  ctx.body = 'Koa';
});

module.exports = app;

index.js

const hmr = require('node-hmr');

let callback;
hmr(() => {
  const app = require('./app');
  callback = app.callback();
});

const server = http.createServer((req, res) => callback(req, res));
server.listen(3000);

Limitations

In some cases, HMR may not work correctly with libraries which using some internal caching storage Mongoose is the example of one. If you see this error message Cannot overwrite `User` model once compiled the workaround could be add the following syntax to each model declaration, but in this case changes to the model will not be 'hot reloaded'.

module.exports = mongoose.models.Users || mongoose.model('Users', UsersSchema);

License

MIT

Changelog

1.4.0 (2023-02-19)

Features

• Typescript support (5481b11)

1.3.2 (2023-01-15)

Bug Fixes

• #19 Handle thrown error by callback function (8ebb8f1)

1.3.1 (2021-11-17)