{"id":28040,"library":"picospinner","title":"picospinner","description":"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.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/PondWader/picospinner#readme","tags":["javascript","spinner","cli","lightweight","minimal","typescript"],"install":[{"cmd":"npm install picospinner","lang":"bash","label":"npm"},{"cmd":"yarn add picospinner","lang":"bash","label":"yarn"},{"cmd":"pnpm add picospinner","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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')`.","wrong":"const Spinner = require('picospinner')","symbol":"Spinner","correct":"import { Spinner } from 'picospinner'"},{"note":"picospinner exports only named exports. Default import will result in undefined at runtime.","wrong":"import Spinner from 'picospinner'","symbol":"default import (Spinner class)","correct":"import { Spinner } from 'picospinner'"},{"note":"TypeScript types are shipped with the package. Use import type for type-only usage.","wrong":"","symbol":"type SpinnerOptions","correct":"import type { SpinnerOptions } from 'picospinner'"}],"quickstart":{"code":"import { Spinner } from 'picospinner';\n\nconst spinner = new Spinner('Loading...', {\n  frames: ['◰', '◳', '◲', '◱'],\n  symbols: { succeed: '✓', fail: '✗' },\n  colors: { text: 'cyan', spinner: 'yellow' }\n});\n\nspinner.start();\n\n// Simulate async work\nsetTimeout(() => {\n  spinner.succeed('Task completed!');\n}, 3000);","lang":"typescript","description":"Shows instantiation, custom frames, symbols, colors, and the start/succeed pattern."},"warnings":[{"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.","message":"In version 3, picospinner is ESM-only. CommonJS require() fails unless using Node.js >=20.17.0 with require(esm) enabled.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Use `spinner.succeed('Done')` or another finishing method instead of `stop()` to show a completion indicator.","message":"The `stop()` method ends the spinner without showing any symbol; use `succeed()`, `fail()`, `warn()`, or `info()` to display a completion symbol.","severity":"gotcha","affected_versions":"*"},{"fix":"Check `process.versions.node` and handle gracefully, or use a third-party color library like picocolors to ensure consistent coloring.","message":"Color support depends on Node.js version. If Node <20.12.0, colors are silently disabled. No error or warning is emitted.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Update to v3: `npm i picospinner@latest`, convert to ESM (use import instead of require).","message":"Version 2 is in maintenance mode and will not receive new features. Migrate to v3 when possible.","severity":"deprecated","affected_versions":"<3.0.0"}],"env_vars":null,"last_verified":"2026-05-09T00:00:00.000Z","next_check":"2026-08-07T00:00:00.000Z","problems":[{"fix":"Use named import: `import { Spinner } from 'picospinner'`","cause":"Using default import (import Spinner from 'picospinner') instead of named import.","error":"TypeError: Spinner is not a constructor"},{"fix":"Switch to ESM: use import syntax, or install picospinner@2 for CommonJS support.","cause":"Using CommonJS require() with picospinner >=3.0.0 on Node <20.17.0.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module [...] not supported."},{"fix":"Set `\"type\": \"module\"` in package.json or use `.mjs` file extension.","cause":"Using picospinner >=3.0.0 in a CommonJS module without enabling ESM.","error":"SyntaxError: Cannot use import statement outside a module"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}