A Lightweight Terminal Spinner for Node.js

Name simplejack comes from its simplicity in approach and the saying “jack of all trades”. I created it when facing with challenges building a binary for a cli tool I was making for work and the sheer joyful pain it was causing me trying to incorporate a simple spinner library into the final binary for macos.

When building CLI applications providing visual feedback during long-running operations is crucial for a good user experience. I was working on a side project which came out of the need to transform internal incident postmortems to a customer friendly version of the incident told/generated by AI.

Example usage:

const spinner = new SimpleSpinner("Processing...");
spinner.start();
// ... do some work ...
spinner.succeed("Complete!");

The library supports custom animation frames, allowing you to create unique spinners using any Unicode characters or emojis. It also handles edge cases like cursor visibility and line clearing, making it a robust solution for terminal-based applications.

Usage

import SimpleSpinner from "simplejack";

// Basic usage
const spinner = new SimpleSpinner("Processing...");
spinner.start();

// After some work
spinner.succeed("Complete!");

// Or on error
spinner.fail("Failed!");

Examples

Custom Animation Frames

const customFrames = ["🌑", "🌒", "🌓", "🌔", "🌕", "🌖", "🌗", "🌘"];
const spinner = new SimpleSpinner("Loading...", customFrames);
spinner.start();

Dynamic Text updates

const spinner = new SimpleSpinner("Starting up...");
spinner.start();

// Updates text during an operation
spinner.setText("Processing data...");

Error Handling

const spinner = new SimpleSpinner("Downloading...");
spinner.start();

// On error
spinner.fail("Download failed: Connection timeout");

Methods

• start(): Starts the spinner
• stop(finalText): Stops the spinner with optional final text
• succeed(text): Stops with success indicator (✅)
• fail(text): Stops with error indicator (❌)
• setText(text): Updates the spinner text

Sample run of the CLI tool:

Github - simplejack

Braille characters used from unicode.org/charts/nameslist/n_2800.htm

all opinions are me own