open-index/open-npm huggingface dataset:
npm package: @lahfir/text-shimmer
Description: Bun-powered CLI for generating animated shimmer text frames.
Latest version: 0.1.0

# 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

```ts
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.