shepherdjerred/monorepo/bun-runtime-best-practices

Bun Runtime Best Practices

Use Bun APIs when they provide a clear Bun-native capability. Use standard Web APIs for portability and node: APIs when Bun does not cover the operation or the code must remain Node-compatible. Do not replace a correct portable API merely because a Bun equivalent exists.

Current baseline

Verified against Bun 1.3.14 on 2026-08-03. Check the project pin and runtime before relying on a newly added API:

bun --version

Bun 1.3.14 adds Bun.Image, faster isolated-linker warm installs, and experimental HTTP/2 and HTTP/3 server support. Features explicitly marked experimental in Bun's documentation are not stable defaults.

Read references/release-notes-1.3.md when upgrading Bun or evaluating a new 1.3 API. Read references/io-process-modules.md for detailed file, subprocess, shell, environment, module, stream, binary, hashing, and worker patterns. Read references/data-networking.md for HTTP, WebSocket, SQL, Redis, SQLite, S3, cookies, CSRF, secrets, and cron guidance.

Choose the narrowest correct API

Validate system boundaries

Environment variables, request bodies, database results, Redis values, and file JSON are untrusted input. Parse them before assigning domain types.

import { z } from "zod";
const Environment = z.object({
  DATABASE_URL: z.string().url(),
  PORT: z.coerce.number().int().min(1).max(65_535).default(3000),
});
const environment = Environment.parse(Bun.env);

Bun.env, process.env, and import.meta.env expose the same environment. Bun.env does not make arbitrary variables statically safe; schema validation does.

Files and paths

Bun.file("relative/path") resolves relative to the process working directory, not the current source file. Anchor source-relative resources explicitly.

import { join } from "node:path";
import { z } from "zod";
const Config = z.object({
  name: z.string(),
  retries: z.number().int().min(0),
});
const configPath = join(import.meta.dir, "config.json");
const config = Config.parse(await Bun.file(configPath).json());
await Bun.write(join(import.meta.dir, "generated", "output.json"), JSON.stringify(config), {
  createPath: true,
});

Use node:fs/promises for directory and metadata operations that Bun.file and Bun.write do not model.

Subprocesses

Prefer literal argv. Capture stderr and enforce the exit status before consuming output as successful.

const process = Bun.spawn(["git", "status", "--short"], {
  cwd: import.meta.dir,
  stdout: "pipe",
  stderr: "pipe",
});
const [stdout, stderr, exitCode] = await Promise.all([
  new Response(process.stdout).text(),
  new Response(process.stderr).text(),
  process.exited,
]);
if (exitCode !== 0) {
  throw new Error(`git status failed (${exitCode}): ${stderr}`);
}

Do not pass dynamic values through sh -c. Use Bun.spawn() argv or Bun Shell interpolation. Bun Shell escapes interpolated strings, but callers must still prevent option injection when user-controlled values can begin with -.

Modules and compatibility

Prefer ESM for new Bun code, but do not claim CommonJS is unsupported. Bun supports both. Follow the repository's import-extension convention; Bun does not require .ts extensions universally.

Use Buffer when an API contract requires it. It is a supported Uint8Array subclass. Prefer Uint8Array, ArrayBuffer, Blob, and Web streams for portable new interfaces.

Check Bun's Node compatibility table before replacing or adopting a Node API. Compatibility is API-specific, not all-or-nothing.

Servers and network clients

Use Bun.serve() for Bun-native HTTP or WebSocket servers and Web fetch() for outbound HTTP. Validate request data before use and make error paths explicit.

const server = Bun.serve({
  port: environment.PORT,
  routes: {
    "/health": new Response("ok"),
  },
  fetch(request) {
    return new Response(`Not found: ${new URL(request.url).pathname}`, { status: 404 });
  },
});
console.log(`Listening on ${server.url}`);

HTTP/2 and HTTP/3 support added in Bun 1.3.14 is experimental. Do not make production compatibility claims without testing the deployed protocol, TLS, proxy, and client path.

Data clients

Bun includes SQL, Redis, SQLite, and S3 clients. Their APIs are not interchangeable:

• Create a SQL connection with new SQL(connectionString) and execute parameterized queries with the connection's tagged template.
• Use redis for the default client or new RedisClient(url) for an explicit connection; close explicit clients with .close().
• Use bun:sqlite for embedded SQLite and Bun.s3 / S3Client for S3-compatible object storage.
• Parse database and cache values at the boundary; generated TypeScript types are not runtime validation.

See references/data-networking.md for current examples and lifecycle details.

Security rules

• Use Bun.password only for password hashing and verification. Its supported password algorithms are Argon2 and bcrypt; do not document scrypt as supported by this API.
• Use Web Crypto or node:crypto for cryptographic digests and signatures. Bun.hash is non-cryptographic.
• Bind CSRF tokens to a session identifier and verify them at mutation boundaries.
• Treat the secrets API and newly introduced protocol support according to their documented stability level.
• Never log secrets, full environment objects, authorization headers, or raw database URLs.

Tests and scheduled work

Use the repository's existing test command. Current Bun test capabilities include process isolation, parallel execution, sharding, and changed-file selection; choose flags deliberately so tests remain deterministic. Do not mask missing build artifacts with skipped tests.

Cron expressions schedule callbacks inside a running Bun process. OS cron support creates operating-system schedules. Neither is a durable distributed scheduler; use the system's established orchestration for retryable, observable production workflows.

Review checklist

• Verify the project's pinned Bun version before using a recent API.
• Keep CWD-relative and module-relative paths distinct.
• Check every subprocess exit code and preserve stderr in failures.
• Validate environment, HTTP, file, cache, and database input.
• Use password and cryptographic hash APIs for their intended purposes.
• Close explicit SQL, Redis, file, worker, and server resources when their lifecycle ends.
• Mark experimental APIs and performance figures as conditional, not universal promises.
• Prefer focused Bun-native APIs without banning supported Web or Node APIs.