Webpack Build Status Notifier

Common errors

• TypeError: WebpackNotifierPlugin is not a constructor

  cause Attempting to import WebpackNotifierPlugin as a named export when it is a default export.
  fix Use `const WebpackNotifierPlugin = require('webpack-notifier');` for CommonJS or `import WebpackNotifierPlugin from 'webpack-notifier';` for ESM.

• Error: stdout maxBuffer exceeded

  cause This error often originates from `node-notifier` when the message content (especially with large stack traces in errors) is too long for the underlying notification system's stdout buffer.
  fix Consider using the `onlyOnError: true` and `excludeWarnings: true` options to reduce notification frequency, or implement a custom `message` function in the plugin configuration to truncate lengthy error messages before they are passed to the notifier.

• Notifications are not showing up on [OS Name]

  cause The underlying `node-notifier` package might require specific system tools that are not installed on the user's OS, or system notification settings are preventing display.
  fix Refer to the `node-notifier` 'Requirements' section on its GitHub page (`https://github.com/mikaelbr/node-notifier#requirements`) for your specific OS and install any missing dependencies. Also, check your OS notification settings for the terminal or IDE running webpack.

Warnings

• gotcha webpack-notifier relies on the `node-notifier` package, which itself has platform-specific requirements. Users might need to install additional system tools (e.g., `growl` on macOS prior to Big Sur, or `snoretoast` on Windows for some versions) for notifications to function correctly.
  Fix: Check the `node-notifier` documentation for your operating system's specific requirements and install any necessary dependencies manually: `https://github.com/mikaelbr/node-notifier#requirements`
• gotcha When migrating from `webpack-error-notification`, be aware that `webpack-notifier` provides improved Windows support and removes the need for `terminal-notifier` on OS X, simplifying setup but changing the underlying notification mechanism.
  Fix: Ensure `terminal-notifier` is uninstalled if it was previously manually installed for older notification plugins, as `webpack-notifier` handles this automatically via `node-notifier`.
• gotcha Prior to v1.3.0, error and warning messages in notifications did not have specific prefixes. Since v1.3.0, messages are prefixed for clearer identification.
  Fix: Update to `webpack-notifier@1.3.0` or higher to benefit from clearer, prefixed error and warning messages in your system notifications.
• gotcha If notifications are not appearing, ensure that your operating system's notification settings are configured to allow notifications from the application running webpack (e.g., your terminal or IDE).
  Fix: Check system preferences/settings for notifications. On macOS, look under 'Notifications & Focus'. On Windows, 'System > Notifications & actions'. Ensure notifications are enabled for the process running webpack.

Install

• npm install webpack-notifier npm
• yarn add webpack-notifier yarn
• pnpm add webpack-notifier pnpm

Imports

• WebpackNotifierPlugin
  wrong:

  import { WebpackNotifierPlugin } from 'webpack-notifier';

  correct:

  import WebpackNotifierPlugin from 'webpack-notifier';
  // or for CommonJS
  const WebpackNotifierPlugin = require('webpack-notifier');

  The plugin is exported as a default export in CommonJS and ESM contexts.
• Configuration options
  wrong:

  new WebpackNotifierPlugin({ 'title': 'My Build' });

  correct:

  new WebpackNotifierPlugin({ title: 'My Build', excludeWarnings: true });

  Configuration options are passed as a plain object to the constructor.
• WebpackNotifierPlugin

  import type WebpackNotifierPlugin from 'webpack-notifier';

  When using TypeScript, import the type if you only need type declarations without runtime import.

Quickstart

This quickstart demonstrates how to integrate webpack-notifier into a basic webpack configuration, showing how to instantiate the plugin and configure common options like `title`, `alwaysNotify`, `contentImage`, `excludeWarnings`, and `skipFirstNotification`.

const path = require('path');
const WebpackNotifierPlugin = require('webpack-notifier');

module.exports = {
  mode: 'development',
  entry: './src/index.js',
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, 'dist'),
  },
  plugins: [
    new WebpackNotifierPlugin({
      title: 'My Webpack Build',
      alwaysNotify: true, // Be 'noisy' and notify on every build
      contentImage: path.join(__dirname, 'logo.png'), // Ensure 'logo.png' exists for this to work
      excludeWarnings: false, // Show warnings in notifications
      skipFirstNotification: false // Notify on the initial build
    }),
  ],
  // Create a dummy logo.png for the example to be runnable
  // For a real project, replace with an actual image path.
  // This ensures the example is complete without external files.
  // fs.writeFileSync(path.join(__dirname, 'logo.png'), 'dummy data'); // Not ideal for quickstart code but illustrates the point
};