Tiny Spinner

2.0.5 · active · verified Wed Apr 22

Tiny Spinner is a minimalist CLI spinner library designed to provide visual feedback for asynchronous operations in terminal applications. It aims for simplicity and a small footprint, differentiating itself from more feature-rich alternatives like `ora` by offering a streamlined API. The package is currently at version 2.0.5 and ships with TypeScript types, facilitating its use in modern JavaScript and TypeScript projects. While its release cadence appears measured, with the last update around early 2025, it remains an active project. Its core functionality focuses on starting, updating, and gracefully stopping a spinner with various status messages (success, warning, error).

Common errors

```
TypeError: tiny_spinner_1.default is not a constructor
```
cause Attempting to use `require('tiny-spinner')` and instantiate it directly without accessing the default export in a CommonJS module after the package became ESM.

fix Correctly access the default export in CommonJS: `const Spinner = require('tiny-spinner').default;` or `const { default: Spinner } = require('tiny-spinner');`.
```
SyntaxError: Cannot use import statement outside a module
```
cause Using `import Spinner from 'tiny-spinner';` in a JavaScript file that is treated as a CommonJS module (e.g., a `.js` file without `"type": "module"` in `package.json` in Node.js).

fix Either convert your project or file to an ES Module by adding `"type": "module"` to your `package.json` or by using the `.mjs` file extension. Alternatively, for CommonJS, use the `require` syntax: `const Spinner = require('tiny-spinner').default;`.

Warnings

breaking The package transitioned to an ES Module (ESM) approximately four years ago, likely with its v2 release. This means direct `require('tiny-spinner')` in a CommonJS context will not correctly yield the `Spinner` class instance without explicitly accessing the `.default` property.
Fix: For CommonJS, use `const Spinner = require('tiny-spinner').default;`. For new projects, prefer ESM with `import Spinner from 'tiny-spinner';` and set `"type": "module"` in your `package.json`.
gotcha Direct `console.log` or `process.stdout.write` calls while the spinner is active can interfere with the spinner's animation, leading to visual glitches or broken output. Unlike some more advanced spinner libraries, `tiny-spinner` does not automatically handle interleaved output.
Fix: Ensure all logging is performed either before the spinner starts or after it stops. If logging is required mid-spin, you might need to manually stop the spinner, log, and then restart it, or consider a more robust spinner library (e.g., `ora`) that handles this gracefully.
gotcha Failing to call any of the termination methods (`spinner.stop()`, `spinner.success()`, `spinner.error()`, `spinner.warning()`) will leave the spinner running indefinitely in the terminal, blocking further output or misleading the user about task completion.
Fix: Always ensure that one of the spinner's termination methods is called in all possible code paths (e.g., in `finally` blocks, success callbacks, or error handlers) to properly clean up the terminal line.

Install

npm install tiny-spinner npm
yarn add tiny-spinner yarn
pnpm add tiny-spinner pnpm

Imports

Spinner
wrong:
```
const Spinner = require('tiny-spinner');
```
correct:
```
import Spinner from 'tiny-spinner';
```
Since v2 (circa 2022), 'tiny-spinner' is an ES Module. For CommonJS, you must access the '.default' property or use dynamic import.
Spinner (CommonJS)
wrong:
```
const Spinner = require('tiny-spinner'); // Fails to construct
```
correct:
```
const Spinner = require('tiny-spinner').default;
```
For CommonJS environments, explicitly access the default export. Alternatively, `const { default: Spinner } = require('tiny-spinner');` also works.
Spinner (Type)
wrong:
```
import { Spinner } from 'tiny-spinner'; // Not typically exported as named type
```
correct:
```
import type { Spinner as SpinnerType } from 'tiny-spinner';
```
The primary export is a default class. For type-only imports, use 'import type' and alias if 'Spinner' is already used.

Quickstart

Demonstrates starting, updating, and gracefully stopping the spinner with success, warning, or error messages based on simulated asynchronous operations.

import Spinner from 'tiny-spinner';

const spinner = new Spinner ();

async function performTask() {
  spinner.start('Doing something important...');

  try {
    await new Promise(resolve => setTimeout(resolve, 2000)); // Simulate async work
    spinner.update('Still processing data...');

    await new Promise(resolve => setTimeout(resolve, 1500)); // More work

    if (Math.random() > 0.8) {
      spinner.error('Task failed unexpectedly!');
      process.exit(1);
    } else if (Math.random() > 0.5) {
      spinner.warning('Task completed with minor issues.');
    } else {
      spinner.success('Task completed successfully!');
    }
  } catch (error) {
    spinner.error(`An unhandled error occurred: ${error.message}`);
    process.exit(1);
  }
}

performTask();

view raw JSON →