ora

Ora is a widely used terminal spinner library for Node.js that shows an animated loading indicator while long-running work is in progress. With a single call you get a configurable spinner with text, colors, and prefix/suffix labels that you can update live, then finalize into a green success, red failure, or yellow warning symbol.

Designed for modern Node.js (ESM, private class fields, Node 20+), Ora automatically detects whether it is running in an interactive TTY, hides the cursor, discards stray stdin, and coexists cleanly with your own console.log output. It powers loading feedback in countless CLIs, build tools, and automation scripts.

What You Get

• A configurable spinner (text, color, prefix/suffix text, indent, custom frames) that can be updated live via getters and setters
• Terminal-aware behavior: automatic TTY/CI detection, cursor hiding, stdin discarding, and a line-spinner fallback on non-Unicode Windows terminals
• Completion helpers - .succeed(), .fail(), .warn(), .info(), and .stopAndPersist() - that stop the spinner and print a persisted symbol and message
• An oraPromise() helper that wires a spinner to a promise, resolving with .succeed() and rejecting with .fail() automatically
• Access to the full cli-spinners catalog and clean coexistence with regular console.log output

Common Use Cases

• Showing loading feedback while a CLI fetches data, installs packages, or calls a slow API
• Reporting step-by-step progress in build scripts and automation with success/failure symbols
• Wrapping a promise-returning task so status is reflected automatically without manual start/stop calls

Under The Hood

Architecture - Ora is a single ES module (index.js) built around one Ora class that encapsulates all state in private fields (#frameIndex, #stream, #hookedStreams, #color) and exposes a small public surface plus a default ora() factory and an oraPromise() helper. On start it resolves the target stream (default process.stderr), decides whether it is enabled by probing TTY/CI state, hides the cursor via cli-cursor, optionally discards stdin, and installs write hooks on the stream so its own frames and the caller’s console output interleave cleanly. A timer advances #frameIndex through the chosen spinner’s frames, and each render clears the previous lines (tracked in #linesToClear) before writing the next frame, using synchronized-output escape sequences where supported.

Tech Stack - Pure modern JavaScript targeting Node.js >=20 as an ESM-only package (“type”: “module”, exports map with bundled TypeScript types in index.d.ts). It composes a set of focused sindresorhus utilities as dependencies: chalk for color, cli-cursor for cursor control, cli-spinners for the frame catalog, log-symbols for completion glyphs, is-interactive and is-unicode-supported for environment detection, stdin-discarder for input handling, and string-width for correct width math. Tooling is xo (lint), tsd (type tests), and the built-in node —test runner.

Code Quality - The code is clean and disciplined: private class fields enforce encapsulation, helper methods like #internalWrite and #tryRender keep render logic DRY, and edge cases (buffer vs string chunks, line-terminating writes, non-Unicode Windows terminals, worker threads) are handled explicitly. Test coverage is strong - test.js contains roughly 100 tests exercised via the native test runner, plus type-level tests in index.test-d.ts.

API Design - The developer experience is excellent and a big reason for Ora’s popularity. A single ora('text').start() gets you going, mutable properties (spinner.text, spinner.color) make live updates obvious, and the completion methods (.succeed/.fail/.warn/.info) read naturally and return the instance for chaining. oraPromise() removes boilerplate for the common promise case, and the bundled, thoroughly documented TypeScript types make the whole surface discoverable in the editor.