webpack-serve-waitpage

1.0.2 verified Sat Apr 25 auth: no javascript

A middleware plugin for webpack-serve that displays a progress page during webpack compilation, replacing the default blank page with a customizable wait screen. Current stable version is 3.0.0 (supports webpack 5 and Node 18). This package is specific to the legacy webpack-serve (v1/v2), not webpack-dev-server. Alternatives include webpack-dev-server's built-in progress overlay or separate plugins like webpack-dashboard.

Common errors

error Error: Cannot find module 'webpack-serve-waitpage' ↓

cause Package not installed or misspelled.

fix

Run npm install -D webpack-serve-waitpage

error TypeError: webpackServeWaitpage is not a function ↓

cause Importing incorrectly – e.g., using default import in ESM or accessing .middleware.

fix

Use const webpackServeWaitpage = require('webpack-serve-waitpage'); and call it directly.

error Cannot read property 'includes' of undefined ↓

cause Bug in v2.1.1 when disableWhenValid is false.

fix

Upgrade to v2.1.0 or v3.0.0.

Warnings

breaking Changed from plugin to middleware. In v0.2.0, you had to use webpackServeWaitpage.middleware(). In v0.3.0, you must use the default export directly: app.use(webpackServeWaitpage(options)). ↓

fix Update usage: remove .middleware() call. See quickstart.

breaking Option 'disableWhenValid' default changed to true in v1.0.0. ↓

fix If you rely on the wait page always showing, set disableWhenValid: false explicitly.

gotcha Package works only with webpack-serve, not webpack-dev-server. Despite similar names, webpack-serve is a separate tool. ↓

fix Use webpack-dev-server-waitpage for webpack-dev-server.

deprecated Node.js 10 and below are not supported in v3.0.0. ↓

fix Upgrade Node.js to v12 or later.

gotcha In v2.0.0, support for webpack 5 was added, but configuration path may differ. Ensure webpack-serve is compatible with webpack 5. ↓

fix Check webpack-serve compatibility; see migration guides.

Install

npm install webpack-serve-waitpage

yarn add webpack-serve-waitpage

pnpm add webpack-serve-waitpage

Imports

default

wrong

import webpackServeWaitpage from 'webpack-serve-waitpage';

correct

const webpackServeWaitpage = require('webpack-serve-waitpage');

This package is CommonJS only and does not ship ESM. Use require().

types

wrong

import { WaitpageOptions } from 'webpack-serve-waitpage';

correct

// Types are already included in the package; no separate import needed

TypeScript definitions are included but not exported; use JSDoc comments or rely on inference.

middleware invocation
wrong
```
app.use(webpackServeWaitpage.middleware(options));
```
correct
```
app.use(webpackServeWaitpage(options));
```
In versions <0.3.0, .middleware() was required. Since 0.3.0, the default export is the factory directly.

Quickstart

Shows how to integrate webpack-serve-waitpage as middleware in a webpack-serve config, with custom theme and disableWhenValid option.

const webpackServeWaitpage = require('webpack-serve-waitpage');

module.exports = {
  // ... other webpack config
  serve: {
    add: (app, middleware, options) => {
      app.use(webpackServeWaitpage(options, {
        theme: 'material',
        disableWhenValid: true
      }));
    }
  }
};