Skip to content

Commit b1f0f38

Browse files
Claude Botclaude
andcommitted
Improve YAML documentation with Bun.YAML.stringify and TypeScript typing
- Add Bun.YAML.stringify() documentation with examples using (null, 2) for spacing - Document space parameter: 2 for readable format, 0 for condensed inline notation - Add TypeScript section in Module Import explaining manual .d.ts requirement - Clarify that unlike JSON, TypeScript doesn't automatically type YAML imports 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
1 parent 6f8138b commit b1f0f38

File tree

1 file changed

+108
-0
lines changed

1 file changed

+108
-0
lines changed

docs/runtime/yaml.mdx

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,47 @@ Bun's YAML parser currently passes over 90% of the official YAML test suite. Whi
2323

2424
Parse a YAML string into a JavaScript object.
2525

26+
### `Bun.YAML.stringify()`
27+
28+
Convert a JavaScript object into a YAML string.
29+
30+
```ts
31+
import { YAML } from "bun";
32+
33+
const obj = {
34+
name: "John Doe",
35+
age: 30,
36+
37+
hobbies: ["reading", "coding", "hiking"]
38+
};
39+
40+
const yaml = Bun.YAML.stringify(obj, null, 2);
41+
console.log(yaml);
42+
// name: John Doe
43+
// age: 30
44+
45+
// hobbies:
46+
// - reading
47+
// - coding
48+
// - hiking
49+
```
50+
51+
The signature is similar to `JSON.stringify()`:
52+
53+
```ts
54+
Bun.YAML.stringify(value, replacer?, space?)
55+
```
56+
57+
The `space` parameter controls indentation (default: 2). With `space: 0`, YAML uses inline notation making output more condensed than JSON:
58+
59+
```ts
60+
const compact = Bun.YAML.stringify(obj, null, 0);
61+
// name: John Doe
62+
// age: 30
63+
64+
// hobbies: [reading, coding, hiking]
65+
```
66+
2667
```ts
2768
import { YAML } from "bun";
2869
const text = `
@@ -193,6 +234,30 @@ const { database, redis } = require("./config.yaml");
193234
console.log(database.port); // 5432
194235
```
195236
237+
### TypeScript
238+
239+
Unlike JSON files, TypeScript doesn't automatically type YAML imports. Add type definitions by creating a `.d.ts` file with the same name as your YAML file:
240+
241+
```ts config.yaml.d.ts icon="/icons/typescript.svg"
242+
const contents: {
243+
database: {
244+
host: string;
245+
port: number;
246+
name: string;
247+
};
248+
server: {
249+
port: number;
250+
timeout: number;
251+
};
252+
features: {
253+
auth: boolean;
254+
rateLimit: boolean;
255+
};
256+
};
257+
258+
export = contents;
259+
```
260+
196261
---
197262
198263
## Hot Reloading with YAML
@@ -435,6 +500,49 @@ if (parseConfig(migrations).autoRun === "true") {
435500
}
436501
```
437502

503+
### Generating YAML Files
504+
505+
You can use `Bun.YAML.stringify()` to programmatically create YAML configuration files:
506+
507+
```ts generate-config.ts icon="/icons/typescript.svg"
508+
import { YAML } from "bun";
509+
510+
const config = {
511+
server: {
512+
port: 3000,
513+
host: "localhost",
514+
},
515+
database: {
516+
type: "postgres",
517+
host: "localhost",
518+
port: 5432,
519+
name: "myapp",
520+
pool: {
521+
min: 2,
522+
max: 10,
523+
},
524+
},
525+
features: {
526+
auth: true,
527+
rateLimit: true,
528+
analytics: false,
529+
},
530+
};
531+
532+
// Generate readable YAML with 2-space indentation
533+
const yaml = Bun.YAML.stringify(config, null, 2);
534+
await Bun.write("config.yaml", yaml);
535+
536+
console.log("Generated config.yaml:");
537+
console.log(yaml);
538+
```
539+
540+
This is particularly useful for:
541+
- Generating configuration files from templates
542+
- Exporting settings from your application
543+
- Creating config files for CI/CD pipelines
544+
- Building development tools that output YAML
545+
438546
### Bundler Integration
439547

440548
When you import YAML files in your application and bundle it with Bun, the YAML is parsed at build time and included as a JavaScript module:

0 commit comments

Comments
 (0)