newyear-fireworks

A beautiful terminal firework animation package for celebrations! Supports both Lunar New Year (Vietnamese/Chinese zodiac) and regular New Year celebrations.

Quick Start

npx newyear-fireworks

Usage

# Default celebration (shows "Happy New Year [Current Year]!")
npx newyear-fireworks

# Custom message
npx newyear-fireworks "Happy Birthday!"

# Multi-line message
npx newyear-fireworks -t "Thank you for an amazing 2025!\nWishing you success in 2026!"

# High intensity, longer duration
npx newyear-fireworks -t "Congratulations!" -i high -d 20

# Fireworks only (no text)
npx newyear-fireworks --no-text -i extreme

# Run forever until Ctrl+C
npx newyear-fireworks -f

Lunar New Year / Zodiac

Display zodiac animals for Lunar New Year celebrations!

# Show zodiac animal for current year (Vietnamese by default)
npx newyear-fireworks --zodiac

# Specify a year
npx newyear-fireworks -z -y 2026

# Vietnamese zodiac (Cat for year 2023)
npx newyear-fireworks --vn -y 2023

# Chinese zodiac (Rabbit for year 2023)
npx newyear-fireworks --cn -y 2023

# List all zodiac animals
npx newyear-fireworks --list-zodiac
npx newyear-fireworks --cn --list-zodiac

Vietnamese vs Chinese Zodiac

The main difference is the 4th animal:

| Year | Vietnamese | Chinese | |------|------------|---------| | 2023 | Cat (Mao/Meo) | Rabbit | | 2024 | Dragon | Dragon | | 2025 | Snake | Snake | | 2026 | Horse | Horse |

Options

General Options

| Option | Description | |--------|-------------| | -t, --text <text> | Set the celebration message (use \n for new lines) | | -d, --duration <secs> | Duration in seconds (default: 10) | | -i, --intensity <level> | Firework intensity: low, medium, high, extreme | | -c, --color <color> | Text color (see colors below) | | --no-text | Hide the text message | | -f, --forever | Run forever (until Ctrl+C) | | -h, --help | Show help message |

Zodiac Options

| Option | Description | |--------|-------------| | -z, --zodiac | Show zodiac animal for the current year | | -y, --year <year> | Specify year for zodiac animal | | --vn, --vietnamese | Vietnamese zodiac - Cat instead of Rabbit (default) | | --cn, --chinese | Chinese zodiac - Rabbit instead of Cat | | --lunar | Alias for --zodiac | | --list-zodiac | List all zodiac animals and their years |

Colors

Available text colors:

• rainbow (animated, default)
• red, green, yellow, blue, magenta, cyan, white
• brightRed, brightGreen, brightYellow, brightBlue, brightMagenta, brightCyan, brightWhite

Examples

# New Year celebration
npx newyear-fireworks -t "Happy New Year 2026!" -i high

# Vietnamese Lunar New Year
npx newyear-fireworks --vn -t "Chuc Mung Nam Moi!"

# Chinese New Year
npx newyear-fireworks --cn -t "Happy Chinese New Year!\nYear of the Horse"

# Birthday party
npx newyear-fireworks -t "Happy Birthday!\nMake a wish!" -c yellow -i extreme

# Thank you message
npx newyear-fireworks -t "Thank you for an amazing 2025!\nWishing you success in 2026!"

# Just fireworks, no text
npx newyear-fireworks --no-text -i extreme -f

Programmatic Usage

const { FireworksDisplay } = require('newyear-fireworks');

const display = new FireworksDisplay({
  text: 'Hello World!',
  duration: 5000,
  intensity: 'high',
  textColor: 'rainbow',
  showZodiac: true,
  zodiacYear: 2026,
  zodiacCulture: 'vietnamese'  // or 'chinese'
});

display.start();

Zodiac API

const { getZodiacInfo, getAllZodiacs } = require('newyear-fireworks/lib/zodiac');

// Get zodiac for a specific year
const info = getZodiacInfo(2026, 'vietnamese');
console.log(info.animal);    // 'horse'
console.log(info.localName); // 'Ngo (Ngua)'

// Get all zodiac animals
const all = getAllZodiacs('chinese');
console.log(all);

Author

Created by Hoang Le with Claude Code

License

MIT