Registry / web-framework / webpack-dev-server-waitpage

webpack-dev-server-waitpage

library3.0.0jsnpmunverified

webpack-dev-server-waitpage provides a visual progress page for `webpack-dev-server`, displaying compilation status to users instead of a blank screen during development. It is currently at version 3.0.0, offering compatibility with modern Node.js environments and Webpack 5. The package aims to improve developer experience by offering immediate visual feedback on the build process. It differentiates itself through customizable themes (default, dark, material) and support for custom EJS templates, allowing developers to brand or tailor the waiting experience. The library functions as both a Webpack plugin and a `webpack-dev-server` middleware, supporting multiple Webpack configurations. Release cadence is driven primarily by updates to Webpack and `webpack-dev-server` itself, ensuring continued compatibility.

web-framework

npm install webpack-dev-server-waitpage

github ↗package ↗

INSTALL

IMPORT

SIG · WEBPACK-DEV-SERVER

webpack-dev-server-waitpage

web-frameworkjavascriptv3.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

webpackDevServerWaitpage

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

✗ const webpackDevServerWaitpage = require('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

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

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

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.

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;

Debug

Known issues

breakingVersion 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)); } }`.

affects: >=2.0.0

breakingPrior 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.

affects: <=0.3.0

gotchaThe `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 }));`

affects: >=1.0.0

gotchaEnsure `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).

affects: >=0.2.0

Errors

Common errors & fixes

TypeError: Cannot read property 'includes' of undefined

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

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`)

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.

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

webpackrequiredPeer dependency for core Webpack functionality. Supports ^4 || ^5.

webpack-dev-serverrequiredMiddleware integrates with webpack-dev-server's internal application hooks.

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/elisherer/webpack-dev-server-waitpage ↗

packagehttps://www.npmjs.com/package/webpack-dev-server-waitpage ↗