This page covers the bun-types npm package: its file structure, how type declarations are organized, the patterns used to avoid conflicts with lib.dom.d.ts, the build process, and the integration testing harness that validates the types compile correctly. It also introduces the documentation system used to maintain Bun's official documentation.
For documentation on the Bun APIs themselves, see the relevant API pages (e.g., page Bun Global Object for the global Bun object, page Shell API for the Shell API, page SQL and Database APIs for SQL APIs). For information on the bun:test testing framework, see page Testing Framework.
The packages/bun-types directory contains the bun-types npm package — a collection of TypeScript declaration files that describe the Bun runtime's public API surface. It is published independently as bun-types and is also re-exported by the @types/bun package at packages/@types/bun.
| Package | Location | Purpose |
|---|---|---|
bun-types | packages/bun-types/ | TypeScript declarations for all Bun APIs |
@types/bun | packages/@types/bun/ | Thin wrapper; references bun-types |
The package.json sets "types": "./index.d.ts" as the entry point and lists only .d.ts files, docs, and vendored types in its "files" array packages/bun-types/package.json1-36 The build script is defined as bun scripts/build.ts packages/bun-types/package.json27
Sources: packages/bun-types/package.json1-36 bun.lock24-36
index.d.ts is the single entry point that stitches all other declaration files together through triple-slash references.
packages/bun-types/index.d.ts reference order:
packages/bun-types/index.d.ts1-33
The file also declares onmessage with a special guard to prevent conflicts with lib.dom.d.ts packages/bun-types/index.d.ts31-33
Declaration file responsibilities:
| File | Module/Scope | What it declares |
|---|---|---|
globals.d.ts | Global | ReadableStream, WritableStream, Worker, WebSocket, Event, TextEncoder, TextDecoder, timer functions, etc. |
bun.d.ts | declare module "bun" | Most of the Bun namespace: file(), serve(), spawn(), build(), hashing, TOML, JSONC, JSONL, Workers, etc. |
bun.ns.d.ts | Global Bun | The globalThis.Bun namespace declaration |
overrides.d.ts | Module augmentation | Extensions to node:fs/promises, node:tls, stream/web, buffer, url, console, and NodeJS process globals |
shell.d.ts | declare module "bun" | $ tagged template, ShellPromise, ShellOutput, ShellError packages/bun-types/shell.d.ts1-221 |
fetch.d.ts | declare module "bun" | HeadersInit, BodyInit, fetch option types |
test.d.ts | declare module "bun:test" | test, expect, Matchers, AsymmetricMatchers, mock types |
test-globals.d.ts | Global (opt-in) | test, it, describe, expect, jest, vi as globals packages/bun-types/test-globals.d.ts1-22 |
s3.d.ts | declare module "bun" | S3 client API types |
sqlite.d.ts | declare module "bun:sqlite" | Database, Statement classes |
sql.d.ts | declare module "bun" | Bun.SQL PostgreSQL/MySQL client |
redis.d.ts | declare module "bun" | Valkey/Redis client |
serve.d.ts | declare module "bun" | Bun.serve() option types, Bun.Server |
ffi.d.ts | declare module "bun:ffi" | dlopen, CFunction, JSCallback |
devserver.d.ts | declare module "bun" | HMR event names, import.meta.hot types |
jsc.d.ts | declare module "bun:jsc" | JSC internal APIs: gcAndSweep, heapStats, serialize, profile, etc. |
wasm.d.ts | declare module "bun" | WebAssembly namespace extensions |
html-rewriter.d.ts | Global | HTMLRewriter API |
bundle.d.ts | declare module "bun:bundle" | feature() function, Registry interface |
deprecated.d.ts | declare module "bun" | Types marked @deprecated |
extensions.d.ts | Global | TypeScript extensions |
security.d.ts | declare module "bun" | Security-related APIs |
Sources: packages/bun-types/index.d.ts1-33 packages/bun-types/shell.d.ts1-221 packages/bun-types/test-globals.d.ts1-22 packages/bun-types/overrides.d.ts1-208
Package structure and type resolution diagram:
Sources: packages/bun-types/index.d.ts1-33 packages/bun-types/package.json1-36 bun.lock10-42
UseLibDomIfAvailable PatternA central challenge in bun-types is that many types (ReadableStream, Worker, WebSocket, MessageEvent, etc.) are declared both in Bun's types and in TypeScript's lib.dom.d.ts. Loading both causes redeclaration errors.
The solution is the Bun.__internal.UseLibDomIfAvailable<GlobalThisKeyName, Otherwise> conditional type.
lib.dom.d.ts is loaded by testing if specific DOM-only properties exist on globalThis.globalThis to avoid conflict.This is applied in globals.d.ts for major web APIs. For example, onmessage is guarded in the main index packages/bun-types/index.d.ts31-33
Conflict resolution pattern diagram:
Sources: packages/bun-types/index.d.ts31-33 test/integration/bun-types/fixture/streams.ts13-22
overrides.d.tsoverrides.d.ts augments existing TypeScript and Node.js modules to add Bun-specific methods and properties. It uses declare module to extend:
| Augmented module | Added types |
|---|---|
stream/web | ReadableStream gets BunConsumerConvenienceMethods (.text(), .bytes(), .json()) and .blob() packages/bun-types/overrides.d.ts28-35 |
buffer | Blob gets convenience methods, .formData(), .arrayBuffer(), .image(), and .stream() packages/bun-types/overrides.d.ts37-65 |
url | URLSearchParams.toJSON() packages/bun-types/overrides.d.ts68-72 |
NodeJS namespace | ProcessEnv extends Bun.Env, Process.isBun, Process.revision, Process.reallyExit, and memoryPressure event listeners packages/bun-types/overrides.d.ts74-117 |
Sources: packages/bun-types/overrides.d.ts1-208
test-globals.d.ts is intentionally not included in index.d.ts. It must be loaded explicitly via a triple-slash directive:
This declares test, it, describe, expect, beforeAll, jest, vi, etc., as globals packages/bun-types/test-globals.d.ts1-22
For details, see Testing Type Definitions.
The test at test/integration/bun-types/bun-types.test.ts validates that the published bun-types package type-checks correctly under various compiler configurations. It uses the typescript API to create a LanguageService and check for diagnostics test/integration/bun-types/bun-types.test.ts174-201
Test setup sequence:
Sources: test/integration/bun-types/bun-types.test.ts32-85
Fixture files tested:
| Fixture file | What it exercises |
|---|---|
fixture/index.ts | General Bun API surface: Bun.file, Bun.serve, Bun.spawn, Shell $, S3, fetch proxy options test/integration/bun-types/fixture/index.ts1-310 |
fixture/spawn.ts | Bun.spawn() / Bun.spawnSync() type inference for stdio configurations (pipe, inherit, ignore, null) test/integration/bun-types/fixture/spawn.ts11-229 |
fixture/serve-types.test.ts | Bun.serve() options, Bun.Server<T> generic, WebSocket handlers with custom data types test/integration/bun-types/fixture/serve-types.test.ts16-206 |
fixture/streams.ts | Web Streams API extensions, direct stream type, and CompressionStream test/integration/bun-types/fixture/streams.ts1-87 |
For details on API specific types, see Bun API Types.
Bun's documentation is structured using MDX files and a central configuration file docs/docs.json.
docs/docs.json defines the navigation structure, sidebar groups (Runtime, Package Manager, Bundler), and theme settings docs/docs.json1-240For details on the documentation infrastructure, see Documentation System.
Sources: docs/docs.json1-240