Webpack Dev Server Wait Page

Common errors

• TypeError: Cannot read property 'includes' of undefined

  cause This error occurred in versions prior to 2.1.1, often when `disableWhenValid` was set to `false` and an internal property was unexpectedly undefined.
  fix Upgrade to `webpack-dev-server-waitpage` version 2.1.1 or higher to resolve this specific bug.

• webpack-dev-server-waitpage is not a function

  cause This typically happens if you are trying to use the main import as a constructor or a direct middleware when it expects a factory invocation, or if using `require` with an ESM-only package.
  fix Ensure you are using `import webpackDevServerWaitpage from 'webpack-dev-server-waitpage';` and then invoking it correctly as `webpackDevServerWaitpage(server, options)` for the middleware or `webpackDevServerWaitpage.plugin()` for the plugin. For CommonJS, use `const webpackDevServerWaitpage = require('webpack-dev-server-waitpage');`.

• webpack-dev-server throws an error about `before` hook not existing or not being a function (or similar for `onBeforeSetupMiddleware`)

  cause You are likely using a `webpack-dev-server` version that expects a different middleware setup hook (e.g., using `before` with `webpack-dev-server` v4+ or `onBeforeSetupMiddleware` with v3).
  fix Adjust your `webpack.config.js` to use the correct `devServer` hook for your `webpack-dev-server` version: `onBeforeSetupMiddleware` for v4+ or `before` for v3.

Warnings

• breaking Version 2.0.0 introduced support for Webpack 5, which often requires updating `webpack-dev-server` configuration. Specifically, the `devServer.before` hook was replaced by `devServer.onBeforeSetupMiddleware` in `webpack-dev-server` v4 and later. Users upgrading from `webpack-dev-server` v3 will need to adapt their configuration.
  Fix: For `webpack-dev-server` v4+, use `devServer: { onBeforeSetupMiddleware: (server) => { server.app.use(webpackDevServerWaitpage(server, options)); } }`. For `webpack-dev-server` v3, use `devServer: { before: (app, server) => { app.use(webpackDevServerWaitpage(server, options)); } }`.
• breaking Prior to v0.3.0, the library's integration method changed significantly. v0.2.0 made the middleware a factory (requiring `webpackServeWaitpage.middleware()` instead of direct use), and v0.3.0 indicated it was middleware-only, removing the explicit plugin step. However, later versions (including current v3) *re-established* the need for both a plugin and middleware, creating a potentially confusing historical migration path. Always follow the current README's usage instructions.
  Fix: Consult the usage section of the README for your specific version. Current versions (>=1.0.0) require both `webpackDevServerWaitpage.plugin()` in the `plugins` array and `app.use(webpackDevServerWaitpage(server, options))` in the `devServer` middleware hook.
• gotcha The `disableWhenValid` option defaults to `true`. This means the wait page will stop appearing after the *first* successful compilation. If you intend for the wait page to show on subsequent hot full-page reloads (e.g., after a full-page refresh due to HMR failure), you must explicitly set `disableWhenValid: false` in the middleware options.
  Fix: Set `disableWhenValid: false` in the options object passed to the middleware: `server.app.use(webpackDevServerWaitpage(server, { disableWhenValid: false }));`
• gotcha Ensure `webpack-dev-server-waitpage`'s middleware is added correctly within the `devServer` configuration's `onBeforeSetupMiddleware` (Webpack Dev Server v4+) or `before` (Webpack Dev Server v3) hook. It must receive the `server` object provided by `webpack-dev-server` to function correctly.
  Fix: Correctly pass the `server` object: `server.app.use(webpackDevServerWaitpage(server, options));` (v4+) or `app.use(webpackDevServerWaitpage(server, options));` (v3).

Install

• npm install webpack-dev-server-waitpage npm
• yarn add webpack-dev-server-waitpage yarn
• pnpm add webpack-dev-server-waitpage pnpm

Imports

• webpackDevServerWaitpage
  wrong:

  const webpackDevServerWaitpage = require('webpack-dev-server-waitpage');

  correct:

  import webpackDevServerWaitpage from 'webpack-dev-server-waitpage';

  While CommonJS `require` works, ESM `import` is preferred for modern projects and better tooling support, especially with TypeScript. The main export is the middleware factory function.
• plugin
  wrong:

  import { plugin } from 'webpack-dev-server-waitpage';

  correct:

  import webpackDevServerWaitpage from 'webpack-dev-server-waitpage';
  const plugin = webpackDevServerWaitpage.plugin();

  The `plugin` factory is a property of the default export, not a named export itself.
• WaitpageOptions

  import type { WaitpageOptions } from 'webpack-dev-server-waitpage';

  Import types explicitly from the package if using TypeScript.

Quickstart

This quickstart demonstrates how to integrate `webpack-dev-server-waitpage` into a TypeScript Webpack 5 project. It shows adding both the plugin to the `plugins` array and the middleware to the `devServer.onBeforeSetupMiddleware` hook, configured with a 'material' theme and custom title.

import path from 'path';
import { Configuration } from 'webpack';
import webpackDevServerWaitpage from 'webpack-dev-server-waitpage';

const config: Configuration = {
  mode: 'development',
  entry: './src/index.ts',
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, 'dist'),
    publicPath: '/',
  },
  module: {
    rules: [
      {
        test: /\.ts$/,
        use: 'ts-loader',
        exclude: /node_modules/,
      },
      {
        test: /\.css$/,
        use: ['style-loader', 'css-loader'],
      },
    ],
  },
  resolve: {
    extensions: ['.ts', '.js', '.json'],
  },
  plugins: [
    // Add the waitpage plugin to the webpack plugins array
    webpackDevServerWaitpage.plugin(),
  ],
  devServer: {
    port: 8080,
    open: true,
    hot: true,
    // For webpack-dev-server@4+, use onBeforeSetupMiddleware
    onBeforeSetupMiddleware: (server) => {
      // Pass the server instance to the waitpage middleware
      server.app.use(webpackDevServerWaitpage(server, { theme: 'material', title: 'Loading App...' }));
    },
    // For webpack-dev-server@3, use before
    // before: (app, server) => {
    //   app.use(webpackDevServerWaitpage(server, { theme: 'material', title: 'Loading App...' }));
    // },
  },
};

export default config;