Module Resolution

The JavaScript ecosystem is in a years-long transition from CommonJS modules to native ES modules (ESM), and different runtimes and build tools have historically disagreed on how import specifiers map to files on disk. Bun aims to provide a consistent and predictable module resolution system that works without configuration.

Syntax

Consider the following files.

import { hello } from "./hello";

hello();

Running index.ts prints "Hello world!".

$ bun index.ts
Hello world!

Here ./hello is a relative path with no extension. Extensioned imports are optional but supported. To resolve this import, Bun checks for the following files in order:

• ./hello.tsx
• ./hello.jsx
• ./hello.mts
• ./hello.ts
• ./hello.mjs
• ./hello.js
• ./hello.cts
• ./hello.cjs
• ./hello.json
• ./hello/index.tsx
• ./hello/index.jsx
• ./hello/index.mts
• ./hello/index.ts
• ./hello/index.mjs
• ./hello/index.js
• ./hello/index.cts
• ./hello/index.cjs
• ./hello/index.json

If the import path includes an extension, Bun checks for that exact file first. If no exact match exists, Bun falls back to trying the extension list above appended to the full path (so ./hello.world can resolve to ./hello.world.ts).

import { hello } from "./hello";
import { hello } from "./hello.ts"; // this works

There's one additional rule for TypeScript compatibility: if you import from "*.js" or from "*.jsx", Bun also checks for a matching *.ts or *.tsx file, and outside node_modules from "*.mjs" also matches *.mts. This follows the TypeScript compiler's file extension substitution, which lets source files reference each other by their compiled output paths. Note that unlike TypeScript, Bun doesn't rewrite .cjs to .cts.

import { hello } from "./hello";
import { hello } from "./hello.ts"; // this works
import { hello } from "./hello.js"; // this also works

Bun supports both ES modules (import/export syntax) and CommonJS modules (require()/module.exports). The following CommonJS version also works in Bun.

const { hello } = require("./hello");

hello();

That said, using CommonJS is discouraged in new projects.

Module systems

Bun has native support for CommonJS and ES modules. ES modules are the recommended module format for new projects, but CommonJS modules are still widely used in the Node.js ecosystem.

In Bun's JavaScript runtime, both ES modules and CommonJS modules can use require. If the target module is an ES module, require returns the module namespace object (equivalent to import * as). If the target module is a CommonJS module, require returns the module.exports object (as in Node.js).

Using require()

You can require() any file or package, even .ts or .mjs files.

const { foo } = require("./foo"); // extensions are optional
const { bar } = require("./bar.mjs");
const { baz } = require("./baz.tsx");

Using import

You can import any file or package, even .cjs files.

import { foo } from "./foo"; // extensions are optional
import bar from "./bar.ts";
import { stuff } from "./my-commonjs.cjs";

Using import and require() together

In Bun, you can use import or require in the same file—they both work, all the time.

import { stuff } from "./my-commonjs.cjs";
import Stuff from "./my-commonjs.cjs";

const myStuff = require("./my-commonjs.cjs");

Top level await

The only exception to this rule is top-level await. You can't require() a file that uses top-level await, since the require() function is inherently synchronous.

Fortunately, very few libraries use top-level await, so this is rarely a problem. But if you're using top-level await in your application code, make sure that file isn't require()'d from elsewhere in your application. Use import or dynamic import() instead.

Importing packages

Bun implements the Node.js module resolution algorithm, so you can import packages from node_modules with a bare specifier.

import { stuff } from "foo";

The full algorithm is specified in the Node.js documentation. Briefly: if you import from "foo", Bun scans up the file system for a node_modules directory containing the package foo.

NODE_PATH

Bun supports NODE_PATH for additional module resolution directories:

$ NODE_PATH=./packages bun run src/index.js

// packages/foo/index.js
export const hello = "world";

// src/index.js
import { hello } from "foo";

Multiple paths use the platform's delimiter (: on Unix, ; on Windows):

$ NODE_PATH=./packages:./lib bun run src/index.js  # Unix/macOS
$ NODE_PATH=./packages;./lib bun run src/index.js  # Windows

Once it finds the foo package, Bun reads its package.json to determine the package's entrypoint. Bun first reads the exports field and checks for the following conditions.

{
  "name": "foo",
  "exports": {
    "bun": "./index.js",
    "node-addons": "./index.js", // unless --no-addons was passed
    "node": "./index.js",
    "require": "./index.js", // if the importer uses require()
    "import": "./index.mjs", // if the importer uses import
    "default": "./index.js"
  }
}

Whichever of these conditions occurs first in the package.json determines the package's entrypoint.

Bun respects subpath "exports" and "imports".

{
  "name": "foo",
  "exports": {
    ".": "./index.js"
  }
}

Subpath imports and conditional imports work in conjunction with each other.

{
  "name": "foo",
  "exports": {
    ".": {
      "import": "./index.mjs",
      "require": "./index.js"
    }
  }
}

As in Node.js, specifying any subpath in the "exports" map prevents other subpaths from being importable; you can only import files that are explicitly exported. Given the preceding package.json:

import stuff from "foo"; // this works
import stuff from "foo/index.mjs"; // this doesn't

If exports is not defined, Bun falls back to the legacy top-level entrypoint fields. At runtime Bun prefers "main" (or an implicit index.* file) when present, and uses "module" otherwise.

{
  "name": "foo",
  "module": "./index.js",
  "main": "./index.js"
}

Custom conditions

The --conditions flag specifies the conditions to use when resolving packages from package.json "exports".

Both bun build and Bun's runtime support this flag.

# Use it with bun build:
$ bun build --conditions="react-server" --target=bun ./app/foo/route.js

# Use it with bun's runtime:
$ bun --conditions="react-server" ./app/foo/route.js

You can also use conditions programmatically with Bun.build:

await Bun.build({
  conditions: ["react-server"],
  target: "bun",
  entryPoints: ["./app/foo/route.js"],
});

Path re-mapping

Bun supports import path re-mapping through TypeScript's compilerOptions.paths in tsconfig.json, which works well with editors. If you aren't a TypeScript user, use a jsconfig.json in your project root for the same behavior.

{
  "compilerOptions": {
    "paths": {
      "config": ["./config.ts"], // map specifier to file
      "components/*": ["components/*"] // wildcard matching
    }
  }
}

Bun also supports Node.js-style subpath imports in package.json, where mapped paths must start with #. TypeScript and editors resolve these too, and you can use both mechanisms together.

{
  "imports": {
    "#config": "./config.ts", // map specifier to file
    "#components/*": "./components/*" // wildcard matching
  }
}

import.meta

The import.meta object exposes information about the current module. It's part of the JavaScript language, but its contents are not standardized: each "host" (browser or runtime) implements its own properties on the import.meta object.

Bun implements the following properties.

import.meta.dir; // => "/path/to/project"
import.meta.file; // => "file.ts"
import.meta.path; // => "/path/to/project/file.ts"
import.meta.url; // => "file:///path/to/project/file.ts"

import.meta.main; // `true` if this file is directly executed by `bun run`
// `false` otherwise

import.meta.resolve("zod"); // => "file:///path/to/project/node_modules/zod/index.js"