task-boxer 🩳✓

https://github.com/user-attachments/assets/8e772143-4fe3-4aed-a510-04694ebe3229

Terminal logging library with interactive task boxes in TTY mode and timestamped fallback for non-TTY environments.

Inspired by Python's Rich library.

Features

• Task boxes - Group logs by task with bordered boxes showing the last N lines
• Parallel tasks - Track multiple concurrent operations with separate task boxes
• Auto-detection - Uses interactive UI in terminals, falls back to flat logs in CI/pipes
• Child process capture - Run shell commands and capture output to task logs
• Completion tracking - Tasks show duration and completion status (✓ or ✗)

Installation

npm install task-boxer

Usage

import { logger, task } from 'task-boxer';

// General logging
logger.info('Starting application...');
logger.warn('Low memory detected');

// Task-scoped logging
const t = task('Processing Images');
t.log('Image 1/5 uploading...');
t.log('Image 2/5 generating...');
t.complete('5 images processed');  // Shows: ✓ Processing Images: 5 images processed (2.3s)

// Child process capture
const build = task('Building');
await build.exec('npm run build');
build.complete('Build successful');

TTY Mode (Terminal)

When running in a terminal, you'll see interactive task boxes:

╭─ ● Processing Images (2.3s) ──────────────────╮
│ Image 3/5 uploading...                        │
│ Image 4/5 generating...                       │
│ Image 5/5 optimizing...                       │
╰───────────────────────────────────────────────╯
╭─ ● Building Assets (1.1s) ────────────────────╮
│ Compiling TypeScript...                       │
│ Bundling modules...                           │
╰───────────────────────────────────────────────╯
╭─ General Logs ────────────────────────────────╮
│ 14:30:45 [INF] Server health check passed     │
│ 14:30:46 [INF] ✓ Auth: Login successful (0.5s)│
│ 14:30:47 [WRN] Rate limit approaching (80%)   │
╰───────────────────────────────────────────────╯

Non-TTY Mode (CI/Pipes)

When stdout is not a terminal (CI, piped output, etc.), logs are flat with timestamps:

[2024-01-24T15:30:45.123Z] [INFO ] Starting application...
[2024-01-24T15:30:45.200Z] [INFO ] [Task:Processing Images] Image 1/5 uploading...
[2024-01-24T15:30:46.100Z] [INFO ] [Task:Processing Images] Image 2/5 generating...
[2024-01-24T15:30:50.300Z] [INFO ] ✓ Processing Images: 5 images processed (4.2s)

API

logger

Global logger for general messages.

logger.debug(message: string): void
logger.info(message: string): void
logger.warn(message: string): void
logger.error(message: string): void
logger.configure({
  minLevel?: 'debug' | 'info' | 'warn' | 'error',
  boxGeneral?: boolean,  // Show box around general logs (default: false)
  maxTasks?: number,     // Max lines per task box
  generalLogsLines?: number,  // Lines in general logs section
}): void

task(title: string): Task

Create a new task with scoped logging.

interface Task {
  log(message: string): void;
  debug(message: string): void;
  warn(message: string): void;
  error(message: string): void;
  complete(summary: string | string[]): void;
  fail(error: string | string[]): void;
  exec(command: string): Promise<{ exitCode: number; stdout: string; stderr: string }>;
}

Bundler Configuration

Next.js

When using task-boxer in a Next.js application, add it to serverExternalPackages in your next.config.ts:

const nextConfig: NextConfig = {
  serverExternalPackages: ['task-boxer', 'ink'],
};

This prevents Next.js from bundling ink's react-devtools-core dependency which is not needed in production.

Other Bundlers

task-boxer uses dynamic imports for TTY mode, so the ink dependency is only loaded when running in a terminal. For non-TTY environments (CI, serverless), only the lightweight fallback logger is used.

If you encounter bundling issues, mark task-boxer and ink as external in your bundler config.

Demo

Run the included demo:

git clone https://github.com/baytelman/task-boxer
cd task-boxer
npm install
npm run demo

Why "task-boxer"?

Because it boxes up your tasks. Also, our mascot wears boxer shorts with checkmarks. 🩳✓

License

MIT