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.
- π― 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
npm install @neabyte/console-kitimport { ConsoleKit } from '@neabyte/console-kit'
// Create a spinner
const spinner = ConsoleKit.spinner('Processing files...')
await spinner.start()
// Do some work...
await processFiles()
// Stop with success message
await spinner.succeed('Files processed successfully!')
// Create a progress bar
const progress = ConsoleKit.progress('Uploading files...', { total: 100 })
await progress.start()
// Update progress
progress.update(50)
progress.increment(25)
// Complete with success
await progress.succeed('Upload complete!')For advanced TypeScript patterns and best practices, see our π TypeScript Usage Guide
const spinner = ConsoleKit.spinner('Loading...')
await spinner.start()
// ... do work
await spinner.succeed('Complete!')const spinner = ConsoleKit.spinner('Building...', {
color: '255,100,150', // Custom RGB color
backgroundColor: '#1a1a1a', // Custom hex background
bold: true, // Bold text
italic: true, // Italic text
underline: false, // No underline
spinner: ['β ', 'β ', 'β Ή', 'β Έ', 'β Ό'] // Custom animation
})start(text?)- Start the spinner animationstop()- Stop the spinner and clear the linesucceed(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
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:
const customSpinner = ConsoleKit.spinner('Custom...', {
spinner: ['π', 'π', 'π'] // Your own characters
})const progress = ConsoleKit.progress('Processing...', { total: 100 })
await progress.start()
// Update progress
progress.update(50)
progress.increment(25)
// Complete
await progress.succeed('Processing complete!')const progress = ConsoleKit.progress('Building project...', {
total: 1000,
current: 0,
style: 'blocks', // Visual style
color: 'green', // Progress bar color
backgroundColor: '#1a1a1a', // Background color
bold: true, // Bold text
italic: false, // No italic
underline: true // Underlined text
})Available Styles:
bar- Solid filled bar with empty blocks (ββββββββββ)blocks- Square blocks pattern (β£β£β£β£β£β£β£β£β£β£)dots- Circular dots pattern (ββββββββββ)
start(text?)- Start the progress barupdate(current)- Set specific progress valueincrement(amount)- Increase progress by amountcomplete()- Set to 100% and display completionsucceed(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 barupdateText(text)- Update progress text while running
File Upload Progress:
const progress = ConsoleKit.progress('Uploading files...', {
total: files.length,
style: 'blocks',
color: 'blue'
})
await progress.start()
for (let i = 0; i < files.length; i++) {
await uploadFile(files[i])
progress.update(i + 1)
}
await progress.succeed('All files uploaded!')Data Processing with Updates:
const progress = ConsoleKit.progress('Processing data...', {
total: 1000,
style: 'dots',
color: 'green'
})
await progress.start()
// Process in batches
for (let i = 0; i < 10; i++) {
await processBatch(i * 100, (i + 1) * 100)
progress.update((i + 1) * 100)
// Update text for each batch
progress.updateText(`Processing batch ${i + 1}/10...`)
}
await progress.succeed('Data processing complete!')Multiple Concurrent Progress Bars:
const tasks = [
{ 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' }
]
const progressBars = tasks.map(task => ConsoleKit.progress(task.name, task))
// Start all progress bars
await Promise.all(progressBars.map(p => p.start()))
// Update them concurrently
const interval = setInterval(() => {
progressBars.forEach((p, i) => {
const current = 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)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
RGB Format:
color: '255,100,150' // Red: 255, Green: 100, Blue: 150
color: '0,255,0' // Pure green
color: '128,0,128' // PurpleHex Format:
color: '#FF0000' // Red
color: '#00FF00' // Green
color: '#0000FF' // Blue
color: '#FF6B9D' // Custom pinkBackground Colors:
backgroundColor: 'red' // Named background
backgroundColor: '255,255,0' // RGB background
backgroundColor: '#FFFF00' // Hex backgroundIndividual Styles:
bold: true // Bold text
italic: true // Italic text
underline: true // Underlined textCombined Styles:
{
bold: true,
italic: true,
underline: false
}Creates a new spinner instance with optional configuration.
Parameters:
text(string, optional) - Initial text to displayoptions(SpinnerOptions, optional) - Configuration object
Returns: Configured Spinner instance
Creates a new progress bar instance with required configuration.
Parameters:
text(string) - Initial text to displayoptions(ProgressOptions) - Configuration object (total is required)
Returns: Configured Progress instance
interface SpinnerOptions {
text?: string // Display text
style?: SpinnerAnimationStyle // Animation style
color?: ColorOption // Foreground color
backgroundColor?: string // Background color
show?: boolean // Visibility control
spinner?: string[] // Custom animation frames
bold?: boolean // Bold text
italic?: boolean // Italic text
underline?: boolean // Underlined text
}interface ProgressOptions {
text?: string // Display text
total: number // Total value (required)
current?: number // Current progress value
style?: ProgressBarStyle // Visual style
color?: ColorOption // Foreground color
backgroundColor?: string // Background color
show?: boolean // Visibility control
bold?: boolean // Bold text
italic?: boolean // Italic text
underline?: boolean // Underlined text
}# 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-allsrc/
βββ 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
- Build Tools - Show compilation progress
- CLI Applications - User-friendly loading states
- Deployment Scripts - Visual feedback for long operations
- API Clients - Request status visualization
- 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
- 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/*
For TypeScript patterns, type definitions, and implementation examples, see the detailed 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
MIT Β© NeaByteLab