Module loaders via Bun.plugin
Bun provides Bun.plugin() for creating custom module loaders through the bundler plugin system.
bun apis/module loaders
36 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Import attribute type for explicit loader specification
To specify a loader explicitly, use the `type` import attribute. For static imports, use `import my_toml from "./my_file" with { type: "toml" };`. For dynamic imports, use `await import("./my_file", { with: { type: "toml" } })`.
js loader for JavaScript
The `js` loader handles JavaScript. It is the default for .cjs and .mjs files. Bun parses the code and applies default transforms like dead-code elimination and tree shaking. Bun does not down-convert syntax.
jsx loader for JavaScript and JSX
The `jsx` loader handles JavaScript with JSX syntax. It is the default for .js and .jsx files. Same as the js loader, but JSX syntax is supported. By default, JSX is down-converted to plain JavaScript; the details depend on the jsx* compiler options in tsconfig.json, following TypeScript documentation on JSX.
ts loader for TypeScript
The `ts` loader handles TypeScript. It is the default for .ts, .mts, and .cts files. Bun strips out all TypeScript syntax, then behaves identically to the js loader. Bun does not perform typechecking.
tsx loader for TypeScript and JSX
The `tsx` loader handles TypeScript with JSX syntax. It is the default for .tsx files. Bun transpiles both TypeScript and JSX to vanilla JavaScript.
json loader for JSON files
The `json` loader handles JSON files, default for .json. JSON files can be directly imported as `import pkg from "./package.json"; pkg.name;`. During bundling, parsed JSON is inlined as a JavaScript object. If a .json file is passed as an entrypoint to the bundler, it is converted to a .js module that export default's the parsed object.
jsonc loader for JSON with Comments
The `jsonc` loader handles JSON with Comments files, default for .jsonc. JSONC files can be directly imported. Bun parses them, stripping out comments and trailing commas. During bundling, parsed JSONC is inlined as a JavaScript object. Bun automatically uses the jsonc loader for tsconfig.json, jsconfig.json, package.json, and bun.lock files.
toml loader for TOML files
The `toml` loader handles TOML files, default for .toml. TOML files can be directly imported as `import config from "./bunfig.toml";`. Bun parses them with its fast native TOML parser. During bundling, parsed TOML is inlined as a JavaScript object. If a .toml file is passed as an entrypoint, it is converted to a .js module that export default's the parsed object.
yaml loader for YAML files
The `yaml` loader handles YAML files, default for .yaml and .yml. YAML files can be directly imported as `import config from "./config.yaml";`. Bun parses them with its fast native YAML parser. During bundling, parsed YAML is inlined as a JavaScript object. If a .yaml or .yml file is passed as an entrypoint, it is converted to a .js module that export default's the parsed object.
json5 loader for JSON5 files
The `json5` loader handles JSON5 files, default for .json5. JSON5 is a superset of JSON that adds comments, trailing commas, unquoted keys, single-quoted strings, and more. JSON5 files can be directly imported as `import config from "./config.json5";`. During bundling, parsed JSON5 is inlined as a JavaScript object. If a .json5 file is passed as an entrypoint, it is converted to a .js module that export default's the parsed object.
xml loader for XML files
The `xml` loader handles XML files, default for .xml. XML files can be directly imported as `import doc from "./config.xml";`. Bun parses them with its native XML 1.0 parser into the compact object shape of Bun.XML.parse: one key for the root element, "@name" keys for attributes, arrays for repeated child elements, "#text" for text next to attributes or children, and every value a string. During bundling, parsed XML is inlined as a JavaScript object. If a .xml file is passed as an entrypoint, it is converted to a .js module that export default's the parsed object.
text loader for text files
The `text` loader handles text files, default for .txt. Text files can be directly imported as `import contents from "./file.txt";`. The file is read and returned as a string. When referenced during a build, contents are inlined into the bundle as a string. If a .txt file is passed as an entrypoint, it is converted to a .js module that export default's the file contents.
napi loader for native addons
The `napi` loader handles native addons, default for .node files. In the runtime, native addons can be directly imported as `import addon from "./addon.node";`. In the bundler, .node files are handled using the file loader.
html loader for HTML files
The `html` loader processes HTML files and bundles any referenced assets. It bundles and hashes referenced JavaScript files (<script src="...">), bundles and hashes referenced CSS files (<link rel="stylesheet" href="...">), hashes referenced images (<img src="...">), and preserves external URLs by default (anything starting with http:// or https://). The loader uses lol-html to extract script and link tags as entrypoints, and other assets as external.
HTML loader selectors for asset extraction
The html loader extracts assets using these selectors: audio[src], img[src], img[srcset], link[as='font'][href], link[type^='font/'][href], link[as='image'][href], link[as='style'][href], link[as='video'][href], link[as='audio'][href], link[as='worker'][href], link[rel='icon'][href], link[rel='apple-touch-icon'][href], link[rel='manifest'][href], link[rel='stylesheet'][href], script[src], source[src], source[srcset], video[poster], video[src].
HTML loader behavior in different contexts
The html loader behaves differently depending on context: (1) Static Build - When running `bun build ./index.html`, Bun produces a static site with all assets bundled and hashed. (2) Runtime - When running `bun run server.ts` where server.ts imports an HTML file, Bun bundles assets on-the-fly during development, enabling features like hot module replacement. (3) Full-stack Build - When running `bun build --target=bun server.ts` where server.ts imports an HTML file, the import resolves to a manifest object that Bun.serve uses to efficiently serve pre-bundled assets in production.
css loader for CSS files
The `css` loader handles CSS files, default for .css. CSS files can be directly imported as `import "./styles.css";`. The import returns no value; it is only used for its side effects. This is primarily useful for full-stack applications where CSS is bundled alongside HTML.
file loader for unrecognized file types
The `file` loader is the default for all unrecognized file types. It resolves the import as a path/URL to the imported file and is commonly used for referencing media or font assets. In the runtime, Bun checks that the file exists and resolves the import to its absolute path on disk. In the bundler, the file is copied into outdir as-is, and the import resolves to a relative path pointing to the copied file. If publicPath is set, the import uses its value as a prefix: "" (default) resolves to ./logo.svg, "/assets/" resolves to /assets/logo.svg, "https://cdn.example.com/" resolves to https://cdn.example.com/logo.svg. The location and file name of the copied file is determined by the value of naming.asset.
TypeScript type declarations for import errors
To fix TypeScript import errors like "Cannot find module './logo.svg' or its corresponding type declarations", create a *.d.ts file anywhere in the project with the contents: `declare module "*.svg" { const content: string; export default content; }`. This tells TypeScript that any default imports from .svg should be treated as a string.
File types supported by Bun bundler and runtime
The Bun bundler and runtime support the following file types: .js, .cjs, .mjs, .mts, .cts, .ts, .tsx, .jsx, .css, .json, .jsonc, .json5, .toml, .yaml, .yml, .xml, .txt, .wasm, .node, .html, .sh. Bun uses the file extension to pick the built-in loader that parses the file.
Require JSON5 files in CommonJS
JSON5 files can be required in CommonJS using const config = require('./config.json5'). Destructuring also works: const { database, features } = require('./config.json5').
Hot reloading for JSON5 files
When running an application with bun --hot, Bun automatically reloads JSON5 files when they change, including hot reloading and watch mode support.
Dynamic imports of JSON5 files
JSON5 files can be dynamically imported using const { default: config } = await import('./config.json5').
Import JSON5 files as ES modules
JSON5 files can be imported as ES modules using default import or named imports. Default import: import config from './config.json5'. Named imports (destructuring top-level properties): import { database, features } from './config.json5'.
Import TOML files as ES modules
TOML files can be imported directly as ES modules in Bun. When importing a TOML file, Bun parses the TOML and exposes it as both a default export and named exports. Top-level TOML tables can be destructured as named imports. The default export contains the entire parsed TOML object. For example, import config from './config.toml' imports the whole config, and import { database, redis } from './config.toml' imports specific top-level tables.
Require TOML files in CommonJS
TOML files can be required in CommonJS using require(). For example, const config = require('./config.toml') loads the TOML file as a JavaScript object. Destructuring also works in CommonJS, such as const { database, redis } = require('./config.toml').
Import attribute for TOML files
Any file can be loaded as TOML using an import attribute with type 'toml'. For example: import myConfig from './my.config' with { type: 'toml' } will parse the file as TOML regardless of its extension.
Import YAML files as ES modules in Bun
YAML files can be imported directly as ES modules in Bun. Both default import and named imports are supported. When a YAML file is imported, top-level YAML properties become available as named exports in addition to the full object as the default export.
Require YAML files with CommonJS in Bun
YAML files can be required with CommonJS using require() in Bun. Destructuring is also supported, extracting top-level properties directly.
Hot reload YAML files with bun --hot
When running an application with 'bun --hot', Bun automatically detects changes to YAML files and reloads them without closing connections. This allows toggling feature flags and adjusting settings during development without restarting.
Dynamically import YAML files in Bun
YAML files can be dynamically imported using dynamic import() expressions. This allows loading configuration based on runtime conditions, such as environment variables or user IDs.
Import YAML with default and named exports example
// config.yaml: // database: // host: localhost // port: 5432 // redis: // host: localhost // port: 6379 import config, { database, redis } from "./config.yaml"; console.log(config.database.host); // "localhost" console.log(database.port); // 5432 console.log(redis.port); // 6379
Require YAML files with CommonJS example
const config = require("./config.yaml"); console.log(config.database.name); // "myapp" // Destructuring also works const { database, redis } = require("./config.yaml"); console.log(database.port); // 5432
Hot reload YAML configuration example
// config.yaml: // server: // port: 3000 // host: localhost // features: // debug: true import { server, features } from "./config.yaml"; console.log(`Starting server on ${server.host}:${server.port}`); if (features.debug) { console.log("Debug mode enabled"); } Bun.serve({ port: server.port, hostname: server.host, fetch(req) { if (features.verbose) { console.log(`${req.method} ${req.url}`); } return new Response("Hello World"); }, }); // Run with: bun --hot server.ts
Dynamic import YAML files example
// Load configuration based on environment const env = process.env.NODE_ENV || "development"; const { default: config } = await import(`./configs/${env}.yaml`); // Load user-specific settings async function loadUserSettings(userId: string) { try { const settings = await import(`./users/${userId}/settings.yaml`); return settings.default; } catch { const { default: defaults } = await import("./users/default-settings.yaml"); return defaults; } }