Loaders

The Bun bundler implements a set of default loaders out of the box. As a rule of thumb, the bundler and the runtime both support the same set of file types out of the box.

.js .cjs .mjs .mts .cts .ts .tsx .jsx .toml .json .txt .wasm .node

Bun uses the file extension to determine which built-in loader should be used to parse the file.

json

import pkg from "./package.json";
pkg.name; // => "my-package"

If a .json file is passed as an entrypoint to the bundler, it will be converted to a .js module that export defaults the parsed object.

{
  "name": "John Doe",
  "age": 35,
  "email": "johndoe@example.com"
}

export default {
  name: "John Doe",
  age: 35,
  email: "johndoe@example.com"
}

toml

import config from "./bunfig.toml";
config.logLevel; // => "debug"

If a .toml file is passed as an entrypoint, it will be converted to a .js module that export defaults the parsed object.

text

The contents of the text file are read and inlined into the bundle as a string. Text files can be directly imported. The file is read and returned as a string.

import contents from "./file.txt";
console.log(contents); // => "Hello, world!"

// To import an html file as text
// The "type' attribute can be used to override the default loader.
import html from "./index.html" with { type: "text" };

sqlite

with { "type": "sqlite" } import attribute

In the runtime and bundler, SQLite databases can be directly imported. This will load the database using bun:sqlite.

import db from "./my.db" with { type: "sqlite" };

// embed the database into the bundle
import db from "./my.db" with { type: "sqlite", embed: "true" };

file

Default for all unrecognized file types.

The file loader resolves the import as a path/URL to the imported file. It’s commonly used for referencing media or font assets.

import logo from "./logo.svg";
console.log(logo);

In the runtime, Bun checks that the logo.svg file exists and converts it to an absolute path to the location of logo.svg on disk.

bun run logo.ts
/path/to/project/logo.svg

In the bundler, things are slightly different. The file is copied into outdir as-is, and the import is resolved as a relative path pointing to the copied file.

var logo = "./logo.svg";
console.log(logo);

If a value is specified for publicPath, the import will use value as a prefix to construct an absolute path/URL.