picospinner

library3.0.0jsnpmunverified

A lightweight, zero-dependency CLI spinner library for Node.js. Current stable version is 3.0.0, published as ESM-only (require() supported in Node >=20.17.0). Provides a simple Spinner class with start/stop/succeed/fail/warn/info methods, customizable frames and symbols, and built-in color support via node:util styleText (Node >=20.12.0). Unlike heavier alternatives like ora, picospinner has no dependencies and a minimal API. Version 2 remains maintained for CJS users. GitHub releases are infrequent; features are added conservatively.

devops observability

npm install picospinner

package ↗

INSTALL

IMPORT

SIG · PICOSPINNER

picospinner

devopsjavascriptv3.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

Spinner

✓ import { Spinner } from 'picospinner'

✗ const Spinner = require('picospinner')

Since v3, picospinner is ESM-only. In Node.js >=20.17.0, require(esm) works. For older Node or tools that don't support require(esm), install v2 with `npm i picospinner@2` and use `const { Spinner } = require('picospinner')`.

default import (Spinner class)

✓ import { Spinner } from 'picospinner'

✗ import Spinner from 'picospinner'

picospinner exports only named exports. Default import will result in undefined at runtime.

type SpinnerOptions

✓ import type { SpinnerOptions } from 'picospinner'

TypeScript types are shipped with the package. Use import type for type-only usage.

Shows instantiation, custom frames, symbols, colors, and the start/succeed pattern.

import { Spinner } from 'picospinner'; const spinner = new Spinner('Loading...', { frames: ['◰', '◳', '◲', '◱'], symbols: { succeed: '✓', fail: '✗' }, colors: { text: 'cyan', spinner: 'yellow' } }); spinner.start(); // Simulate async work setTimeout(() => { spinner.succeed('Task completed!'); }, 3000);

Debug

Known issues

breakingIn version 3, picospinner is ESM-only. CommonJS require() fails unless using Node.js >=20.17.0 with require(esm) enabled.

fix

If you must use CommonJS, install v2: `npm i picospinner@2`. For Node <20.17.0, ensure your project is ESM or use a dynamic import.

affects: >=3.0.0

gotchaThe `stop()` method ends the spinner without showing any symbol; use `succeed()`, `fail()`, `warn()`, or `info()` to display a completion symbol.

fix

Use `spinner.succeed('Done')` or another finishing method instead of `stop()` to show a completion indicator.

affects: *

gotchaColor support depends on Node.js version. If Node <20.12.0, colors are silently disabled. No error or warning is emitted.

fix

Check `process.versions.node` and handle gracefully, or use a third-party color library like picocolors to ensure consistent coloring.

affects: >=3.0.0

deprecatedVersion 2 is in maintenance mode and will not receive new features. Migrate to v3 when possible.

fix

Update to v3: `npm i picospinner@latest`, convert to ESM (use import instead of require).

affects: <3.0.0

Errors

Common errors & fixes

TypeError: Spinner is not a constructor

Using default import (import Spinner from 'picospinner') instead of named import.

fix

Use named import: `import { Spinner } from 'picospinner'`

Error [ERR_REQUIRE_ESM]: require() of ES Module [...] not supported.

Using CommonJS require() with picospinner >=3.0.0 on Node <20.17.0.

fix

Switch to ESM: use import syntax, or install picospinner@2 for CommonJS support.

SyntaxError: Cannot use import statement outside a module

Using picospinner >=3.0.0 in a CommonJS module without enabling ESM.

fix

Set `"type": "module"` in package.json or use `.mjs` file extension.

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

14 hits · last 30 days

node

OpenAI (training)

Resources

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