error-overlay-webpack-plugin

1.1.1 verified Sat Apr 25 auth: no javascript

Webpack plugin that displays a full-screen error overlay in the browser during development, similar to create-react-app. Current stable version is 1.1.1, with sporadic releases for bug fixes. It supports Webpack 4 and 5, provides elegant stack traces, and allows clicking to open error lines in the editor. Key differentiator: seamless integration of the same error overlay used in CRA without ejecting, with support for custom sockHost/sockPath settings.

Common errors

error Options has an unknown property 'before' ↓

cause Using 'before' option with plugin version >=1.1.0 which removed or renamed it.

fix

Remove 'before' from plugin options. Use webpack-dev-server's 'onBeforeSetupMiddleware' instead.

error The 'mode' option has not been set, webpack will fallback to 'production' for this value. ↓

cause Common webpack configuration warning; not specific to this plugin but often appears together.

fix

Set 'mode' to 'development' in webpack config.

Warnings

gotcha Plugin requires 'cheap-module-source-map' devtool; using 'eval' will cause the overlay to not display errors properly. ↓

fix Set devtool to 'cheap-module-source-map' in webpack config.

gotcha Options object property 'before' was renamed or removed in v1.1.0; using it causes 'unknown property' error. ↓

fix Do not pass 'before' option; use webpack-dev-server's 'onBeforeSetupMiddleware' instead.

breaking v1.0.0 dropped support for Webpack 4 (though later versions declare peer dep on webpack ^4.0.0 || ^5.0.0). Check compatibility. ↓

fix Upgrade to v1.1.1 for Webpack 4 support or use v0.4.2 if Webpack 4 needed.

gotcha If using webpack-dev-middleware without webpack-dev-server, the socket listener must be manually configured; otherwise overlay won't update. ↓

fix Pass custom sockHost/sockPath/sockPort options to the plugin, or use webpack-dev-server.

Install

npm install error-overlay-webpack-plugin

yarn add error-overlay-webpack-plugin

pnpm add error-overlay-webpack-plugin

Imports

ErrorOverlayPlugin

wrong

import ErrorOverlayPlugin from 'error-overlay-webpack-plugin'

correct

const ErrorOverlayPlugin = require('error-overlay-webpack-plugin')

Package does not export ESM; use CommonJS require in webpack config.

ErrorOverlayPlugin

const ErrorOverlayPlugin = require('error-overlay-webpack-plugin')

Default export is the plugin class.

webpack
```
const webpack = require('webpack')
```
webpack is a peer dependency; must be installed separately.

Quickstart

Basic setup of error-overlay-webpack-plugin with Webpack 5, devtool configuration, and dev server.

// webpack.config.js
const ErrorOverlayPlugin = require('error-overlay-webpack-plugin');

module.exports = {
  entry: './src/index.js',
  output: { path: __dirname + '/dist', filename: 'bundle.js' },
  devtool: 'cheap-module-source-map',
  plugins: [new ErrorOverlayPlugin()],
  devServer: { hot: true }
};

// package.json
// {
//   "scripts": { "dev": "webpack serve" },
//   "devDependencies": {
//     "webpack": "^5.0.0",
//     "webpack-cli": "^4.0.0",
//     "webpack-dev-server": "^3.0.0 || ^4.0.0",
//     "error-overlay-webpack-plugin": "^1.1.1"
//   }
// }