TOML

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

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

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

Runtime API

`Bun.TOML.parse()`

Parse a TOML string into a JavaScript object.

import { TOML } from "bun";
const text = `
name = "my-app"
version = "1.0.0"
debug = true

[database]
host = "localhost"
port = 5432

[features]
tags = ["web", "api"]
`;

const data = TOML.parse(text);
console.log(data);
// {
//   name: "my-app",
//   version: "1.0.0",
//   debug: true,
//   database: { host: "localhost", port: 5432 },
//   features: { tags: ["web", "api"] }
// }

Supported TOML Features

Bun's TOML parser implements the full TOML v1.1.0 specification and passes the complete official toml-test conformance suite.

Strings: basic ("...") and literal ('...'), including multi-line, with all escapes (\uHHHH, \UHHHHHHHH, and TOML 1.1's \xHH and \e)
Integers: decimal, hex (0x), octal (0o), and binary (0b). Integers that cannot be represented losslessly as a JavaScript number — outside ±(2^53 - 1) — throw
Floats: including inf and nan
Booleans: true and false
Date/times: offset date-time, local date-time, local date, and local time, returned as strings of their source text
Arrays: including mixed types and nested arrays
Tables: standard ([table]) and inline ({ key = "value" }), including TOML 1.1 multi-line inline tables
Array of tables: [[array]]
Dotted keys: a.b.c = "value"
Comments: using #

const data = Bun.TOML.parse(`
# Application config
title = "My App"

[owner]
name = "John Doe"

[database]
enabled = true
ports = [8000, 8001, 8002]
connection_max = 5000

[servers.alpha]
ip = "10.0.0.1"
role = "frontend"

[servers.beta]
ip = "10.0.0.2"
role = "backend"
`);

Error Handling

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

try {
  Bun.TOML.parse("invalid = = =");
} catch (error) {
  console.error("Failed to parse TOML:", error.message);
  // Failed to parse TOML: TOML Parse error: Expected a value but found '='
}

`Bun.TOML.stringify()`

Serialize a JavaScript object to a TOML document. Scalar keys come first, followed by [table] and [[array-of-tables]] sections:

Bun.TOML.stringify({
  name: "app",
  server: { host: "localhost", port: 8080 },
  points: [{ x: 1 }, { x: 2 }],
});
// name = "app"
//
// [server]
// host = "localhost"
// port = 8080
//
// [[points]]
// x = 1
//
// [[points]]
// x = 2

The top-level value must be an object — a TOML document is a table. Date values become TOML offset date-times. Because TOML cannot represent them, null values, BigInt, and circular structures throw; undefined, function, and symbol properties are skipped (inside arrays they throw, since TOML arrays cannot have holes).

Module Import

ES Modules

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

config.toml

[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.toml";

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

Named Imports

You can destructure top-level TOML tables as named imports:

app.ts

import { database, redis, features } from "./config.toml";

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.toml";

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

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

Import Attributes

Use an import attribute to load any file as TOML:

app.ts

import myConfig from "./my.config" with { type: "toml" };

CommonJS

You can also require TOML files in CommonJS:

app.ts

const config = require("./config.toml");
console.log(config.database.name); // "myapp"

// Destructuring also works
const { database, redis } = require("./config.toml");
console.log(database.port); // 5432

Hot Reloading with TOML

When you run your application with bun --hot, Bun detects changes to TOML files and reloads them without restarting:

config.toml

[server]
port = 3000
host = "localhost"

[features]
debug = true
verbose = false

server.ts

import { server, features } from "./config.toml";

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

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

Bundler Integration

When you bundle with Bun, the bundler parses imported TOML at build time and includes it as a JavaScript module:

terminal

$ bun build app.ts --outdir=dist

This means:

Zero runtime TOML parsing overhead in production
Smaller bundle sizes
Tree shaking of unused properties (named imports)

Dynamic Imports

You can also dynamically import TOML files:

const config = await import("./config.toml");

On this page