{"id":15407,"library":"webpack-dev-server-waitpage","title":"Webpack Dev Server Wait Page","description":"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.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/elisherer/webpack-dev-server-waitpage","tags":["javascript","typescript"],"install":[{"cmd":"npm install webpack-dev-server-waitpage","lang":"bash","label":"npm"},{"cmd":"yarn add webpack-dev-server-waitpage","lang":"bash","label":"yarn"},{"cmd":"pnpm add webpack-dev-server-waitpage","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for core Webpack functionality. Supports ^4 || ^5.","package":"webpack","optional":false},{"reason":"Middleware integrates with webpack-dev-server's internal application hooks.","package":"webpack-dev-server","optional":false}],"imports":[{"note":"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.","wrong":"const webpackDevServerWaitpage = require('webpack-dev-server-waitpage');","symbol":"webpackDevServerWaitpage","correct":"import webpackDevServerWaitpage from 'webpack-dev-server-waitpage';"},{"note":"The `plugin` factory is a property of the default export, not a named export itself.","wrong":"import { plugin } from 'webpack-dev-server-waitpage';","symbol":"plugin","correct":"import webpackDevServerWaitpage from 'webpack-dev-server-waitpage';\nconst plugin = webpackDevServerWaitpage.plugin();"},{"note":"Import types explicitly from the package if using TypeScript.","symbol":"WaitpageOptions","correct":"import type { WaitpageOptions } from 'webpack-dev-server-waitpage';"}],"quickstart":{"code":"import path from 'path';\nimport { Configuration } from 'webpack';\nimport webpackDevServerWaitpage from 'webpack-dev-server-waitpage';\n\nconst config: Configuration = {\n  mode: 'development',\n  entry: './src/index.ts',\n  output: {\n    filename: 'bundle.js',\n    path: path.resolve(__dirname, 'dist'),\n    publicPath: '/',\n  },\n  module: {\n    rules: [\n      {\n        test: /\\.ts$/,\n        use: 'ts-loader',\n        exclude: /node_modules/,\n      },\n      {\n        test: /\\.css$/,\n        use: ['style-loader', 'css-loader'],\n      },\n    ],\n  },\n  resolve: {\n    extensions: ['.ts', '.js', '.json'],\n  },\n  plugins: [\n    // Add the waitpage plugin to the webpack plugins array\n    webpackDevServerWaitpage.plugin(),\n  ],\n  devServer: {\n    port: 8080,\n    open: true,\n    hot: true,\n    // For webpack-dev-server@4+, use onBeforeSetupMiddleware\n    onBeforeSetupMiddleware: (server) => {\n      // Pass the server instance to the waitpage middleware\n      server.app.use(webpackDevServerWaitpage(server, { theme: 'material', title: 'Loading App...' }));\n    },\n    // For webpack-dev-server@3, use before\n    // before: (app, server) => {\n    //   app.use(webpackDevServerWaitpage(server, { theme: 'material', title: 'Loading App...' }));\n    // },\n  },\n};\n\nexport default config;","lang":"typescript","description":"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."},"warnings":[{"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)); } }`.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":"<=0.3.0"},{"fix":"Set `disableWhenValid: false` in the options object passed to the middleware: `server.app.use(webpackDevServerWaitpage(server, { disableWhenValid: false }));`","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Correctly pass the `server` object: `server.app.use(webpackDevServerWaitpage(server, options));` (v4+) or `app.use(webpackDevServerWaitpage(server, options));` (v3).","message":"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.","severity":"gotcha","affected_versions":">=0.2.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Upgrade to `webpack-dev-server-waitpage` version 2.1.1 or higher to resolve this specific bug.","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.","error":"TypeError: Cannot read property 'includes' of undefined"},{"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');`.","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.","error":"webpack-dev-server-waitpage is not a function"},{"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.","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).","error":"webpack-dev-server throws an error about `before` hook not existing or not being a function (or similar for `onBeforeSetupMiddleware`)"}],"ecosystem":"npm"}