Bun Type Definitions

1.3.12 · active · verified Sun Apr 19

Bun-types provides comprehensive TypeScript type definitions for the Bun JavaScript runtime, currently stable at version 1.3.12. This package is crucial for developers leveraging TypeScript with Bun, offering robust static type checking, autocompletion, and improved developer experience across Bun's unique APIs and global objects. It releases frequently, typically coinciding with major and minor Bun runtime releases, ensuring type definitions remain in sync with the rapidly evolving runtime. Unlike traditional `@types/` packages that target third-party libraries, `bun-types` directly defines the core Bun runtime environment, including its native module system (e.g., `bun:sqlite`, `bun:jsc`), global APIs like `Bun.serve` and `Bun.file`, and Web API implementations (e.g., `fetch`, `Request`, `Response`). Its key differentiator is its tight integration and direct support for Bun's opinionated, high-performance ecosystem, providing an authoritative and up-to-date type experience that reflects Bun's specific behaviors and extensions.

Common errors

```
Cannot find name 'Bun'.
```
cause The `bun-types` package is not installed, or your `tsconfig.json` is not configured to include its types.

fix Install `bun-types` as a dev dependency: `bun add -d bun-types` or `npm install -D bun-types`. Ensure `tsconfig.json` includes `"types": ["bun-types"]` or that the package is discovered automatically.
```
Property 'serve' does not exist on type 'typeof Bun'.
```
cause There is a mismatch between your installed `bun` runtime version and `bun-types` version, or Bun's API has changed.

fix Upgrade both your Bun runtime and `bun-types` to the latest compatible versions. Run `bun upgrade` followed by `bun install --force` or `npm update bun-types`.
```
Module 'bun' has no exported member 'SomeType'. Did you mean to use 'import type'?
```
cause Attempting to import a type as a value, or using the wrong module specifier for a Bun-specific feature (e.g., 'bun' instead of 'bun:sqlite').

fix For type-only imports, use `import type { SomeType } from 'bun'`. For module-specific features, ensure the correct Bun module specifier is used, e.g., `import { Database } from 'bun:sqlite'`.

Warnings

gotcha The `bun-types` package must match the installed `bun` runtime version for accurate type definitions. Mismatched versions can lead to TypeScript errors or missing definitions.
Fix: Run `bun upgrade` to update Bun and then `bun install --force` or `npm update bun-types` to ensure types are in sync.
breaking Bun's APIs, especially in earlier versions, evolve rapidly. Major Bun runtime updates often introduce breaking changes to core APIs (e.g., `Bun.serve`, `Bun.file`), which are reflected in `bun-types`. Always review Bun's release notes.
Fix: Consult Bun's official blog and release notes for each version upgrade. Update your code to match the new API signatures and behaviors.
gotcha Bun implements many Web APIs (e.g., `fetch`, `Request`, `Response`, `URL`) with its own optimizations and sometimes subtle behavioral differences compared to browser or Node.js environments. Types reflect these Bun-specific behaviors.
Fix: Refer to Bun's documentation for specifics on its Web API implementations to understand any differences and ensure compatibility.

Install

npm install bun-types npm
yarn add bun-types yarn
pnpm add bun-types pnpm

Imports

Server
wrong:
```
const Server = require('bun').Server;
```
correct:
```
import type { Server } from 'bun'
```
'Server' is a type declaration from bun-types for Bun's HTTP server. Use 'import type' for type-only imports to prevent bundling issues.
ServeOptions
wrong:
```
import { ServeOptions } from 'bun';
```
correct:
```
import type { ServeOptions } from 'bun'
```
'ServeOptions' defines the configuration for `Bun.serve`. Always use 'import type' for type-only references in modern TypeScript to ensure tree-shaking.
HTMLRewriter
wrong:
```
import { HTMLRewriter } from 'bun';
```
correct:
```
import { HTMLRewriter } from 'bun:jsc'
```
HTMLRewriter is part of Bun's native JavaScriptCore (jsc) module, accessed via the 'bun:jsc' specifier, not the main 'bun' module.

Quickstart

Demonstrates a basic HTTP server using Bun's native `Bun.serve` API, showcasing type safety and core functionality.

import type { ServeOptions, Server } from "bun";

const port = process.env.PORT ?? 3000;

const serverOptions: ServeOptions = {
  port: Number(port),
  async fetch(request: Request): Promise<Response> {
    const url = new URL(request.url);
    if (url.pathname === "/") {
      return new Response("Hello from Bun!", { status: 200 });
    }
    if (url.pathname === "/json") {
      return Response.json({ message: "Hello JSON!", timestamp: Date.now() });
    }
    if (url.pathname === "/delay") {
      await Bun.sleep(1000); // Bun-specific sleep function
      return new Response("Delayed response!", { status: 200 });
    }
    return new Response("Not Found", { status: 404 });
  },
  error(error: Error): Response {
    console.error("Server error:", error);
    return new Response(`Error: ${error.message}`, { status: 500 });
  }
};

const server: Server = Bun.serve(serverOptions);

console.log(`Bun server running on http://localhost:${server.port}`);
console.log(`Server PID: ${server.pid}`);

// Gracefully shut down the server on process termination signals
process.on("SIGINT", () => {
  console.log("Shutting down server...");
  server.stop();
  console.log("Server stopped.");
  process.exit(0);
});

// To run this example: bun run your_file_name.ts

view raw JSON →