tessl/npm-webpack-hot-middleware

Webpack hot reloading middleware that can be attached to your own server

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Webpack Hot Middleware

Name: tessl/npm-webpack-hot-middleware
Author: tessl

Webpack Hot Middleware provides webpack hot module replacement (HMR) for custom server setups without requiring webpack-dev-server. It acts as a bridge between webpack's compilation process and browser clients using Server-Sent Events to communicate build updates and coordinate hot module replacement through webpack's HMR API.

Package Information

Package Name: webpack-hot-middleware
Package Type: npm
Language: JavaScript
Installation: npm install --save-dev webpack-hot-middleware

Core Imports

const webpackHotMiddleware = require("webpack-hot-middleware");

For client-side integration:

// In webpack entry configuration
entry: {
  main: ['webpack-hot-middleware/client', './src/main.js']
}

Basic Usage

const webpack = require('webpack');
const express = require('express');
const webpackDevMiddleware = require('webpack-dev-middleware');
const webpackHotMiddleware = require('webpack-hot-middleware');

const app = express();
const config = require('./webpack.config.js');
const compiler = webpack(config);

// Add webpack-dev-middleware
app.use(webpackDevMiddleware(compiler, {
  publicPath: config.output.publicPath
}));

// Add webpack-hot-middleware
app.use(webpackHotMiddleware(compiler));

app.listen(3000);

Architecture

Webpack Hot Middleware operates through several key components:

Server Middleware: Express/Connect-compatible middleware that manages webpack compiler events and client connections
Event Stream: Server-Sent Events (SSE) communication layer for real-time updates between server and clients
Client Runtime: Browser-side JavaScript that connects to the event stream and applies HMR updates
Error Overlay: Optional browser overlay displaying compilation errors and warnings
Update Processing: Module update detection and application using webpack's HMR API

Capabilities

Server Middleware

The main middleware factory function that creates HMR middleware for a webpack compiler.

/**
 * Creates webpack hot middleware for a compiler instance
 * @param {Object} compiler - webpack compiler instance
 * @param {Object} opts - Configuration options
 * @returns {Function} Express/Connect-compatible middleware with additional methods
 */
function webpackHotMiddleware(compiler, opts);

interface MiddlewareOptions {
  /** Function for logging or false to disable (default: console.log) */
  log?: Function | false;
  /** Path for event stream endpoint (default: '/__webpack_hmr') */
  path?: string;
  /** Heartbeat interval in milliseconds (default: 10000) */
  heartbeat?: number;
  /** Stats configuration object (default: {}) */
  statsOptions?: Object;
}

The middleware function includes additional methods:

interface MiddlewareInstance {
  /** Manually publish events to connected clients */
  publish(payload: Object): void;
  /** Close the middleware and clean up resources */
  close(): void;
}

Usage Example:

const webpackHotMiddleware = require('webpack-hot-middleware');

// Basic usage
const hotMiddleware = webpackHotMiddleware(compiler);
app.use(hotMiddleware);

// With options
const hotMiddleware = webpackHotMiddleware(compiler, {
  log: console.log,
  path: '/__webpack_hmr',
  heartbeat: 10 * 1000
});
app.use(hotMiddleware);

// Manual event publishing
hotMiddleware.publish({ 
  action: 'reload' 
});

// Cleanup
hotMiddleware.close();

Client Integration

Client-side module that connects to the HMR server and handles module updates.

/**
 * Client module exports when used as CommonJS module
 */
interface ClientExports {
  /** Subscribe to all HMR events */
  subscribeAll(handler: Function): void;
  /** Subscribe to custom HMR events */
  subscribe(handler: Function): void;
  /** Replace default error overlay with custom implementation */
  useCustomOverlay(customOverlay: Object): void;
  /** Set client options and establish connection */
  setOptionsAndConnect(overrides: Object): void;
}

Usage Examples:

// As webpack entry (automatic connection)
entry: {
  main: ['webpack-hot-middleware/client', './src/main.js']
}

// As module for custom handling
const client = require('webpack-hot-middleware/client');

client.subscribe(function(obj) {
  if (obj.action === 'reload') {
    window.location.reload();
  }
});

client.subscribeAll(function(obj) {
  console.log('HMR event:', obj);
});

Client Configuration

Client behavior can be configured via query parameters when including in webpack entry.

interface ClientOptions {
  /** Event stream endpoint path (default: '/__webpack_hmr') */
  path?: string;
  /** Bundle name for multi-compiler mode */
  name?: string;
  /** Reconnection timeout in milliseconds (default: 20000) */
  timeout?: number;
  /** Enable/disable error overlay (default: true) */
  overlay?: boolean;
  /** Enable auto-reload on webpack stuck (default: false) */
  reload?: boolean;
  /** Disable informational logging (default: false) */
  noInfo?: boolean;
  /** Disable all console logging (default: false) */
  quiet?: boolean;
  /** Use webpack publicPath as path prefix (default: false) */
  dynamicPublicPath?: boolean;
  /** Auto-connect to server (default: true) */
  autoConnect?: boolean;
  /** Custom ANSI colors for overlay */
  ansiColors?: Object;
  /** Custom styles for error overlay */
  overlayStyles?: Object;
  /** Show overlay for warnings (default: false) */
  overlayWarnings?: boolean;
}

Configuration Examples:

// Basic client configuration
entry: {
  main: [
    'webpack-hot-middleware/client?path=/__webpack_hmr&timeout=20000&reload=true',
    './src/main.js'
  ]
}

// Multi-compiler configuration
module.exports = [
  {
    name: 'mobile',
    entry: {
      main: ['webpack-hot-middleware/client?name=mobile', 'mobile.js']
    }
  },
  {
    name: 'desktop', 
    entry: {
      main: ['webpack-hot-middleware/client?name=desktop', 'desktop.js']
    }
  }
];

// Custom overlay colors and styles
const ansiColors = { red: '00FF00' };
const overlayStyles = { color: '#FF0000' };
const clientScript = 'webpack-hot-middleware/client?ansiColors=' + 
  encodeURIComponent(JSON.stringify(ansiColors)) + 
  '&overlayStyles=' + encodeURIComponent(JSON.stringify(overlayStyles));

Error Overlay

Browser overlay system for displaying compilation errors and warnings.

/**
 * Creates customizable error overlay for browser
 * @param {Object} options - Configuration with ansiColors and overlayStyles
 * @returns {Object} Overlay instance with control methods
 */
function createOverlay(options: OverlayOptions): OverlayInstance;

interface OverlayOptions {
  /** Custom ANSI color mappings */
  ansiColors?: Object;
  /** Custom CSS styles for overlay element */
  overlayStyles?: Object;
}

interface OverlayInstance {
  /** Display compilation problems in overlay */
  showProblems(type: 'errors' | 'warnings', lines: string[]): void;
  /** Remove overlay from DOM */
  clear(): void;
}

Usage Example:

const createOverlay = require('webpack-hot-middleware/client-overlay');

const overlay = createOverlay({
  ansiColors: {
    red: 'ff0000',
    yellow: 'ffff00'
  },
  overlayStyles: {
    fontSize: '14px',
    fontFamily: 'Monaco, monospace'
  }
});

// Show errors
overlay.showProblems('errors', [
  'Module not found: Error: Cannot resolve module "missing-module"'
]);

// Clear overlay
overlay.clear();

Helper Utilities

Utility functions used internally by the middleware.

/**
 * URL path matching utility
 * @param {string} url - URL string to test
 * @param {string} path - Path string to match against  
 * @returns {boolean} True if paths match
 */
function pathMatch(url: string, path: string): boolean;

Event Protocol

The middleware communicates with clients using a defined event protocol over Server-Sent Events.

Server to Client Events

interface HMREvent {
  /** Event action type */
  action: 'building' | 'built' | 'sync';
  /** Bundle name (for multi-compiler) */
  name?: string;
  /** Build completion time in milliseconds */
  time?: number;
  /** Build hash string */
  hash?: string;
  /** Compilation warnings */
  warnings?: string[];
  /** Compilation errors */
  errors?: string[];
  /** Module ID to name mapping */
  modules?: Object;
}

Event Types

building: Emitted when webpack starts rebuilding
built: Emitted when webpack completes a build
sync: Emitted when a client first connects to sync current state

Multi-Compiler Support

Webpack Hot Middleware supports webpack's multi-compiler mode for handling multiple webpack configurations simultaneously.

Configuration:

// webpack.config.js
module.exports = [
  {
    name: 'client',
    entry: {
      main: ['webpack-hot-middleware/client?name=client', './src/client.js']
    },
    // ... other client config
  },
  {
    name: 'server',
    entry: {
      main: ['webpack-hot-middleware/client?name=server', './src/server.js']  
    },
    // ... other server config
  }
];

// Server setup
const compiler = webpack(configs);
app.use(webpackHotMiddleware(compiler));

Error Handling

The middleware handles various error conditions and provides fallback mechanisms:

Connection Loss: Automatic reconnection with configurable timeout
Build Errors: Error overlay display with ANSI color support
Update Failures: Fallback to full page reload when HMR fails
Module Rejection: Graceful handling of modules that can't be hot updated

Webpack Configuration

Required webpack configuration for hot module replacement:

// webpack.config.js
const webpack = require('webpack');

module.exports = {
  plugins: [
    new webpack.HotModuleReplacementPlugin()
  ],
  entry: {
    main: ['webpack-hot-middleware/client', './src/main.js']
  }
};

docs

index.md

tile.json

tessl/npm-webpack-hot-middleware

index.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Webpack Hot Middleware

Package Information

Core Imports

Basic Usage

Architecture

Capabilities

Server Middleware

Client Integration

Client Configuration

Error Overlay

Helper Utilities

Event Protocol

Server to Client Events

Event Types

Multi-Compiler Support

Error Handling

Webpack Configuration

index.mddocs/