{"id":10601,"library":"bun-types","title":"Bun Type Definitions","description":"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.","status":"active","version":"1.3.12","language":"javascript","source_language":"en","source_url":"https://github.com/oven-sh/bun","tags":["javascript","bun","bun.js","types","typescript"],"install":[{"cmd":"npm install bun-types","lang":"bash","label":"npm"},{"cmd":"yarn add bun-types","lang":"bash","label":"yarn"},{"cmd":"pnpm add bun-types","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"'Server' is a type declaration from bun-types for Bun's HTTP server. Use 'import type' for type-only imports to prevent bundling issues.","wrong":"const Server = require('bun').Server;","symbol":"Server","correct":"import type { Server } from 'bun'"},{"note":"'ServeOptions' defines the configuration for `Bun.serve`. Always use 'import type' for type-only references in modern TypeScript to ensure tree-shaking.","wrong":"import { ServeOptions } from 'bun';","symbol":"ServeOptions","correct":"import type { ServeOptions } from 'bun'"},{"note":"HTMLRewriter is part of Bun's native JavaScriptCore (jsc) module, accessed via the 'bun:jsc' specifier, not the main 'bun' module.","wrong":"import { HTMLRewriter } from 'bun';","symbol":"HTMLRewriter","correct":"import { HTMLRewriter } from 'bun:jsc'"}],"quickstart":{"code":"import type { ServeOptions, Server } from \"bun\";\n\nconst port = process.env.PORT ?? 3000;\n\nconst serverOptions: ServeOptions = {\n  port: Number(port),\n  async fetch(request: Request): Promise<Response> {\n    const url = new URL(request.url);\n    if (url.pathname === \"/\") {\n      return new Response(\"Hello from Bun!\", { status: 200 });\n    }\n    if (url.pathname === \"/json\") {\n      return Response.json({ message: \"Hello JSON!\", timestamp: Date.now() });\n    }\n    if (url.pathname === \"/delay\") {\n      await Bun.sleep(1000); // Bun-specific sleep function\n      return new Response(\"Delayed response!\", { status: 200 });\n    }\n    return new Response(\"Not Found\", { status: 404 });\n  },\n  error(error: Error): Response {\n    console.error(\"Server error:\", error);\n    return new Response(`Error: ${error.message}`, { status: 500 });\n  }\n};\n\nconst server: Server = Bun.serve(serverOptions);\n\nconsole.log(`Bun server running on http://localhost:${server.port}`);\nconsole.log(`Server PID: ${server.pid}`);\n\n// Gracefully shut down the server on process termination signals\nprocess.on(\"SIGINT\", () => {\n  console.log(\"Shutting down server...\");\n  server.stop();\n  console.log(\"Server stopped.\");\n  process.exit(0);\n});\n\n// To run this example: bun run your_file_name.ts\n","lang":"typescript","description":"Demonstrates a basic HTTP server using Bun's native `Bun.serve` API, showcasing type safety and core functionality."},"warnings":[{"fix":"Run `bun upgrade` to update Bun and then `bun install --force` or `npm update bun-types` to ensure types are in sync.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Consult Bun's official blog and release notes for each version upgrade. Update your code to match the new API signatures and behaviors.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Refer to Bun's documentation for specifics on its Web API implementations to understand any differences and ensure compatibility.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The `bun-types` package is not installed, or your `tsconfig.json` is not configured to include its types.","error":"Cannot find name 'Bun'."},{"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`.","cause":"There is a mismatch between your installed `bun` runtime version and `bun-types` version, or Bun's API has changed.","error":"Property 'serve' does not exist on type 'typeof Bun'."},{"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'`.","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').","error":"Module 'bun' has no exported member 'SomeType'. Did you mean to use 'import type'?"}],"ecosystem":"npm"}