Home/Docs/console-animations
AN

console-animations

v0.1.3

@backendkit-labs/console-animations

Production-ready terminal animations for Node.js CLI tools.

Overview#

CLI tools that run async operations — builds, deployments, migrations — leave operators staring at a blank terminal for 30–120 seconds with no indication that the process is still alive. Without feedback, a working process looks identical to a hung one, and operators kill it prematurely.

@backendkit-labs/console-animations provides 17 production-grade animation presets with a consistent lifecycle API: start(), stop(id), and destroyAll(). No raw terminal control codes, no TTY handling — just clean primitives that compose with any async workflow.

Animation Types#

17 built-in presets across four semantic categories:

Indeterminate
SPINNERDOTSWORMSNAKE

Best for operations with unknown duration — async triggers, network calls, polling.

Bounded
PROGRESS_BARPULSE

Best for operations with known or estimated progress — file uploads, batch processing.

Thematic
MATRIXHACKERCYBERPUNKFIRE

High-visual-impact presets for branded or security-themed CLI tools.

Ambient
RAINSTARSPARTICLESWAVESTYPINGBOUNCING_BALLFUTURISTA

Background atmosphere for long idle periods or splash screens.

AnimationManager#

AnimationManager is the primary entry point. It manages the full lifecycle of one or more concurrent animations and provides id-based tracking so you can stop the right animation in multi-phase flows without keeping track of references manually.

PropTypeDescription
start(options)AnimationStarts an animation and returns a handle with an id for later stop/query.
stop(id)voidStops a specific animation by id. Clears the terminal line.
stopAll()voidStops all currently running animations.
destroyAll()voidStops and frees all resources. Call at process exit or after the final phase.
getRunning()Animation[]Returns all currently active animation handles.

AnimationBuilder#

AnimationBuilder provides a fluent interface for constructing animations programmatically — useful when animation config is computed at runtime or when you want to pass pre-built animations as arguments to higher-order functions.

custom-animation.ts
import { AnimationBuilder, AnimationType } from '@backendkit-labs/console-animations';

const anim = new AnimationBuilder()
  .withType(AnimationType.MATRIX)
  .withText('Establishing secure connection')
  .withColor('green')
  .withSpeed(50)
  .build();

anim.start();
await connect();
anim.stop();

Examples#

From basic to production-grade — copy and adapt.

spinner.ts
import { AnimationManager, AnimationType } from '@backendkit-labs/console-animations';

const manager = new AnimationManager();

const spinner = manager.start({
  type: AnimationType.SPINNER,
  text: 'Fetching data...',
  color: 'cyan',
  speed: 80,
});

await fetchData();

manager.stop(spinner.id);
console.log('Done.');
View on npmView source on GitHub