> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/zhcndoc/bun/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

<AccordionGroup>
  <Accordion title="JavaScript & TypeScript" icon="js" defaultOpen>
    * **`.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)
  </Accordion>

  <Accordion title="Data Formats" icon="database">
    * **`.json`** - JSON (json loader)
    * **`.jsonc`** - JSON with comments (jsonc loader)
    * **`.json5`** - JSON5 (json5 loader)
    * **`.toml`** - TOML (toml loader)
    * **`.yaml`**, **`.yml`** - YAML (yaml loader)
  </Accordion>

  <Accordion title="Web Assets" icon="globe">
    * **`.css`** - CSS stylesheets (css loader)
    * **`.html`** - HTML (html loader)
    * **`.md`** - Markdown (md loader)
  </Accordion>

  <Accordion title="Binary & Special" icon="file-binary">
    * **`.wasm`** - WebAssembly (wasm loader)
    * **`.sqlite`**, **`.db`** - SQLite databases (sqlite loader)
    * **`.node`** - Native addons (napi loader)
    * **`.txt`** - Plain text (text loader)
  </Accordion>

  <Accordion title="Encoding Loaders" icon="code">
    * **base64** - Base64 encoding
    * **dataurl** - Data URL encoding
    * **file** - Copy file to output directory
  </Accordion>
</AccordionGroup>

## Automatic Loader Selection

Bun automatically selects the appropriate loader based on file extension:

```typescript Automatic loader selection theme={null}
// 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:

```javascript JS loader features theme={null}
// 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 TypeScript loader theme={null}
// 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:

```typescript JSON loaders theme={null}
// 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:

```typescript Text loader theme={null}
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:

```typescript Encoding loaders theme={null}
// 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:

```typescript File loader theme={null}
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:

```typescript WASM loader theme={null}
import wasm from "./module.wasm";

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

### SQLite Loader

Loads SQLite databases:

```typescript SQLite loader theme={null}
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:

```typescript NAPI loader theme={null}
import addon from "./native.node";

addon.someNativeFunction();
```

## Configuring Loaders

### CLI Flags

Override the loader for specific extensions:

```bash CLI loader configuration theme={null}
# 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:

```toml bunfig.toml theme={null}
[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:

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

## Import Attributes

Explicitly specify loader with import attributes:

```typescript Import attributes theme={null}
// 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`:

```zig Loader enum (src/options.zig:617) theme={null}
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:

```typescript Custom loader plugin theme={null}
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

<Note>
  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)
</Note>

### 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

```typescript Lazy loading example theme={null}
// Instead of:
import largeModule from "./large.ts";

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

## Related

* [TypeScript](/runtime/typescript) - TypeScript-specific configuration
* [JSX](/runtime/jsx) - JSX transformation options
* [Modules](/runtime/modules) - Module resolution
* [Bundling](/bundler) - Build-time loader configuration