listr2

library10.2.1jsnpmunverified

Listr2 is a robust and highly interactive task list manager for Node.js command-line applications, designed to provide live updates and a dynamic user experience. As of version 10.2.1, it emphasizes modern JavaScript practices and is primarily used with TypeScript, shipping with comprehensive type definitions. It evolved from the original Listr package, offering a rewritten architecture for improved flexibility, extensibility, and performance, including advanced error handling, concurrent task execution, and support for multiple renderers (e.g., default, verbose, silent). Its release cadence is active, with frequent updates addressing bug fixes, dependency updates, and new features, often released in minor and patch versions. Key differentiators include its ability to manage complex multi-level tasks with live output, integration with popular prompt libraries like Inquirer.js and Enquirer through dedicated adapters, and a flexible API for customizability, making it suitable for complex CLI workflows.

devops

npm install listr2

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · LISTR2

listr2

devopsjavascriptv10.2.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Listr

✓ import { Listr } from 'listr2'

✗ const Listr = require('listr2')

Listr2 is primarily designed for ESM. While it may offer CJS compatibility through transpilation or bundlers, direct `require()` is not the recommended or fully supported way to import the main `Listr` class in modern Node.js environments, especially with its high Node.js engine requirement. Using `import` is preferred for type inference and future compatibility.

ListrDefaultRenderer

✓ import { ListrDefaultRenderer } from 'listr2'

Renderers are imported as named exports. Listr2 also provides `ListrSimpleRenderer` and `ListrVerboseRenderer`.

ListrTask

✓ import type { ListrTask } from 'listr2'

For type-checking tasks, explicitly import `ListrTask` for better code completion and safety, especially when defining complex task arrays or subtasks.

Demonstrates creating a new Listr instance with main tasks and subtasks, handling context, displaying output, and managing errors with both sequential and concurrent execution.

import { Listr, ListrDefaultRenderer } from 'listr2'; interface MyContext { input: string; output: string; } async function runTasks() { const tasks = new Listr<MyContext>( [ { title: 'Main task 1: Processing input', task: async (ctx, task) => { ctx.input = 'initial data'; task.output = `Input set to: ${ctx.input}`; await new Promise((resolve) => setTimeout(resolve, 1000)); } }, { title: 'Main task 2: With subtasks', task: (ctx, task) => task.newListr( [ { title: 'Subtask 2.1: Fetching data', task: async (_, subtask) => { subtask.output = 'Fetching from external API...'; await new Promise((resolve) => setTimeout(resolve, 1500)); // Simulate an error for demonstration if (Math.random() > 0.7) { throw new Error('Failed to fetch data!'); } } }, { title: 'Subtask 2.2: Transforming data', task: async (_, subtask) => { subtask.output = 'Applying transformations.'; await new Promise((resolve) => setTimeout(resolve, 800)); } } ], { concurrent: true, exitOnError: false } ) }, { title: 'Main task 3: Generating output', task: async (ctx, task) => { ctx.output = `Processed: ${ctx.input.toUpperCase()}`; task.output = `Final output: ${ctx.output}`; await new Promise((resolve) => setTimeout(resolve, 500)); }, options: { persistentOutput: true } } ], { concurrent: false, exitOnError: true, renderer: ListrDefaultRenderer, rendererOptions: { collapse: false, clearOutput: true } } ); try { const context = await tasks.run(); console.log('\nAll tasks completed successfully!'); console.log('Final Context:', context); } catch (e: any) { console.error('\nOne or more tasks failed:', e.message); } } runTasks();

Debug

Known issues

breakingListr2 requires Node.js version 22.13.0 or higher. Older Node.js versions are not supported and will result in errors.

fix

Upgrade your Node.js environment to version 22.13.0 or newer. Consider using a Node.js version manager like `nvm` or `volta`.

affects: >=10.0.0

breakingListr2 is a complete rewrite of the original `listr` package. It introduces a new API, different configuration options, and a more opinionated structure. Direct migration from `listr` without code changes is not possible.

fix

Refer to the official Listr2 documentation for a comprehensive guide on the new API and migration path from `listr`.

affects: >=1.0.0

gotchaListr2 is primarily designed for ES Modules (ESM). While tools may transpile it for CommonJS (CJS) compatibility, direct `require()` calls may lead to unexpected behavior or `TypeError: Listr is not a constructor`.

fix

Ensure your project is configured for ESM by setting `"type": "module"` in your `package.json` and using `import` statements. If you must use CJS, you might need to use dynamic `import()` or adjust your build pipeline.

affects: >=1.0.0

gotchaWhen using prompt adapters (e.g., `@listr2/prompt-adapter-inquirer`), ensure the specific adapter package is installed alongside `listr2`. Failure to do so will result in runtime errors when a prompt task is encountered.

fix

Install the required prompt adapter, e.g., `npm install @listr2/prompt-adapter-inquirer`.

affects: >=1.0.0

deprecatedInternal color styling utility `colorette` has been replaced with Node.js's native `util.styleText` for internal styling. While this is primarily an internal change, users who were relying on or overriding `colorette`'s behavior within Listr2 might notice differences.

fix

No direct action required for most users. If you had custom renderer logic tied to `colorette`, you may need to update it to use `util.styleText` or another coloring library if you desire custom styling.

affects: >=10.2.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM: require() of ES Module ... listr2.js from ... is not supported.

Attempting to import Listr2 using CommonJS `require()` syntax in an environment where it's treated as an ES Module.

fix

Switch to ES Module import syntax: `import { Listr } from 'listr2';`. Ensure your `package.json` has `"type": "module"` if your entire project is ESM, or use a bundler if mixing CJS and ESM.

TypeError: Listr is not a constructor

This usually happens when trying to `new Listr()` after a CJS `require()` that incorrectly resolves the ESM export, or if an incorrect symbol is imported.

fix

Verify that you are using `import { Listr } from 'listr2';` and that your environment supports ES Modules for this package. Avoid `const Listr = require('listr2').Listr;` as it might not work reliably.

ListrError: A task has failed and `exitOnError` is enabled, exiting.

One of the tasks or subtasks threw an unhandled error, and the `exitOnError` option (defaulting to `true`) caused Listr2 to stop execution.

fix

Wrap your task logic in `try...catch` blocks to gracefully handle errors, or set `exitOnError: false` in the Listr options to allow other tasks to continue running even after a failure.

Upgrade

Version history

10.2.1latest on npm

Audit

Dependencies

@listr2/prompt-adapter-inquireroptionalProvides integration with Inquirer.js for interactive prompts within tasks.

@listr2/prompt-adapter-enquireroptionalProvides integration with Enquirer for interactive prompts within tasks.

Agent activity

13 hits · last 30 days

node

Resources

githubhttps://github.com/listr2/listr2 ↗

packagehttps://www.npmjs.com/package/listr2 ↗

homepagehttps://listr2.kilic.dev ↗