From 85770596ca723a58596435a1785457ab85673d83 Mon Sep 17 00:00:00 2001 From: Jarred Sumner Date: Sat, 23 Aug 2025 18:54:50 -0700 Subject: [PATCH] Add some missing docs for yaml support --- docs/bundler/loaders.md | 51 +++++++++++++++++++- docs/guides/runtime/import-yaml.md | 76 ++++++++++++++++++++++++++++++ docs/runtime/bun-apis.md | 2 +- docs/runtime/bunfig.md | 1 + docs/runtime/index.md | 7 ++- docs/runtime/loaders.md | 7 ++- 6 files changed, 138 insertions(+), 6 deletions(-) create mode 100644 docs/guides/runtime/import-yaml.md diff --git a/docs/bundler/loaders.md b/docs/bundler/loaders.md index 5ad227b978..c3e70535cd 100644 --- a/docs/bundler/loaders.md +++ b/docs/bundler/loaders.md @@ -1,6 +1,6 @@ The Bun bundler implements a set of default loaders out of the box. As a rule of thumb, the bundler and the runtime both support the same set of file types out of the box. -`.js` `.cjs` `.mjs` `.mts` `.cts` `.ts` `.tsx` `.jsx` `.toml` `.json` `.txt` `.wasm` `.node` `.html` +`.js` `.cjs` `.mjs` `.mts` `.cts` `.ts` `.tsx` `.jsx` `.toml` `.json` `.yaml` `.yml` `.txt` `.wasm` `.node` `.html` Bun uses the file extension to determine which built-in _loader_ should be used to parse the file. Every loader has a name, such as `js`, `tsx`, or `json`. These names are used when building [plugins](https://bun.com/docs/bundler/plugins) that extend Bun with custom loaders. @@ -121,6 +121,55 @@ export default { {% /codetabs %} +### `yaml` + +**YAML loader**. Default for `.yaml` and `.yml`. + +YAML files can be directly imported. Bun will parse them with its fast native YAML parser. + +```ts +import config from "./config.yaml"; +config.database.host; // => "localhost" + +// via import attribute: +// import myCustomYAML from './my.config' with {type: "yaml"}; +``` + +During bundling, the parsed YAML is inlined into the bundle as a JavaScript object. + +```ts +var config = { + database: { + host: "localhost", + port: 5432 + }, + // ...other fields +}; +config.database.host; +``` + +If a `.yaml` or `.yml` file is passed as an entrypoint, it will be converted to a `.js` module that `export default`s the parsed object. + +{% codetabs %} + +```yaml#Input +name: John Doe +age: 35 +email: johndoe@example.com +``` + +```js#Output +export default { + name: "John Doe", + age: 35, + email: "johndoe@example.com" +} +``` + +{% /codetabs %} + +For more details on YAML support including the runtime API `Bun.YAML.parse()`, see the [YAML API documentation](/docs/api/yaml). + ### `text` **Text loader**. Default for `.txt`. diff --git a/docs/guides/runtime/import-yaml.md b/docs/guides/runtime/import-yaml.md new file mode 100644 index 0000000000..791d6c96a2 --- /dev/null +++ b/docs/guides/runtime/import-yaml.md @@ -0,0 +1,76 @@ +--- +name: Import a YAML file +--- + +Bun natively supports `.yaml` and `.yml` imports. + +```yaml#config.yaml +database: + host: localhost + port: 5432 + name: myapp + +server: + port: 3000 + timeout: 30 + +features: + auth: true + rateLimit: true +``` + +--- + +Import the file like any other source file. + +```ts +import config from "./config.yaml"; + +config.database.host; // => "localhost" +config.server.port; // => 3000 +config.features.auth; // => true +``` + +--- + +You can also use named imports to destructure top-level properties: + +```ts +import { database, server, features } from "./config.yaml"; + +console.log(database.name); // => "myapp" +console.log(server.timeout); // => 30 +console.log(features.rateLimit); // => true +``` + +--- + +Bun also supports [Import Attributes](https://github.com/tc39/proposal-import-attributes) syntax: + +```ts +import config from "./config.yaml" with { type: "yaml" }; + +config.database.port; // => 5432 +``` + +--- + +For parsing YAML strings at runtime, use `Bun.YAML.parse()`: + +```ts +const yamlString = ` +name: John Doe +age: 30 +hobbies: + - reading + - coding +`; + +const data = Bun.YAML.parse(yamlString); +console.log(data.name); // => "John Doe" +console.log(data.hobbies); // => ["reading", "coding"] +``` + +--- + +See [Docs > API > YAML](https://bun.com/docs/api/yaml) for complete documentation on YAML support in Bun. \ No newline at end of file diff --git a/docs/runtime/bun-apis.md b/docs/runtime/bun-apis.md index 6b39bef010..ce768bb092 100644 --- a/docs/runtime/bun-apis.md +++ b/docs/runtime/bun-apis.md @@ -195,7 +195,7 @@ Click the link in the right column to jump to the associated documentation. --- - Parsing & Formatting -- [`Bun.semver`](https://bun.com/docs/api/semver), `Bun.TOML.parse`, [`Bun.color`](https://bun.com/docs/api/color) +- [`Bun.semver`](https://bun.com/docs/api/semver), `Bun.TOML.parse`, [`Bun.YAML.parse`](https://bun.com/docs/api/yaml), [`Bun.color`](https://bun.com/docs/api/color) --- diff --git a/docs/runtime/bunfig.md b/docs/runtime/bunfig.md index c4bce6c3db..0c030697dc 100644 --- a/docs/runtime/bunfig.md +++ b/docs/runtime/bunfig.md @@ -94,6 +94,7 @@ Bun supports the following loaders: - `file` - `json` - `toml` +- `yaml` - `wasm` - `napi` - `base64` diff --git a/docs/runtime/index.md b/docs/runtime/index.md index d737892af0..c55e11323f 100644 --- a/docs/runtime/index.md +++ b/docs/runtime/index.md @@ -92,15 +92,18 @@ every file before execution. Its transpiler can directly run TypeScript and JSX ## JSX -## JSON and TOML +## JSON, TOML, and YAML -Source files can import a `*.json` or `*.toml` file to load its contents as a plain old JavaScript object. +Source files can import `*.json`, `*.toml`, or `*.yaml` files to load their contents as plain JavaScript objects. ```ts import pkg from "./package.json"; import bunfig from "./bunfig.toml"; +import config from "./config.yaml"; ``` +See the [YAML API documentation](/docs/api/yaml) for more details on YAML support. + ## WASI {% callout %} diff --git a/docs/runtime/loaders.md b/docs/runtime/loaders.md index 18608f3020..6cbeea35aa 100644 --- a/docs/runtime/loaders.md +++ b/docs/runtime/loaders.md @@ -52,15 +52,18 @@ Hello world! {% /codetabs %} -## JSON and TOML +## JSON, TOML, and YAML -JSON and TOML files can be directly imported from a source file. The contents will be loaded and returned as a JavaScript object. +JSON, TOML, and YAML files can be directly imported from a source file. The contents will be loaded and returned as a JavaScript object. ```ts import pkg from "./package.json"; import data from "./data.toml"; +import config from "./config.yaml"; ``` +For more details on YAML support, see the [YAML API documentation](/docs/api/yaml). + ## WASI {% callout %}