Skip to content
Tutorials Center
My learning

Topics

Lesson 35 of 39 ยท Deploy and Compatibility

Production Hardening, Workers and Performance

Run Bun services reliably: graceful shutdown on SIGTERM, structured logging, timeouts and limits, Web Workers for CPU-bound work, reusePort, memory flags, measuring performance and a launch checklist.

A server that works on your laptop is not yet a service. In production, processes are stopped and replaced all the time (deploys, scaling, crashes), requests arrive in bursts, one slow computation can freeze everyone, and when something fails at 3 a.m. the logs are all you have. This lesson covers the habits that make a Bun service dependable.

Bun is not available on this site, so Bun code is read-only. TryIt blocks demonstrate the same patterns with Node 24 (node:http, node:worker_threads). Shapes differ slightly where we say so.

Graceful shutdown

When a container stops, the platform sends SIGTERM and, after a grace period (often 10 to 30 seconds), SIGKILL. A graceful shutdown stops accepting new connections, lets running requests finish, closes databases and then exits. Without it, users see dropped requests on every deploy.

TypeScript
import { Database } from "bun:sqlite";

const db = new Database("app.db");
const server = Bun.serve({ port: 3000, fetch: () => new Response("ok") });

let shuttingDown = false;
async function shutdown(signal: string) {
  if (shuttingDown) return;
  shuttingDown = true;
  console.log(JSON.stringify({ level: "info", msg: "shutting down", signal }));

  await server.stop();       // stop listening, wait for in-flight requests
  db.close();                // flush and close resources
  process.exit(0);
}

process.on("SIGTERM", () => shutdown("SIGTERM"));
process.on("SIGINT", () => shutdown("SIGINT"));   // Ctrl+C

server.stop() without arguments is graceful; server.stop(true) forces connections closed (use it as a last resort after a timeout). Also handle the failures you did not predict:

TypeScript
process.on("uncaughtException", (err) => {
  console.error(JSON.stringify({ level: "fatal", msg: err.message, stack: err.stack }));
  process.exit(1);               // let the supervisor restart a clean process
});
process.on("unhandledRejection", (reason) => {
  console.error(JSON.stringify({ level: "error", msg: "unhandled rejection", reason: String(reason) }));
});

After an uncaught exception the process state is unknown, so log and exit; a supervisor (Docker restart policy, systemd, your platform) starts a fresh one.

Node.js Graceful shutdown: in-flight requests finish (Node stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Logging

In production, log one JSON object per line to stdout. Log collectors parse it, filter it by field and graph it. Include a level, a message and context such as a request id and duration:

TypeScript
function log(level: "info" | "warn" | "error", msg: string, extra: Record<string, unknown> = {}) {
  console.log(JSON.stringify({ time: new Date().toISOString(), level, msg, ...extra }));
}

Bun.serve({
  async fetch(req) {
    const id = crypto.randomUUID();
    const start = performance.now();
    const res = new Response("ok");
    log("info", "request", {
      id, method: req.method, path: new URL(req.url).pathname,
      status: res.status, ms: Math.round(performance.now() - start),
    });
    return res;
  },
});

Never log passwords, tokens, full credit card numbers or whole request bodies. Libraries such as pino work on Bun if you want levels, redaction and transports built in.

Limits and timeouts

Protect the server from slow or huge requests with settings you already know:

TypeScript
Bun.serve({
  maxRequestBodySize: 1024 * 1024,   // 1 MB
  idleTimeout: 30,                   // seconds before idle connections close
  fetch: handler,
});

On outgoing calls add AbortSignal.timeout(ms), so one slow dependency cannot hold your handlers forever (see headers and fetch). Add rate limiting per IP or API key for public endpoints. Often the proxy in front (nginx, Cloudflare) does this.

CPU-bound work and Workers

JavaScript runs your code on one thread. Waiting for a database or network is cheap because it is asynchronous, but a CPU-heavy loop (image resizing, big JSON transforms, hashing a file, a long calculation) blocks the thread, and no other request is served until it ends. Move such work to a Worker: a separate thread with its own event loop. Bun uses the web standard Worker class:

TypeScript
// main.ts
const worker = new Worker(new URL("./worker.ts", import.meta.url));

worker.onmessage = (event: MessageEvent) => {
  console.log("result:", event.data);
  worker.terminate();
};
worker.postMessage({ n: 40 });
TypeScript
// worker.ts
declare var self: Worker;

function fib(n: number): number {
  return n < 2 ? n : fib(n - 1) + fib(n - 2);
}

self.onmessage = (event: MessageEvent) => {
  self.postMessage(fib(event.data.n));
};

Messages are copied with the structured clone algorithm (objects, arrays, Maps, typed arrays all work; functions do not). Transfer large ArrayBuffers without copying: postMessage(buffer, [buffer]). Create a small pool of workers (about the number of CPU cores) rather than one per request, since starting a worker costs a few milliseconds.

Node has the equivalent node:worker_threads module, which Bun also supports. The stand-in below uses it.

Node.js Offloading CPU work to a worker thread (node:worker_threads)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Using several cores

One Bun process uses one core for JavaScript. To use more, run several processes that share one port: Bun supports reusePort: true on Linux, so the kernel spreads connections between processes that listen on the same port.

TypeScript
Bun.serve({ port: 3000, reusePort: true, fetch: handler });

Start as many copies as you have cores (with systemd, Docker replicas or a small supervisor script using Bun.spawn). Because processes do not share memory, keep state in the database or Redis, not in module variables. Often it is simpler to run one container per core behind your platform's load balancer.

Performance in practice

  • Measure first. performance.now() and Bun.nanoseconds() time code; load-test with bombardier, wrk or k6. Compare p50 and p99 latency, not only the average.
  • Do less work per request: reuse prepared SQL statements, avoid parsing the same JSON repeatedly, cache expensive results in memory with a time limit, and return Response objects for static content once (as static routes).
  • Stream big payloads (streaming lesson); do not build giant strings.
  • Batch database writes inside a transaction (bun:sqlite).
  • Memory: watch process.memoryUsage(). For small containers, bun --smol run app.ts favors lower memory over speed. A steadily growing heap usually means a leak: unbounded caches, listeners never removed, closures kept in global arrays.
  • Profile when numbers surprise you: bun --inspect attaches the debugger (WebKit inspector protocol, usable from Chrome DevTools-style clients and the VS Code extension), and recent versions can print heap and CPU profiles.
Node.js A tiny in-memory cache with expiry

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

A launch checklist

  1. Graceful shutdown on SIGTERM and SIGINT; uncaughtException logs and exits.
  2. JSON logs to stdout, with request ids; no secrets in logs.
  3. Body-size, idle and fetch timeouts configured.
  4. CPU-heavy work in Workers or a queue; several processes for several cores.
  5. Health and readiness endpoints; restart policy in the supervisor.
  6. Metrics and alerts: error rate, latency percentiles, memory, restarts.
  7. Backups of the database; a tested restore.
  8. A rollback you have actually practiced.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What should a graceful shutdown do on SIGTERM?

    That sequence avoids dropping requests during deploys.
  2. 2. Why does a CPU-heavy loop in a request handler hurt other users?

    The event loop cannot serve other requests while synchronous code runs.
  3. 3. How do Workers receive data?

    Threads do not share JavaScript objects; messages are cloned or transferred.
  4. 4. What is reusePort: true for?

    It lets multiple Bun processes bind one port (Linux), spreading load across cores.
  5. 5. What logging format suits production collectors?

    Structured lines can be parsed, filtered and graphed; containers should log to stdout.

Summary

  • Handle SIGTERM/SIGINT gracefully; on uncaughtException log and exit so a supervisor can restart.
  • Log JSON lines without secrets; set body, idle and fetch timeouts.
  • Move CPU-bound work to Workers (pool them) or a job queue; use reusePort or multiple containers for more cores.
  • Measure before optimizing: reuse statements, stream, batch writes, cache with expiry, watch memory (--smol).
  • Follow a checklist and practice the rollback.

Next: Project: A REST API with Bun and SQLite