Module Resolution

Module resolution in JavaScript is a complex topic.

The ecosystem is currently in the midst of a years-long transition from CommonJS modules to native ES modules. TypeScript enforces its own set of rules around import extensions that aren't compatible with ESM. Different build tools support path re-mapping via disparate non-compatible mechanisms.

Bun aims to provide a consistent and predictable module resolution system that just works. Unfortunately it's still quite complex.

Syntax

Consider the following files.

import { hello } from "./hello";

hello();

When we run index.ts, it prints "Hello world!".

$ bun index.ts
Hello world!

In this case, we are importing from ./hello, a relative path with no extension. Extensioned imports are optional but supported. To resolve this import, Bun will check for the following files in order:

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

Import paths can optionally include extensions. If an extension is present, Bun will only check for a file with that exact extension.

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

If you import from "*.js{x}", Bun will additionally check for a matching *.ts{x} file, to be compatible with TypeScript's ES module support.

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 would also work 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, require can be used by both ES Modules and CommonJS modules. 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 being require() from elsewhere in your application. Instead, you should use import or dynamic import().

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 specification of this algorithm are officially documented in the Node.js documentation; we won't rehash it here. 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 the package.json to determine how the package should be imported. 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": "./index.js",
    "require": "./index.js", // if importer is CommonJS
    "import": "./index.mjs", // if importer is ES module
    "default": "./index.js"
  }
}

Whichever one of these conditions occurs first in the package.json is used to determine 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 will prevent other subpaths from being importable; you can only import files that are explicitly exported. Given the package.json above:

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

If exports is not defined, Bun falls back to "module" (ESM imports only) then "main".

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

Custom conditions

The --conditions flag allows you to specify a list of conditions to use when resolving packages from package.json "exports".

This flag is supported in both bun build and Bun's runtime.

# 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, you can achieve the same behavior by using a jsconfig.json in your project root.

{
  "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 #. This approach doesn’t work as well with editors, but both options can be used together.

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

import.meta

The import.meta object is a way for a module to access information about itself. It's part of the JavaScript language, but its contents are not standardized. Each "host" (browser, runtime, etc) is free to implement any properties it wishes 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"