Command Line Progress Bar

Common errors

• ReferenceError: colors is not defined

  cause The `ansi-colors` package, which is used for colorizing the progress bar, has not been installed.
  fix Install the `ansi-colors` package: `npm install ansi-colors` or `yarn add ansi-colors`.

• TypeError: cliProgress.SingleBar is not a constructor

  cause Attempting to use ES module named imports for `SingleBar` (e.g., `import { SingleBar } from 'cli-progress';`) when 'cli-progress' is a CommonJS module.
  fix For ESM, use a default import for the main module object: `import cliProgress from 'cli-progress';` and then access `SingleBar` as a property: `new cliProgress.SingleBar(...)`. For CommonJS, use `const cliProgress = require('cli-progress');`.

• ETA displays as 'INF' or 'NULL'

  cause This can happen if the progress bar is initialized with zero total and current values (0/0), if the ETA calculation buffer (`etaBuffer`) is too small for long processes, or if progress updates are too infrequent.
  fix Ensure `start()` is called with a meaningful total, increase the `etaBuffer` option in the constructor for long-running tasks, and ensure regular updates to the progress value.

Warnings

• breaking Synchronous updates on MultiBar instances could cause unexpected behavior prior to v3.3.1. The fix in v3.3.1 effectively limited synchronous updates to SingleBar instances to prevent these issues.
  Fix: Upgrade to v3.3.1 or higher. If you require synchronous multi-bar updates, thoroughly test your implementation on newer versions or consider alternative approaches for synchronization.
• gotcha Colorized progress bars (e.g., using `colors.cyan('{bar}')`) will throw a `ReferenceError` if the `ansi-colors` package is not manually installed, as it is an optional peer dependency for styling.
  Fix: Ensure `ansi-colors` is installed in your project: `npm install ansi-colors` or `yarn add ansi-colors`.
• gotcha The maximum displayed ETA value has been adjusted in different versions (e.g., limited to 100000s in v2.1.0, then to 1e7 seconds in v3.9.0). If the calculated ETA exceeds this limit, it will display as 'INF'.
  Fix: Review any code that relies on specific large ETA display values. If precise display beyond the current limit is critical, consider implementing a custom ETA formatter.
• gotcha For very long-running processes or processes with infrequent updates, the ETA calculation may incorrectly display 'INF' if the `etaBuffer` option is not sufficiently large to capture enough historical data points.
  Fix: Increase the `etaBuffer` option in the `SingleBar` or `MultiBar` constructor options to a value appropriate for your process's duration and update frequency.

Install

• npm install cli-progress npm
• yarn add cli-progress yarn
• pnpm add cli-progress pnpm

Imports

• cliProgress
  wrong:

  import { cliProgress } from 'cli-progress';

  correct:

  import cliProgress from 'cli-progress';

  As 'cli-progress' is a CommonJS module, ESM users should use the default import pattern (e.g., `import cliProgress from 'cli-progress';`) which leverages Node.js's CJS interop. Named imports for the main module object are not supported directly.
• SingleBar
  wrong:

  import { SingleBar } from 'cli-progress';

  correct:

  const cliProgress = require('cli-progress');
  const bar = new cliProgress.SingleBar({}, cliProgress.Presets.shades_classic);

  `SingleBar` is a class property of the main `cliProgress` object. In ESM, it's accessed via `cliProgress.SingleBar` after a default import. Direct named imports are incorrect for this CommonJS package.
• MultiBar
  wrong:

  import { MultiBar } from 'cli-progress';

  correct:

  const cliProgress = require('cli-progress');
  const multiBar = new cliProgress.MultiBar({}, cliProgress.Presets.shades_classic);

  `MultiBar` is a class property of the main `cliProgress` object. In ESM, it's accessed via `cliProgress.MultiBar` after a default import. Direct named imports are incorrect for this CommonJS package.
• Presets
  wrong:

  const { Presets } = require('cli-progress');

  correct:

  import cliProgress from 'cli-progress';
  const theme = cliProgress.Presets.shades_classic;

  `Presets` is an object property of the main `cliProgress` export. Access it via `cliProgress.Presets` in both CommonJS and ESM environments.

Quickstart

Demonstrates a single progress bar with custom formatting, colors (using 'ansi-colors'), and a dynamic payload token update.

const cliProgress = require('cli-progress');
const colors = require('ansi-colors'); // Install 'ansi-colors' manually: npm install ansi-colors

// Create new progress bar instance
const b1 = new cliProgress.SingleBar({
    format: 'CLI Progress |' + colors.cyan('{bar}') + '| {percentage}% || {value}/{total} Chunks || Speed: {speed}',
    barCompleteChar: '\u2588',
    barIncompleteChar: '\u2591',
    hideCursor: true
});

// Initialize the bar with total 200, start value 0, and a custom payload token 'speed'
b1.start(200, 0, {
    speed: "N/A"
});

let value = 0;
const timer = setInterval(() => {
    value += 5;
    b1.update(value, { speed: `${(Math.random() * 10).toFixed(2)} MB/s` });

    if (value >= b1.getTotal()) {
        clearInterval(timer);
        b1.stop();
        console.log('Progress complete!');
    }
}, 100);