tiny-spinner

library2.0.5jsnpmunverified

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

devops observability

npm install tiny-spinner

github ↗package ↗

INSTALL

IMPORT

SIG · TINY-SPINNER

tiny-spinner

devopsjavascriptv2.0.5

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.

Spinner

✓ import Spinner from 'tiny-spinner';

✗ const Spinner = require('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)

✓ const Spinner = require('tiny-spinner').default;

✗ const Spinner = require('tiny-spinner'); // Fails to construct

For CommonJS environments, explicitly access the default export. Alternatively, `const { default: Spinner } = require('tiny-spinner');` also works.

Spinner (Type)

✓ import type { Spinner as SpinnerType } from 'tiny-spinner';

✗ import { Spinner } from 'tiny-spinner'; // Not typically exported as named type

The primary export is a default class. For type-only imports, use 'import type' and alias if 'Spinner' is already used.

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

Debug

Known issues

breakingThe 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`.

affects: >=2.0.0

gotchaDirect `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.

affects: >=1.0.0

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

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: tiny_spinner_1.default is not a constructor

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

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;`.

Upgrade

Version history

2.0.5latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

23 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/fabiospampinato/tiny-spinner ↗

packagehttps://www.npmjs.com/package/tiny-spinner ↗