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.