webpackbar

repository·main·Indexed 24 days ago

An elegant progress bar and profiler for Webpack and Rspack (version 7.0.0). It provides visual feedback during builds, supports multiple concurrent builds for SSR, and includes an advanced build profiler. It features built-in fancy and basic reporters, supports custom reporter implementations via lifecycle hooks, and allows manual progress updates.

Tokens: 2.2K
Snippets: 4
Records: 13
Agent score: 84%

What's inside webpackbar

Create a custom reporter

main

You can provide your own reporter to control how build progress is displayed. A reporter can be a class instance or a plain object containing hook functions. You do not need to implement all functions; webpackbar only calls the ones that exist.

Important: When using a custom reporter, set fancy: false and basic: false in your configuration to avoid conflicts with default reporters.

Reporter Hooks

Each hook receives a context object. You can access the current status via context.state.

const logger = {
  start(context) {
    // Called when (re)compile is started
  },
  change(context) {
    // Called when a file changed on watch mode
  },
  update(context) {
    // Called after each progress update
  },
  done(context) {
    // Called when compile finished
  },
  progress(context) {
    // Called when build progress updated
  },
  allDone(context) {
    // Called when _all_ compiles finished
  },
  beforeAllDone(context) {},
  afterAllDone(context) {},
};

Context State Schema

The context.state object contains the following fields:

{
  start, 
  progress, 
  message, 
  details, 
  request, 
  hasErrors
}

const logger = {
  start(context) {
    // Called when (re)compile is started
  },
  change(context) {
    // Called when a file changed on watch mode
  },
  update(context) {
    // Called after each progress update
  },
  done(context) {
    // Called when compile finished
  },
  progress(context) {
    // Called when build progress updated
  },
  allDone(context) {
    // Called when _all_ compiles finished
  },
  beforeAllDone(context) {},
  afterAllDone(context) {},
};

// context.state schema:
// {
//   start, progress, message, details, request, hasErrors;
// }

Add webpackbar to Rspack configuration

main

To use webpackbar in an Rspack project, import WebpackBar from webpackbar/rspack and add it to your plugins array. Ensure @rspack/core is installed as a peer dependency.

import WebpackBar from "webpackbar/rspack";

export default {
  entry: "./src/entry.js",
  plugins: [
    new WebpackBar({
      /* options */
    }),
  ],
};

import WebpackBar from "webpackbar/rspack";

export default {
  entry: "./src/entry.js",
  plugins: [
    new WebpackBar({
      /* options */
    }),
  ],
};

Add webpackbar to Webpack configuration

main

To use webpackbar in a Webpack project, import WebpackBar from webpackbar and add it to your plugins array. Ensure webpack is installed as a peer dependency.

import WebpackBar from "webpackbar";

export default {
  entry: "./src/entry.js",
  plugins: [
    new WebpackBar({
      /* options */
    }),
  ],
};

import WebpackBar from "webpackbar";

export default {
  entry: "./src/entry.js",
  plugins: [
    new WebpackBar({
      /* options */
    }),
  ],
};

Install webpackbar

main

Install webpackbar using your preferred package manager:

# npm
npm install webpackbar

# yarn
yarn add webpackbar

# pnpm
pnpm install webpackbar

# bun
bun install webpackbar

# deno
deno install webpackbar

npm install webpackbar

Configure webpackbar options

main

You can customize the behavior of webpackbar using the following options:

Option	Default	Description
`name`	`webpack`	The name displayed in the output.
`color`	`green`	Primary color (supports HEX like `#xxyyzz` or web colors like `green`).
`profile`	`false`	Enable the advanced build profiler.
`fancy`	`true`*	Enable the bars reporter. Automatically set to `false` in CI or testing modes.
`basic`	`true`*	Enable a simple log reporter (only start and end). Automatically set to `true` in minimal environments.
`reporter`	-	Register a single custom reporter.
`reporters`	`[]`	Register an array of custom reporters.

Note: If you provide a custom reporter via reporter or reporters, you should set fancy: false and basic: false to prevent conflicts with the built-in reporters.

Use WebpackBar with Rspack
main
To use webpackbar with Rspack, import the Rspack-specific entry point from webpackbar/rspack. You can then instantiate it as a plugin within your Rspack configuration's plugins array.
Available configuration options for the WebpackBar constructor include:
- name: A string representing the name of the build/process to display in the progress bar.
- color: A string defining the color of the progress bar.
- reporters: An array of reporter names (e.g., ['fancy']) to use for output.
- profile: A boolean that enables profiling mode (can be driven by CLI flags like --profile).
https://github.com/unjs/webpackbar/blob/main/playground/rspack.config.mjs
Initialize the WebpackBar plugin
main
To use WebpackBar in your Webpack configuration, instantiate the WebpackBar class and pass an optional WebpackBarOptions object. The plugin automatically detects if the environment is minimal (e.g., CI) to decide between fancy or basic reporters by default.
Key configuration options include:
- name: The name of the build process (defaults to "build").
- color: The color used for output (defaults to "green").
- reporters: An array of reporters to use. You can provide strings (e.g., "fancy", "basic", "profile") or tuples containing a reporter and its options [reporter, options].
- reporter: A single reporter to use.
- profile: A boolean that, if true, automatically adds the profile reporter if it isn't already present.
https://github.com/unjs/webpackbar/blob/main/src/plugin.ts
Access the current build state
main
The WebpackBar instance provides access to the current build state through the state getter. This state object tracks the lifecycle of the build process.
Properties of the State object:
- start: The high-resolution start time.
- progress: Current progress percentage (-1 if not started, 100 if done).
- done: Boolean indicating if the compilation is finished.
- message: The current status message.
- details: An array of detailed progress steps.
- request: The current active module request.
- hasErrors: Boolean indicating if the compilation encountered errors.
https://github.com/unjs/webpackbar/blob/main/src/plugin.ts
Update build progress manually
main
You can manually update the progress bar state during your build process using the updateProgress method. This is useful for custom build steps or long-running tasks within Webpack.
updateProgress(percent, message, details)
- percent: A float between 0 and 1 representing the progress.
- message: A string message to display.
- details: An array of strings representing detailed steps or modules currently being processed. The last item in this array is used to track the active module request.
https://github.com/unjs/webpackbar/blob/main/src/plugin.ts
Implement a custom Reporter
main
You can extend webpackbar by providing a custom Reporter object. A reporter is an object containing optional lifecycle hooks that receive the WebpackBar instance and specific context data.
Available hooks:
- start: Called when (re)compile starts.
- change: Called when a file changes in watch mode. Receives { shortPath: string }.
- update: Called after each progress update.
- done: Called when the compile finishes. Receives { stats: Stats }.
- progress: Called when build progress is updated.
- allDone: Called when all compiles are finished.
- beforeAllDone: Called before allDone.
- afterAllDone: Called after allDone.
https://github.com/unjs/webpackbar/blob/main/src/types.ts
Use WebpackBarProgressPlugin with Rspack
main
To use webpackbar with Rspack, use the WebpackBarProgressPlugin class. This plugin extends Rspack's native ProgressPlugin and integrates the WebpackBar progress bar into the Rspack build lifecycle. You can pass an optional WebpackBarOptions object to the constructor to configure the progress bar appearance and behavior.
https://github.com/unjs/webpackbar/blob/main/src/rspack.ts
Use WebpackBarProgressPlugin in Webpack configuration
main
To use webpackbar as a progress bar in your Webpack build, use the WebpackBarProgressPlugin class. This class extends the standard Webpack ProgressPlugin and integrates the WebpackBar logic to provide a visual progress bar in your terminal.
You can pass an optional WebpackBarOptions object to the constructor to customize the appearance and behavior of the progress bar.
https://github.com/unjs/webpackbar/blob/main/src/webpack.ts