Terminal Text Effects (TypeScript)

A TypeScript vibe-port of the Terminal Text Effects Python library, which provides inline visual effects in the terminal.

I wanted effects in a Deno CLI I was working on. All credit to ChrisBuilds as the only thing I actually did was dedicate time to holding Claude's hand in completing this port. The code was good and well-documented so AI could easily infer architectural details and the port went relatively smoothly.

Features

• Xterm 256 / RGB hex color support
• Character animation with motion and appearance changes
• Color gradients with variable stops/steps
• Event handling with custom callbacks
• Runs inline, preserving terminal state and workflow

Installation

npm install terminal-text-effects

Usage

Basic Example

import { Print, Color, Gradient } from 'terminal-text-effects';

async function main() {
  // Text to apply the effect to
  const text = `Hello, Terminal Text Effects!`;

  // Create a new Print effect with the input text
  const effect = new Print(text);

  // Run the effect
  await effect.run((frame) => {
    // Clear screen and output the current frame
    process.stdout.write('\x1b[2J\x1b[H' + frame);
  });
}

main().catch(console.error);

Customizing Effects

Each effect has its own configuration options that can be customized:

// Create a new Print effect
const effect = new Print(text);

// Customize the effect
effect.effectConfig.printSpeed = 2;
effect.effectConfig.finalGradientStops = [
  new Color('ff5555'),  // Red
  new Color('5555ff'),  // Blue
  new Color('55ff55')   // Green
];
effect.effectConfig.finalGradientDirection = Gradient.Direction.HORIZONTAL;

Available Effects

Currently ported effects:

• Print: Prints text line by line with a simulated print head, including carriage return and line feed animations.

More effects will be ported in future releases.

Development

To build the project:

npm run build

To run tests:

npm test

Effect Development

If you want too submit effects and know Python, I would prefer you craft the effect in Python and submit a PR to the original repository, then either submit a Typescript version or post an Issue requesting a port with a link to the PR (where an agent will be waiting to complete your request)

License

MIT License - See LICENSE file for details.

Acknowledgements

This project is a TypeScript port of the original Terminal Text Effects Python library created by ChrisBuilds.