Bun JavaScript Runtime

Common errors

• bun: command not found

  cause Bun executable is not in the system's PATH.
  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.

• Error: Cannot find module 'my-local-module' from '/path/to/file.ts'

  cause Bun's module resolution differs or `tsconfig.json` paths are not correctly configured/interpreted.
  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.

• ReferenceError: require is not defined in ES module scope

  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.
  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);`

• RangeError: Maximum call stack size exceeded (V8-specific error)

  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.
  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.

Warnings

• breaking 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`.
  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.
• gotcha 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.
  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"`.
• gotcha 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.
  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.
• breaking 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.
  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.

Install

• npm install bun npm
• yarn add bun yarn
• pnpm add bun pnpm

Imports

• Bun
  wrong:

  import { Bun } from 'bun'

  correct:

  /* Bun is a global object, no import needed */

  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.
• existsSync
  wrong:

  import { existsSync } from 'fs';

  correct:

  import { existsSync } from 'node:fs';

  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.
• Request
  wrong:

  import { Request } from 'bun';

  correct:

  const req = new Request('https://example.com');

  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`.

Quickstart

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.

import { Server, serve } from 'bun';

interface Env {
  PORT?: string;
}

const env = process.env as Env;
const port = env.PORT ? parseInt(env.PORT, 10) : 3000;

const server = Bun.serve({
  port: port,
  fetch(request: Request): Response {
    const url = new URL(request.url);
    if (url.pathname === '/') {
      return new Response('Hello from Bun! Visit /greet/:name');
    }
    if (url.pathname.startsWith('/greet/')) {
      const name = url.pathname.split('/').pop();
      return new Response(`Greetings, ${name}!`);
    }
    return new Response('404 Not Found', { status: 404 });
  },
  error(error: Error): Response {
    console.error('Server error:', error);
    return new Response('Internal Server Error', { status: 500 });
  },
});

console.log(`Bun server listening on http://localhost:${server.port}`);