text-shimmer

Give any terminal string a gentle, animated shimmer. This Bun-powered package bundles a CLI and a tiny API so you can drop the effect into status banners, onboarding scripts, or whatever else needs a little spotlight.

Quick start

1. bun add @lahfir/text-shimmer
2. bun run build
3. bun ./dist/cli.js "Shipping soon"

Tip: during development you can run straight from TypeScript with bun src/cli.ts "Draft build" to skip the build step.

Use the CLI

text-shimmer "Release party" --palette "red,white,gold" --speed 60

• Colours can be hex (#ec4899) or plain words (magenta, light gray, teal).
• --static prints a single shimmer frame, handy for screenshots.
• --speed controls the delay between frames in milliseconds.
• --width widens the glow if you want a slower roll.
• --bold flips on ANSI bold when you want extra emphasis.
• --once or --iterations let you cap the loops.

Pipe anything in:

echo "Deploying service" | text-shimmer --palette "cyan,purple" --once

Embed in your own tool

import { createShimmerSequence, animateToStream } from "@lahfir/text-shimmer";

const banner = createShimmerSequence("Build complete", {
  palette: ["skyblue", "white", "gold"],
  highlightWidth: 8,
  bold: true,
});

console.log(banner.frameAt(0));

await animateToStream(process.stdout, "Waiting on staging", {
  speed: 40,
  iterations: 2,
});

The shimmer smoothly blends between the base colour (defaults to a soft gray) and your palette. Pass baseColor: null or --plain if you want to skip the overlay entirely, and add bold: true or --bold whenever you want the text weight turned up.

Options at a glance

| Flag | Purpose | | ----------------------------- | ------------------------------------------------------- | | --palette <a,b,c> | Comma-separated colours (hex or names) for the gradient | | --base <colour> | Base colour outside the shimmer (hex or name) | | --bold | Apply ANSI bold styling to the text | | --frames <count> | Override the total frames in the loop | | --width <number> | Grow or shrink the shimmer spread | | --speed <ms> | Delay between frames | | --plain | Disable colour output | | --static | Print only one frame | | --once / --iterations <n> | Control looping | | --help / --version | Utility info |

Work on the project

bun install
bun run build
bun test

The build emits dist/index.js and dist/cli.js. Tests (and the shimmer itself) run on the Bun runtime.