Skip to content
BranchesTags

Repository files navigation

Console Kit

npm versionnode versiontypescript versionlicense

Enhanced terminal UI toolkit for Node.js with TypeScript support. Create beautiful, interactive command-line interfaces with spinners, progress bars, custom colors, and advanced styling.

✨ Features

  • 🎯 Spinners - Beautiful terminal loading animations with 6 predefined styles
  • 📊 Progress Bars - Visual progress tracking with multiple styles and real-time updates
  • 🎨 Advanced Colors - 25 predefined colors + RGB + Hex + Background support
  • 🎭 Text Styling - Bold, italic, underline with full ANSI support
  • ⚡ Performance - Efficient rendering with minimal overhead
  • 🌈 Custom Colors - Support for RGB values, hex codes, and background colors
  • 🔒 Type Safe - Full TypeScript support with strict typing
  • 🚀 Modern - ES modules and Node.js 22+ support

📦 Installation

npm install @neabyte/console-kit

🚀 Quick Start

import{ConsoleKit}from'@neabyte/console-kit'// Create a spinnerconstspinner=ConsoleKit.spinner('Processing files...')awaitspinner.start()// Do some work...awaitprocessFiles()// Stop with success messageawaitspinner.succeed('Files processed successfully!')// Create a progress barconstprogress=ConsoleKit.progress('Uploading files...',{total: 100})awaitprogress.start()// Update progressprogress.update(50)progress.increment(25)// Complete with successawaitprogress.succeed('Upload complete!')

For advanced TypeScript patterns and best practices, see our 📖 TypeScript Usage Guide

🎯 Spinner Usage

Basic Spinner

constspinner=ConsoleKit.spinner('Loading...')awaitspinner.start()// ... do workawaitspinner.succeed('Complete!')

Advanced Customization

constspinner=ConsoleKit.spinner('Building...',{color: '255,100,150',// Custom RGB colorbackgroundColor: '#1a1a1a',// Custom hex backgroundbold: true,// Bold textitalic: true,// Italic textunderline: false,// No underlinespinner: ['⠋','⠙','⠹','⠸','⠼']// Custom animation})

Available Methods

  • start(text?) - Start the spinner animation
  • stop() - Stop the spinner and clear the line
  • succeed(text?) - Stop with success message ✔
  • fail(text?) - Stop with error message ✖
  • warn(text?) - Stop with warning message ⚠
  • info(text?) - Stop with info message ℹ
  • updateText(text) - Update spinner text while running

Spinner Styles

Predefined Styles:

  • dots - Classic dot animation (default) ⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏
  • corners - Elegant corner rotation │┤┘└┐┌┴┬
  • arrows - Directional arrows ←↖↑↗→↘↓↙
  • triangles - Geometric triangles ◢◣◤◥
  • circles - Smooth circle rotation ◐◑◒◓
  • stars - Twinkling stars ★☆✯✰

Custom Styles:

constcustomSpinner=ConsoleKit.spinner('Custom...',{spinner: ['🌍','🌎','🌏']// Your own characters})

📊 Progress Bar Usage

Basic Progress Bar

constprogress=ConsoleKit.progress('Processing...',{total: 100})awaitprogress.start()// Update progressprogress.update(50)progress.increment(25)// Completeawaitprogress.succeed('Processing complete!')

Advanced Customization

constprogress=ConsoleKit.progress('Building project...',{total: 1000,current: 0,style: 'blocks',// Visual stylecolor: 'green',// Progress bar colorbackgroundColor: '#1a1a1a',// Background colorbold: true,// Bold textitalic: false,// No italicunderline: true// Underlined text})

Progress Bar Styles

Available Styles:

  • bar - Solid filled bar with empty blocks (████████░░)
  • blocks - Square blocks pattern (▣▣▣▣▣▣▣▣▣▣)
  • dots - Circular dots pattern (●●●●●●○○○○)

Available Methods

  • start(text?) - Start the progress bar
  • update(current) - Set specific progress value
  • increment(amount) - Increase progress by amount
  • complete() - Set to 100% and display completion
  • succeed(text?) - Complete with success message ✔
  • fail(text?) - Complete with error message ✖
  • warn(text?) - Complete with warning message ⚠
  • info(text?) - Complete with info message ℹ
  • stop() - Stop the progress bar
  • updateText(text) - Update progress text while running

Real-World Examples

File Upload Progress:

constprogress=ConsoleKit.progress('Uploading files...',{total: files.length,style: 'blocks',color: 'blue'})awaitprogress.start()for(leti=0;i<files.length;i++){awaituploadFile(files[i])progress.update(i+1)}awaitprogress.succeed('All files uploaded!')

Data Processing with Updates:

constprogress=ConsoleKit.progress('Processing data...',{total: 1000,style: 'dots',color: 'green'})awaitprogress.start()// Process in batchesfor(leti=0;i<10;i++){awaitprocessBatch(i*100,(i+1)*100)progress.update((i+1)*100)// Update text for each batchprogress.updateText(`Processing batch ${i+1}/10...`)}awaitprogress.succeed('Data processing complete!')

Multiple Concurrent Progress Bars:

consttasks=[{name: 'Task 1',total: 50,style: 'bar',color: 'green'},{name: 'Task 2',total: 30,style: 'blocks',color: 'blue'},{name: 'Task 3',total: 80,style: 'dots',color: 'yellow'}]constprogressBars=tasks.map(task=>ConsoleKit.progress(task.name,task))// Start all progress barsawaitPromise.all(progressBars.map(p=>p.start()))// Update them concurrentlyconstinterval=setInterval(()=>{progressBars.forEach((p,i)=>{constcurrent=Math.min(p.state.current+5,p.state.total)p.update(current)if(current>=p.state.total){p.succeed(`${tasks[i].name} complete!`)}})if(progressBars.every(p=>p.state.current>=p.state.total)){clearInterval(interval)}},200)

🎨 Color System

Predefined Colors (25 total)

Standard Colors:

  • black, red, green, yellow, blue, magenta, cyan, white, gray

Bright Variants:

  • brightBlack, brightRed, brightGreen, brightYellow, brightBlue, brightMagenta, brightCyan, brightWhite

Extended Colors:

  • orange, purple, pink, teal, indigo, lime, brown, gold

Custom Colors

RGB Format:

color: '255,100,150'// Red: 255, Green: 100, Blue: 150
color: '0,255,0'// Pure green
color: '128,0,128'// Purple

Hex Format:

color: '#FF0000'// Red
color: '#00FF00'// Green
color: '#0000FF'// Blue
color: '#FF6B9D'// Custom pink

Background Colors:

backgroundColor: 'red'// Named background
backgroundColor: '255,255,0'// RGB background
backgroundColor: '#FFFF00'// Hex background

Text Styling

Individual Styles:

bold: true// Bold text
italic: true// Italic text
underline: true// Underlined text

Combined Styles:

{bold: true,italic: true,underline: false}

🔧 API Reference

ConsoleKit.spinner(text?, options?)

Creates a new spinner instance with optional configuration.

Parameters:

  • text (string, optional) - Initial text to display
  • options (SpinnerOptions, optional) - Configuration object

Returns: Configured Spinner instance

ConsoleKit.progress(text, options)

Creates a new progress bar instance with required configuration.

Parameters:

  • text (string) - Initial text to display
  • options (ProgressOptions) - Configuration object (total is required)

Returns: Configured Progress instance

SpinnerOptions Interface

interfaceSpinnerOptions{text?: string// Display textstyle?: SpinnerAnimationStyle// Animation stylecolor?: ColorOption// Foreground colorbackgroundColor?: string// Background colorshow?: boolean// Visibility controlspinner?: string[]// Custom animation framesbold?: boolean// Bold textitalic?: boolean// Italic textunderline?: boolean// Underlined text}

ProgressOptions Interface

interfaceProgressOptions{text?: string// Display texttotal: number// Total value (required)current?: number// Current progress valuestyle?: ProgressBarStyle// Visual stylecolor?: ColorOption// Foreground colorbackgroundColor?: string// Background colorshow?: boolean// Visibility controlbold?: boolean// Bold textitalic?: boolean// Italic textunderline?: boolean// Underlined text}

🛠️ Development

# Install dependencies
npm install
# Build the project
npm run build
# Run in development mode
npm run dev
# Lint and type check
npm run check-all
# Run all quality checks
npm run check-all

📁 Project Structure

src/
├── index.ts # Main export file
├── core/ # Core functionality
│ ├── ConsoleKit.ts # Main class with static methods
│ ├── Spinner.ts # Spinner implementation
│ └── Progress.ts # Progress bar implementation
├── interfaces/ # TypeScript type definitions
│ ├── Spinner.ts # All spinner-related interfaces
│ └── Progress.ts # All progress bar interfaces
└── utils/ # Utility functions
└── Colors.ts # Color and styling utilities

🎯 Use Cases

Spinners

  • Build Tools - Show compilation progress
  • CLI Applications - User-friendly loading states
  • Deployment Scripts - Visual feedback for long operations
  • API Clients - Request status visualization

Progress Bars

  • File Operations - Upload/download progress
  • Data Processing - Batch processing progress
  • Build Systems - Compilation progress
  • Database Operations - Query execution progress
  • Network Requests - API call progress
  • Installation Scripts - Package installation progress

🔒 Type Safety

  • Strict Mode - Full TypeScript strict configuration enabled
  • No Any Types - All types are explicitly defined
  • Interface Segregation - Clean separation of concerns
  • Path Aliases - @core/*, @interfaces/*, @utils/*

📚 Advanced TypeScript Usage

For TypeScript patterns, type definitions, and implementation examples, see the detailed guide:

📖 TypeScript Usage Guide

This guide covers:

  • Type-safe configuration patterns
  • Advanced generic types and constraints
  • Custom error handling with TypeScript
  • Real-world examples and production patterns
  • Performance optimization techniques

📄 License

MIT © NeaByteLab

About

Terminal UI toolkit for Node.js with animated spinners, custom colors, and text styling. Create beautiful CLI applications with Console-Kit.

www.npmjs.com/package/@neabyte/console-kit

Topics

animationansiclicolorsconsolees-moduleses6libraryloadingnodejsspinnerterminaltypescriptuiutilities

Resources

Readme
MIT license

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Contributors

Languages