chalk-animation-skilld

name	chalk-animation-skilld
description	ALWAYS use when writing code importing "chalk-animation". Consult for debugging, best practices, or modifying chalk-animation, chalk animation.
metadata	{"version":"2.0.3","generated_by":"Anthropic · Haiku 4.5","generated_at":"2026-06-26T00:00:00.000Z"}

bokub/chalk-animation chalk-animation@2.0.3

Tags: latest: 2.0.3

References: package.json • README • Issues • Releases

Search

Use skilld search "query" -p chalk-animation instead of grepping .skilld/ directories. Run skilld search --guide -p chalk-animation for full syntax, filters, and operators.

API Changes

This section documents version-specific API changes — prioritize recent major/minor releases.

• BREAKING: ESM module system — v2.0.0 requires ES Module imports (import chalkAnimation from 'chalk-animation'), no CommonJS support. Previously supported require() source

• BREAKING: Node.js >=12 minimum — v2.0.0 dropped support for Node.js versions older than 12. If targeting older Node versions, remain on v1.6.0 source

• NEW: karaoke animation effect — added in v1.6.0, highlights text as it "plays" character by character. Use chalkAnimation.karaoke(text, speed) source

• NEW: frame() method for manual rendering — added in v1.3.0, returns the next frame's rendered output without displaying it. Allows programmatic frame access: const nextFrame = animation.frame(); console.log(nextFrame); source

• NEW: render() method for frame display — added in v1.3.0, manually renders and displays the current frame. Use with .stop() to control animation timing manually source

• NEW: replace(text) method — added in v1.2.0, seamlessly changes the animated text without restarting the animation. Example: animation.replace('new text') source

• NEW: Multi-line animation support — added in v1.5.0, animations now correctly handle strings containing newlines. Text is split on \r\n, \r, or \n and each line is animated independently source

Also changed: CLI --speed flag added v1.4.0 · CLI --duration flag added v1.4.0

Best Practices

• Always pass string input to animation methods — the library expects strings and will throw str.split is not a function if passed non-string values like the return value of process.stdout.write() source

• Provide speed as a number greater than 0, typically between 0.5 and 2 — speed acts as a divisor on animation frame delays, so values <= 0 throw an error and very high values make animations difficult to read source

• Leverage automatic animation start for immediate visual feedback — created animations start automatically after a brief delay, so no explicit start() call is needed unless you've previously called stop() source

• Use stop() and start() for pause/resume without losing the animation instance — these methods preserve frame state, allowing smooth playback control without recreating the animation object source

• Call replace(newText) to seamlessly update animated text — this is preferable to creating a new animation, as it preserves the running animation state and frame counter source

• Manually render frames with render() or retrieve frame content with frame() when you need non-automatic rendering — this allows frame-by-frame control for custom display logic or testing source

• Be aware that any console.log, console.info, console.warn, or console.error call will automatically stop the current animation — this is by design to prevent animation text from interfering with explicit logging, but can affect multi-animation workflows source

• Use different animations for different visual moods: rainbow (hue rotation), pulse (red/white breathing), glitch (chaotic scrambling), radar (sweeping glow), neon (bold flicker), karaoke (progressive reveal) source

• Adjust speed based on animation type — faster animations like glitch (55ms) benefit from lower speeds (0.5–1), while slower animations like neon (500ms) can tolerate higher speeds source

• Use the CLI --duration flag in non-interactive scripts or demos to automatically stop after N milliseconds, preventing runaway animations in automated contexts source

• For multi-line text, provide newline-delimited strings — the animation preserves line breaks and re-renders all lines together, maintaining text structure source

• Store animation instances in variables when you need later control — the object exposes stop(), start(), replace(), frame(), and render() methods for programmatic manipulation source

• Rely on gradient-string integration in built-in effects for smooth colour transitions — the rainbow and pulse effects use gradient interpolation to create smooth hue changes without manual colour management source