Listr2 - Interactive Terminal Task Lists

Common errors

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

  cause 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

  cause 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.

  cause 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.

Warnings

• breaking Listr2 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`.
• breaking Listr2 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`.
• gotcha Listr2 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.
• gotcha When 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`.
• deprecated Internal 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.

Install

• npm install listr2 npm
• yarn add listr2 yarn
• pnpm add listr2 pnpm

Imports

• Listr
  wrong:

  const Listr = require('listr2')

  correct:

  import { Listr } from '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.

Quickstart

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();