YAML

Use Bun's built-in support for YAML files through both runtime APIs and bundler integration

In Bun, YAML is a first-class citizen alongside JSON and TOML. You can:

  • Parse YAML strings with Bun.YAML.parse
  • import & require YAML files as modules at runtime (including hot reloading & watch mode support)
  • import & require YAML files in frontend apps with Bun's bundler

Conformance#

Bun's YAML parser, written in Rust, passes the official YAML test suite and covers the vast majority of real-world use cases.

Runtime API#

Bun.YAML.parse()#

Parse a YAML string into a JavaScript object.

import { YAML } from "bun";
const text = `
name: John Doe
age: 30
email: john@example.com
hobbies:
  - reading
  - coding
  - hiking
`;

const data = YAML.parse(text);
console.log(data);
// {
//   name: "John Doe",
//   age: 30,
//   email: "john@example.com",
//   hobbies: ["reading", "coding", "hiking"]
// }

Multi-document YAML#

When parsing YAML with multiple documents (separated by ---), Bun.YAML.parse() returns an array:

const multiDoc = `
---
name: Document 1
---
name: Document 2
---
name: Document 3
`;

const docs = Bun.YAML.parse(multiDoc);
console.log(docs);
// [
//   { name: "Document 1" },
//   { name: "Document 2" },
//   { name: "Document 3" }
// ]

Supported YAML Features#

Bun's YAML parser supports the YAML 1.2 specification, including:

  • Scalars: strings, numbers, booleans, null values
  • Collections: sequences (arrays) and mappings (objects)
  • Anchors and Aliases: reusable nodes with & and *. Aliased collections share identity. An alias may refer to a collection that contains it, so Bun.YAML.parse can return cyclic objects. YAML imported as a module cannot be cyclic.
  • Tags: type hints like !!str, !!int, !!float, !!bool, !!null
  • Multi-line strings: literal (|) and folded (>) scalars
  • Comments: using #
  • Directives: %YAML and %TAG
const yaml = `
# Employee record
employee: &emp
  name: Jane Smith
  department: Engineering
  skills:
    - JavaScript
    - TypeScript
    - React

manager: *emp  # Reference to employee

config: !!str 123  # Explicit string type

description: |
  This is a multi-line
  literal string that preserves
  line breaks and spacing.

summary: >
  This is a folded string
  that joins lines with spaces
  unless there are blank lines.
`;

const data = Bun.YAML.parse(yaml);

Error Handling#

Bun.YAML.parse() throws a SyntaxError if the YAML is invalid:

try {
  Bun.YAML.parse("invalid: yaml: content:");
} catch (error) {
  console.error("Failed to parse YAML:", error.message);
}

Module Import#

ES Modules#

Import YAML files directly as ES modules. Bun parses the content and exposes it as both default and named exports:

config.yaml
database:
  host: localhost
  port: 5432
  name: myapp

redis:
  host: localhost
  port: 6379

features:
  auth: true
  rateLimit: true
  analytics: false

Default Import#

app.ts
import config from "./config.yaml";

console.log(config.database.host); // "localhost"
console.log(config.redis.port); // 6379

Named Imports#

Top-level YAML properties are available as named imports:

app.ts
import { database, redis, features } from "./config.yaml";

console.log(database.host); // "localhost"
console.log(redis.port); // 6379
console.log(features.auth); // true

Or combine both:

app.ts
import config, { database, features } from "./config.yaml";

// Use the full config object
console.log(config);

// Or use specific parts
if (features.rateLimit) {
  setupRateLimiting(database);
}

CommonJS#

You can also require YAML files in CommonJS:

app.ts
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 Reloading with YAML#

When you run your application with bun --hot, Bun detects changes to YAML files and reloads them without closing connections.

Configuration Hot Reloading#

config.yaml
server:
  port: 3000
  host: localhost

features:
  debug: true
  verbose: false
server.ts
import { server, features } from "./config.yaml";

console.log(`Starting server on ${server.host}:${server.port}`);

if (features.debug) {
  console.log("Debug mode enabled");
}

// Your server code here
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 hot reloading:

terminal
bun --hot server.ts