bun-workers_skill

Overview

This skill provides practical, production-ready patterns for running Web Workers and Node.js worker_threads in Bun. It focuses on parallel processing, worker pools, shared memory, transferable objects, and robust error and shutdown handling. Use it to move CPU-bound or background work off the main thread and scale concurrency safely.

How this skill works

The skill shows how to spawn workers from file URLs or blob code, post and receive messages, and use transferable objects and SharedArrayBuffer for zero-copy and shared memory. It includes a worker_threads worker pool implementation for Node-style environments, plus patterns for progress reporting, parallel map, message channels, and graceful termination. Error handlers and common failure modes are documented to make production runs predictable.

When to use it

• Offload CPU-heavy work (image processing, math, data transforms) to avoid blocking the event loop
• Perform parallel map/reduce over large datasets with controlled concurrency
• Run background tasks or long-running jobs while keeping the main process responsive
• Share large binary buffers between threads without copying using transferable objects
• Coordinate worker-to-worker communication via MessageChannel
• Implement worker pools for throughput and task queuing

Best practices

• Use transferable objects (ArrayBuffer) to avoid costly data copies and detect detached buffers after transfer
• Employ SharedArrayBuffer with Atomics for low-latency coordination and safe shared counters
• Design workers to report progress and support graceful shutdown messages for observability and cleanup
• Limit per-worker responsibilities and use a worker pool for many short tasks to amortize startup cost
• Always add onerror and onmessageerror handlers and send structured error messages from workers
• Terminate or close workers after use to free resources; provide a timeout-based force-terminate fallback

Example use cases

• Image or media processing pipelines that need parallel decoding and encoding
• Numeric simulations or machine-learning feature extraction off the main thread
• A worker pool serving many small tasks (thumbnail generation, file conversions) from an HTTP server
• Streaming or chunked processing with progress updates for long-running jobs
• Worker-to-worker pipelines where one worker pre-processes data and another post-processes it