{"id":12711,"library":"bun","title":"Bun JavaScript Runtime","description":"Bun is an all-in-one JavaScript runtime, bundler, transpiler, and package manager, designed for extreme speed and a streamlined developer experience. It is built on Apple's WebKit engine's JavaScriptCore and written in Zig. As of version 1.3.12, Bun offers a highly performant alternative to Node.js, providing native support for TypeScript, JSX, and ES modules out of the box. The project maintains a rapid release cadence with frequent patch and minor versions, often weekly, addressing bugs and introducing new features. Its key differentiators include significantly faster startup times, execution speed, and comprehensive tooling built into a single executable, aiming to replace a multitude of separate tools like Node.js, npm/yarn/pnpm, webpack, Babel, and esbuild. Bun is currently stable for production use but continues to evolve rapidly, adding new features and improving compatibility.","status":"active","version":"1.3.12","language":"javascript","source_language":"en","source_url":"https://github.com/oven-sh/bun","tags":["javascript","bun","bun.js","node","node.js","runtime","bundler","transpiler","typescript"],"install":[{"cmd":"npm install bun","lang":"bash","label":"npm"},{"cmd":"yarn add bun","lang":"bash","label":"yarn"},{"cmd":"pnpm add bun","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The `Bun` object is a global runtime object, similar to `window` in browsers or `process` in Node.js. It does not need to be imported from a package when running code with Bun.","wrong":"import { Bun } from 'bun'","symbol":"Bun","correct":"/* Bun is a global object, no import needed */"},{"note":"Bun supports Node.js built-in modules using the `node:` prefix, which is the recommended way for explicit Node.js compatibility and type safety. While `import { existsSync } from 'fs'` might work due to Bun's automatic resolution, using `node:` is more robust.","wrong":"import { existsSync } from 'fs';","symbol":"existsSync","correct":"import { existsSync } from 'node:fs';"},{"note":"Bun implements Web Standard APIs like `Request`, `Response`, `fetch`, and `URL` globally. These are available without explicit imports, similar to how they work in browsers. TypeScript users can rely on built-in global types or `@types/bun`.","wrong":"import { Request } from 'bun';","symbol":"Request","correct":"const req = new Request('https://example.com');"}],"quickstart":{"code":"import { Server, serve } from 'bun';\n\ninterface Env {\n  PORT?: string;\n}\n\nconst env = process.env as Env;\nconst port = env.PORT ? parseInt(env.PORT, 10) : 3000;\n\nconst server = Bun.serve({\n  port: port,\n  fetch(request: Request): Response {\n    const url = new URL(request.url);\n    if (url.pathname === '/') {\n      return new Response('Hello from Bun! Visit /greet/:name');\n    }\n    if (url.pathname.startsWith('/greet/')) {\n      const name = url.pathname.split('/').pop();\n      return new Response(`Greetings, ${name}!`);\n    }\n    return new Response('404 Not Found', { status: 404 });\n  },\n  error(error: Error): Response {\n    console.error('Server error:', error);\n    return new Response('Internal Server Error', { status: 500 });\n  },\n});\n\nconsole.log(`Bun server listening on http://localhost:${server.port}`);\n","lang":"typescript","description":"This quickstart demonstrates how to create a simple HTTP server using Bun's built-in `Bun.serve` API, handling basic routing and errors. It uses web-standard `Request` and `Response` objects and shows type-safety with TypeScript, which Bun supports natively."},"warnings":[{"fix":"Always pin exact Bun versions in CI/CD environments. Regularly test applications against new Bun versions and consult the official Bun release notes and migration guides.","message":"Bun's API and behavior, especially concerning Node.js compatibility, can change rapidly between minor versions. While efforts are made for backward compatibility, specific edge cases or less-common Node.js APIs might have different implementations or be temporarily unstable. Always review release notes for `bun upgrade`.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Use `bun install --frozen-lockfile` in CI to ensure consistent builds. If issues persist, try `bun install --force` or manually clear `node_modules` and `bun.lockb`. Check Bun's documentation on package resolution for advanced configurations like `\"trustedDependencies\"`.","message":"Bun's package resolution and `bun install` behavior can differ from npm/yarn, particularly with symlinks, monorepos, and specific `postinstall` scripts. This can lead to packages not being found or unexpected build failures if not configured correctly.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Thoroughly test existing Node.js applications when migrating to Bun. Consult Bun's compatibility tables in the documentation for known differences. Consider polyfills or alternative approaches for problematic Node.js APIs.","message":"While Bun aims for high Node.js compatibility, certain Node.js APIs (e.g., specific `fs` options, `child_process` nuances, or older `stream` implementations) might behave differently or be partially implemented. Relying heavily on less common or deprecated Node.js features may lead to unexpected results.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure `package.json` correctly defines `\"main\"`, `\"module\"`, and `\"exports\"` fields. For TypeScript, verify `tsconfig.json`'s `\"paths\"` and `\"baseUrl\"` are compatible with Bun's resolver. Use explicit file extensions in imports where ambiguity might occur.","message":"The default module resolution strategy in Bun prefers `\"exports\"` field in `package.json` and supports various module extensions (`.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.cjs`). Differences in how Bun resolves files compared to Node.js (especially without `type: module` or with complex `tsconfig.json` paths) can cause 'Module not found' errors.","severity":"breaking","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":"If installed via `curl | bash`, the installer attempts to add Bun to your shell's PATH. Restart your terminal or source your shell configuration file (`~/.bashrc`, `~/.zshrc`). If installed via npm (`npm install -g bun`), ensure your npm global bin directory is in your PATH. On Windows, use `powershell -c \"irm bun.sh/install.ps1|iex\"` and restart PowerShell.","cause":"Bun executable is not in the system's PATH.","error":"bun: command not found"},{"fix":"Verify that `my-local-module` is correctly declared in your `package.json` dependencies or that its path is correctly specified in `tsconfig.json`'s `paths` and `baseUrl`. Ensure file extensions are consistent (e.g., if it's a `.ts` file, use `.ts` or ensure your `tsconfig.json` allows omitting it). Use `bun install` to ensure all dependencies are resolved.","cause":"Bun's module resolution differs or `tsconfig.json` paths are not correctly configured/interpreted.","error":"Error: Cannot find module 'my-local-module' from '/path/to/file.ts'"},{"fix":"Refactor the code to use ES module `import` statements. If you explicitly need to `require` a CommonJS module from an ESM context, Bun (like Node.js) allows `createRequire` from `node:module`: `import { createRequire } from 'node:module'; const require = createRequire(import.meta.url);`","cause":"Attempting to use CommonJS `require()` in an ES module (`.js` file with `\"type\": \"module\"` in `package.json` or a `.mjs` file) when Bun enforces ESM strictness.","error":"ReferenceError: require is not defined in ES module scope"},{"fix":"Refactor recursive functions to be iterative where possible. For extremely deep recursion that cannot be easily converted, consider increasing the stack size if Bun provides a flag (check `bun --help`) or process large data in chunks to avoid deep stack usage.","cause":"Bun (specifically its JavaScriptCore engine) might have a smaller default stack size or different tail call optimization behavior than V8 (Node.js). Deep recursion or large data structures can hit this limit sooner.","error":"RangeError: Maximum call stack size exceeded (V8-specific error)"}],"ecosystem":"npm"}