Loaders

File type loaders and transpilation in Bun

Bun supports multiple file types through its loader system. Each loader determines how a file is processed and executed.

Built-in Loaders

Bun includes loaders for common file types:

JavaScript & TypeScript

• .js - JavaScript (js loader)
• .mjs - ES module JavaScript (js loader)
• .cjs - CommonJS JavaScript (js loader)
• .ts - TypeScript (ts loader)
• .mts - TypeScript ES module (ts loader)
• .cts - TypeScript CommonJS (ts loader)
• .jsx - JavaScript with JSX (jsx loader)
• .tsx - TypeScript with JSX (tsx loader)

Data Formats

• .json - JSON (json loader)
• .jsonc - JSON with comments (jsonc loader)
• .json5 - JSON5 (json5 loader)
• .toml - TOML (toml loader)
• .yaml, .yml - YAML (yaml loader)

Web Assets

• .css - CSS stylesheets (css loader)
• .html - HTML (html loader)
• .md - Markdown (md loader)

Binary & Special

• .wasm - WebAssembly (wasm loader)
• .sqlite, .db - SQLite databases (sqlite loader)
• .node - Native addons (napi loader)
• .txt - Plain text (text loader)

Encoding Loaders

• base64 - Base64 encoding
• dataurl - Data URL encoding
• file - Copy file to output directory

Automatic Loader Selection

Bun automatically selects the appropriate loader based on file extension:

Automatic loader selection

// TypeScript - uses 'ts' loader
import { add } from "./math.ts";

// JSX - uses 'jsx' loader  
import Button from "./Button.jsx";

// JSON - uses 'json' loader
import config from "./config.json";

// TOML - uses 'toml' loader
import data from "./data.toml";

// Text - uses 'text' loader
import content from "./README.md" with { type: "text" };

Loader Details

JavaScript Loaders (js, jsx)

Processes JavaScript files with optional JSX transformation:

JS loader features

// Modern JavaScript features
const data = await fetch("/api/data").then(r => r.json());

// Optional chaining & nullish coalescing
const name = user?.profile?.name ?? "Anonymous";

// Top-level await (ESM only)
await database.connect();

Features:

• No transpilation needed for modern JS
• JSX transformation when using .jsx extension
• Source map generation for debugging
• CommonJS/ESM interoperability

TypeScript Loaders (ts, tsx)

Strips TypeScript types and compiles to JavaScript:

TypeScript loader

// Type annotations removed at runtime
function greet(name: string): string {
  return `Hello, ${name}!`;
}

// Interfaces completely erased
interface User {
  id: number;
  name: string;
}

// Decorators supported (experimental & standard)
@sealed
class Handler {
  @log
  handle() { }
}

// Using declarations (explicit resource management)
using file = openFile("data.txt");

Features:

• Fast type stripping (no type checking)
• Decorator support (both legacy and standard)
• tsconfig.json path mapping
• Experimental features: decorators, using

JSON Loaders (json, jsonc, json5)

Parses JSON and returns a JavaScript object:

JSON loaders

// Standard JSON
import config from "./config.json";
console.log(config.apiKey);

// JSON with comments (jsonc)
import settings from "./settings.jsonc";

// JSON5 - extended syntax
import data from "./data.json5";
// Supports: trailing commas, comments, unquoted keys

Performance:

• Uses optimized JSON parser with SIMD
• Direct object construction (no eval)
• Type: json loaders return immutable objects

Text Loader

Returns file contents as a string:

Text loader

import readme from "./README.md" with { type: "text" };
import sql from "./query.sql" with { type: "text" };

console.log(readme); // "# My Project\n..."

Base64 & DataURL Loaders

Encode files as base64 or data URLs:

Encoding loaders

// Base64 encoding
import encoded from "./image.png" with { type: "base64" };
// Returns: string (base64 encoded)

// Data URL encoding  
import dataURL from "./image.png" with { type: "dataurl" };
// Returns: "data:image/png;base64,..."

Use cases:

• Embedding small assets in bundles
• Inline images in HTML/CSS
• Data URIs for web APIs

File Loader

Copies files to output directory and returns the path:

File loader

import path from "./logo.png" with { type: "file" };
// Returns: "/logo-a8b3c2d1.png"

Behavior:

• Copies file to public directory
• Generates content-hashed filename
• Returns public path to the file

WASM Loader

Loads WebAssembly modules:

WASM loader

import wasm from "./module.wasm";

// Synchronous instantiation
const { add } = wasm;
console.log(add(5, 3)); // 8

SQLite Loader

Loads SQLite databases:

SQLite loader

import db from "./data.sqlite";

// Query the database
const users = db.query("SELECT * FROM users").all();

Variants:

• sqlite - External database file
• sqlite_embedded - Embeds database in binary

NAPI Loader

Loads native Node.js addons:

NAPI loader

import addon from "./native.node";

addon.someNativeFunction();

Configuring Loaders

CLI Flags

Override the loader for specific extensions:

CLI loader configuration

# Treat .js files as JSX
bun --loader .js:jsx app.js

# Load .txt files as JavaScript
bun --loader .txt:js config.txt

# Multiple loaders
bun --loader .data:json --loader .config:toml app.ts

bunfig.toml

Persistent loader configuration:

bunfig.toml

[loader]
".js" = "jsx"          # Treat .js as JSX
".data" = "json"       # Parse .data as JSON  
".config" = "toml"     # Parse .config as TOML
".graphql" = "text"    # Load .graphql as text

Bun.build API

Programmatic loader configuration:

Bun.build loaders

await Bun.build({
  entrypoints: ["./app.ts"],
  loader: {
    ".svg": "text",
    ".png": "dataurl",
    ".woff2": "file",
  },
});

Import Attributes

Explicitly specify loader with import attributes:

Import attributes

// Force text loader for JSON file
import data from "./data.json" with { type: "text" };

// Load as JSON (default for .json)
import config from "./config.json" with { type: "json" };

// Load module as WebAssembly
import wasm from "./module.wasm" with { type: "wasm" };

Loader Implementation

Loaders are implemented in src/options.zig:

Loader enum (src/options.zig:617)

pub const Loader = enum(u8) {
    jsx = 0,
    js = 1,
    ts = 2,
    tsx = 3,
    css = 4,
    file = 5,
    json = 6,
    jsonc = 7,
    toml = 8,
    wasm = 9,
    napi = 10,
    base64 = 11,
    dataurl = 12,
    text = 13,
    bunsh = 14,
    sqlite = 15,
    sqlite_embedded = 16,
    html = 17,
    yaml = 18,
    json5 = 19,
    md = 20,
};

Custom Loaders (Plugins)

Extend Bun with custom loaders using plugins:

Custom loader plugin

import { plugin } from "bun";

plugin({
  name: "yaml-loader",
  setup(build) {
    build.onLoad({ filter: /\.yaml$/ }, async (args) => {
      const text = await Bun.file(args.path).text();
      const data = parseYAML(text);
      return {
        contents: `export default ${JSON.stringify(data)}`,
        loader: "js",
      };
    });
  },
});

Performance Considerations

Loaders execute during import, affecting startup time:

• Fast: js, ts, json - minimal overhead
• Medium: jsx, tsx, toml, yaml - requires parsing
• Slow: Large binary files (wasm, sqlite)

Optimization Tips

1. Lazy loading: Dynamically import large files
2. Caching: Bun caches transpiled files automatically
3. Bundling: Pre-bundle for production to avoid runtime transpilation

Lazy loading example

// Instead of:
import largeModule from "./large.ts";

// Use dynamic import:
const largeModule = await import("./large.ts");

Related

• TypeScript - TypeScript-specific configuration
• JSX - JSX transformation options
• Modules - Module resolution
• Bundling - Build-time loader configuration