CLI Spinners

Common errors

• ERR_REQUIRE_ESM

  cause Attempting to `require()` `cli-spinners` in a CommonJS module after upgrading to v3.0.0.
  fix Refactor your code to use ES Modules (`import`) and ensure your project's `package.json` has `"type": "module"` or use `.mjs` file extensions.

• TypeError: cliSpinners is not a function

  cause Trying to invoke `cliSpinners` as a function or accessing properties on an undefined `cliSpinners` variable due to incorrect import.
  fix Ensure you are using the correct ESM import syntax: `import cliSpinners from 'cli-spinners';` and accessing properties like `cliSpinners.dots` (it's an object, not a function).

• Cannot find module 'cli-spinners'

  cause The package is not installed, or there is a typo in the import path/package name.
  fix Run `npm install cli-spinners` or `yarn add cli-spinners`. Double-check the spelling in your import statement.

Warnings

• breaking This package transitioned to pure ECMAScript Modules (ESM) in version 3.0.0. Attempting to use `require()` to import `cli-spinners` will result in an `ERR_REQUIRE_ESM` runtime error.
  Fix: Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json` or using `.mjs` file extension) and use `import cliSpinners from 'cli-spinners';` for imports.
• breaking Version 3.0.0 of `cli-spinners` raised the minimum Node.js requirement to 18.x. Running this package on older Node.js versions will lead to runtime errors or compatibility issues.
  Fix: Upgrade your Node.js environment to version 18.x or newer.
• gotcha `cli-spinners` provides only the raw data (frames and recommended intervals) for spinners. It does not include any logic for animating or displaying these spinners in the terminal. If you need a fully functional terminal spinner, you should use a higher-level library like `ora`.
  Fix: For actual animated spinners, install and use `ora` (e.g., `npm install ora`) which consumes `cli-spinners` internally. For custom animation, use `setInterval` and `process.stdout.write` with the spinner's frames and interval.
• gotcha Spinner frames use various Unicode characters. While most modern terminals and fonts support these, some older or non-standard terminal emulators might display characters incorrectly or as empty boxes, leading to broken animations.
  Fix: Test the chosen spinners in your target terminal environments. Consider offering a fallback or simpler spinner for environments with limited Unicode support, or advising users on suitable terminal fonts.

Install

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

Imports

• cliSpinners
  wrong:

  const cliSpinners = require('cli-spinners');

  correct:

  import cliSpinners from 'cli-spinners';

  The default export is an object containing all spinner definitions. `require` is not supported since v3.0.0 (pure ESM).
• randomSpinner
  wrong:

  import cliSpinners, { randomSpinner } from 'cli-spinners';

  correct:

  import { randomSpinner } from 'cli-spinners';

  randomSpinner is a named export. While the default can be imported alongside, it's unnecessary if only randomSpinner is needed.
• Spinner

  import type { Spinner } from 'cli-spinners';

  Type import for TypeScript users to define the structure of a spinner object (interval, frames).

Quickstart

Demonstrates how to import the default `cliSpinners` object and `randomSpinner`, retrieve spinner data, and provides a basic manual animation loop for illustrative purposes (though `ora` is recommended for actual terminal animation).

import cliSpinners, { randomSpinner, type Spinner } from 'cli-spinners';
import process from 'node:process';

// Get a specific spinner by name
const dotsSpinner: Spinner = cliSpinners.dots;
console.log('Using "dots" spinner (first frame):', dotsSpinner.frames[0]);

// Get a random spinner programmatically
const randSpinner: Spinner = randomSpinner();
console.log(`\nUsing a random spinner (first frame): ${randSpinner.frames[0]}...`);

// Example of manually animating a spinner (ora is recommended for production use)
let frameIndex = 0;
const spinnerName = 'dots';
const spinner = cliSpinners[spinnerName as keyof typeof cliSpinners]; // Access dynamically with type assertion
const interval = spinner.interval;
const frames = spinner.frames;

process.stdout.write(`\nAnimating "${spinnerName}": `);

const timer = setInterval(() => {
    process.stdout.write('\r'); // Clear the current line
    process.stdout.write(`Animating "${spinnerName}": ${frames[frameIndex]}`);
    frameIndex = (frameIndex + 1) % frames.length;
}, interval);

// Stop the animation after a few seconds
setTimeout(() => {
    clearInterval(timer);
    process.stdout.write('\r                                  \r'); // Clear the spinner line completely
    console.log(`\nStopped animating "${spinnerName}".`);
}, 3000);