DOCSEARCHbyAlgolia
Submit Docs

webpack-dashboard

repository·master·Indexed 11 days ago

https://github.com/formidablelabs/webpack-dashboard

A CLI dashboard for webpack dev servers that provides a high-fidelity, visual interface to monitor webpack processes, replacing standard terminal output. Version 3.3.8 requires Node 8 or above. It includes a DashboardPlugin for webpack configuration and a CLI tool to wrap dev server start scripts.

Tokens
3.7K
Snippets
15
Records
18
Agent score
96%

What's inside webpack-dashboard

  1. Install webpack-dashboard

    master

    You can install webpack-dashboard as a development dependency in your project or install it globally to use it across any project.

    As a dev dependency:

    npm install --save-dev webpack-dashboard
# or
yarn add --dev webpack-dashboard

    Globally:

    npm install -g webpack-dashboard
    npm install --save-dev webpack-dashboard

  2. Configure the DashboardPlugin in webpack

    master

    To use the dashboard, import DashboardPlugin from webpack-dashboard/plugin and add it to your webpack configuration's plugins array.

    Note for OS X Terminal.app users: Ensure that View → Allow Mouse Reporting is enabled to allow scrolling through logs and modules. If this is not available, consider using iTerm2.

    // Import the plugin:
const DashboardPlugin = require("webpack-dashboard/plugin");

// Add it to your webpack configuration plugins.
module.exports = {
  // ...
  plugins: [new DashboardPlugin({
    /* options */
  })];
  // ...
};

  3. Use webpack-dashboard in your project

    master

    To use the dashboard, you must perform two steps: add the plugin to your webpack configuration and wrap your dev server start script with the webpack-dashboard CLI.

    Note: webpack-dashboard@^3.0.0 requires Node 8 or above.

    1. Add the plugin to webpack config

    Import DashboardPlugin from webpack-dashboard/plugin and add it to your plugins array.

    2. Update your start script

    Prefix your existing dev command with webpack-dashboard --. The -- separator is used to pass the remaining arguments to your command.

    Example transformation: If your script was: "dev": "webpack-dev-server"

    Change it to: "dev": "webpack-dashboard -- webpack-dev-server"

    const DashboardPlugin = require("webpack-dashboard/plugin");

module.exports = {
  // ...
  plugins: [new DashboardPlugin()],
  // ...
};

// In package.json:
"scripts": {
    "dev": "webpack-dashboard -- webpack-dev-server"
}

  4. Run webpack-dashboard via CLI

    master

    To launch the dashboard, wrap your existing webpack start command with webpack-dashboard --. The -- separator ensures that subsequent arguments are passed to your original command.

    Common usage patterns

    Standard Node/Webpack script: Change your package.json script from: "dev": "node index.js" to: "dev": "webpack-dashboard -- node index.js"

    Webpack-dev-server script: "dev": "webpack-dashboard -- webpack-dev-server --config ./webpack.dev.js"

    CLI Flags

    • -p <port>: Specify the custom port used by the dashboard sockets. This must match the port configured in the DashboardPlugin constructor.
    • -c <color>: Custom colorize your dashboard using a supported ANSI color.

    Example with custom port and color:

    "dev": "webpack-dashboard -p 3001 -c magenta -- node index.js"
    "scripts": {
  "dev": "webpack-dashboard -p 3001 -c magenta -- node index.js"
}

  5. Customize the webpack-dashboard port

    master

    If you need to use a custom port for communication between the webpack plugin and the CLI tool, you must specify the same port in both places.

    Warning: Choose a port that is not currently in use by webpack-dev-server, devServer, or any other process. It should be dedicated solely to webpack-dashboard.

    1. Set the port in the DashboardPlugin options in your webpack config.
    2. Pass the same port to the CLI using the --port flag.
    // webpack.config.js
plugins: [new DashboardPlugin({ port: 3001 })]

// package.json script
"dev": "webpack-dashboard --port 3001 -- webpack"

  6. Configure a custom port for the DashboardPlugin

    master

    The dashboard uses sockets, which require a port. If the default port causes issues, you can specify a custom port in the DashboardPlugin constructor.

    Important: If you define a custom port in the webpack configuration, you must also pass that same port number to the webpack-dashboard CLI using the -p flag.

    plugins: [
  new DashboardPlugin({ port: 3001 })
]

  7. How the Dashboard lifecycle and data binding works

    master

    The Dashboard operates on a reactive-style data binding model. When you call setData(), the class iterates through the provided array and maps each type to a specific internal setter method (e.g., setProgress, setStats, setSizes).

    Lifecycle Flow:

    1. Initialization: The constructor sets up the blessed screen, defines the layout (Log, Status, Operation, Progress, and optionally Modules/Assets/Problems), and binds message types to internal methods.
    2. Data Ingestion: setData() receives an array of updates.
    3. Error Handling: If a data object has error: true, the value is deserialized into a proper Error object before being passed to the specific setter.
    4. UI Update: The corresponding setter updates the specific blessed component (like a listbar, table, or log), and this.screen.render() is called to refresh the terminal display.
    5. Navigation: The dashboard automatically handles keyboard navigation (e.g., up/down for logs, left/right for menus, q or Esc to exit).

  8. Integrate webpack-dashboard using DashboardPlugin

    master

    To use the webpack-dashboard, instantiate the DashboardPlugin class and add it to your webpack configuration's plugins array. The plugin automatically connects to a dashboard server via Socket.io and streams build progress, status, stats, and metrics (like bundle sizes and duplicate detection) to the UI.

    By default, it connects to http://127.0.0.1:9838. You can customize the connection settings or provide a custom handler function.

    Basic Usage

    const DashboardPlugin = require('webpack-dashboard/plugin');

module.exports = {
  // ... other webpack config
  plugins: [
    new DashboardPlugin()
  ]
};
    const DashboardPlugin = require('webpack-dashboard/plugin');

module.exports = {
  plugins: [
    new DashboardPlugin()
  ]
};

  9. DashboardPlugin options

    master

    The DashboardPlugin used in your webpack configuration accepts the following options:

    OptionTypeDescription
    hoststringCustom host for connection the socket client
    portnumberCustom port for connecting the socket client
    includeAssetsArray<String | RegExp>Limit display to asset names matching string prefix or regex
    handlerfunctionPlugin handler method. You can pass a method like dashboard.setData or simply pass a function directly: new DashboardPlugin(myHandlerFunction)
    new DashboardPlugin({
  host: 'localhost',
  port: 3001,
  includeAssets: ['\.js$', /\.css$/],
  handler: (data) => console.log(data)
});

  10. Configure DashboardPlugin options

    master

    When instantiating DashboardPlugin, you can pass an options object to customize its behavior:

    OptionTypeDefaultDescription
    hoststring'127.0.0.1'The hostname of the dashboard server.
    portnumber9838The port of the dashboard server.
    includeAssetsArray<string|RegExp>[]A list of patterns used to filter which assets are included in the metrics analysis. Can contain strings (prefix match) or Regular Expressions.
    handlerfunctionnullA custom function to handle the emitted dashboard messages. If provided, the plugin will use this instead of the default Socket.io transport.
    new DashboardPlugin({
  host: 'localhost',
  port: 9000,
  includeAssets: ['js/', /^styles/],
  handler: (message) => {
    console.log('Received message:', message);
  }
});

  11. Terminal and OS compatibility

    master

    The dashboard's behavior (especially mouse support) depends on your operating system and terminal emulator.

    macOS

    Works in Terminal, iTerm 2, and Hyper.

    • Terminal: To enable scrolling via mouse, ensure View → Enable Mouse Reporting is enabled (supported in El Capitan, Sierra, and High Sierra).
    • iTerm 2:
      • Hold <kbd>⌥ Opt</kbd> to select full rows.
      • Hold <kbd>⌥ Opt</kbd> + <kbd>⌘ Cmd</kbd> to select a block of text.

    Windows 10

    Works in Command Prompt, PowerShell, and WSL.

    • Mouse events are not supported.
    • Use keys to scroll the main log: <kbd>↑</kbd>, <kbd>↓</kbd>, <kbd>Page Up</kbd>, and <kbd>Page Down</kbd>.

    Linux

    Verified in built-in terminals for Debian-based distros (e.g., Ubuntu, Mint).

    • Mouse events and scrolling are supported automatically.
    • Hold <kbd>⇧ Shift</kbd> to highlight or select lines.

  12. webpack-dashboard CLI options

    master

    The webpack-dashboard CLI accepts the following options to customize the dashboard experience:

    FlagLong FlagDescription
    -c--color [color]Custom ANSI color for your dashboard
    -m--minimalRuns the dashboard in minimal mode
    -t--title [title]Set title of terminal window
    -p--port [port]Custom port for socket communication server
    -a--include-assets [string prefix]Limit display to asset names matching string prefix (can be repeated; values are concatenated to the plugin's includeAssets array)

    Arguments: [command] - The command you want to run (e.g., webpack-dashboard -- node index.js).

    webpack-dashboard --port 3001 -- webpack