diff --git a/docs/bundler/index.mdx b/docs/bundler/index.mdx index 66696f0151..6204c42bca 100644 --- a/docs/bundler/index.mdx +++ b/docs/bundler/index.mdx @@ -160,8 +160,12 @@ Like the Bun runtime, the bundler supports an array of file types out of the box | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `.js` `.jsx` `.cjs` `.mjs` `.mts` `.cts` `.ts` `.tsx` | Uses Bun's built-in transpiler to parse the file and transpile TypeScript/JSX syntax to vanilla JavaScript. The bundler executes a set of default transforms including dead code elimination and tree shaking. At the moment Bun does not attempt to down-convert syntax; if you use recently ECMAScript syntax, that will be reflected in the bundled code. | | `.json` | JSON files are parsed and inlined into the bundle as a JavaScript object.

`js
import pkg from "./package.json";
pkg.name; // => "my-package"
` | +| `.jsonc` | JSON with comments. Files are parsed and inlined into the bundle as a JavaScript object.

`js
import config from "./config.jsonc";
config.name; // => "my-config"
` | | `.toml` | TOML files are parsed and inlined into the bundle as a JavaScript object.

`js
import config from "./bunfig.toml";
config.logLevel; // => "debug"
` | +| `.yaml` `.yml` | YAML files are parsed and inlined into the bundle as a JavaScript object.

`js
import config from "./config.yaml";
config.name; // => "my-app"
` | | `.txt` | The contents of the text file are read and inlined into the bundle as a string.

`js
import contents from "./file.txt";
console.log(contents); // => "Hello, world!"
` | +| `.html` | HTML files are processed and any referenced assets (scripts, stylesheets, images) are bundled. | +| `.css` | CSS files are bundled together into a single `.css` file in the output directory. | | `.node` `.wasm` | These files are supported by the Bun runtime, but during bundling they are treated as assets. | ### Assets @@ -1462,7 +1466,21 @@ interface BuildArtifact extends Blob { sourcemap: BuildArtifact | null; } -type Loader = "js" | "jsx" | "ts" | "tsx" | "json" | "toml" | "file" | "napi" | "wasm" | "text"; +type Loader = + | "js" + | "jsx" + | "ts" + | "tsx" + | "css" + | "json" + | "jsonc" + | "toml" + | "yaml" + | "text" + | "file" + | "napi" + | "wasm" + | "html"; interface BuildOutput { outputs: BuildArtifact[]; diff --git a/docs/bundler/loaders.mdx b/docs/bundler/loaders.mdx index a610186f58..89e8824679 100644 --- a/docs/bundler/loaders.mdx +++ b/docs/bundler/loaders.mdx @@ -7,7 +7,7 @@ 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` `.css` `.json` `.jsonc` `.toml` `.yaml` `.yml` `.txt` `.wasm` `.node` `.html` `.sh` 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 that extend Bun with custom loaders. @@ -85,7 +85,7 @@ If a `.json` file is passed as an entrypoint to the bundler, it will be converte } ``` -```ts Output +```js Output export default { name: "John Doe", age: 35, @@ -97,7 +97,33 @@ export default { --- -### toml +### `jsonc` + +**JSON with Comments loader.** Default for `.jsonc`. + +JSONC (JSON with Comments) files can be directly imported. Bun will parse them, stripping out comments and trailing commas. + +```js +import config from "./config.jsonc"; +console.log(config); +``` + +During bundling, the parsed JSONC is inlined into the bundle as a JavaScript object, identical to the `json` loader. + +```js +var config = { + option: "value", +}; +``` + + + Bun automatically uses the `jsonc` loader for `tsconfig.json`, `jsconfig.json`, `package.json`, and `bun.lock` files, + allowing comments and trailing commas in these files. + + +--- + +### `toml` **TOML loader.** Default for `.toml`. @@ -131,7 +157,7 @@ age = 35 email = "johndoe@example.com" ``` -```ts Output +```js Output export default { name: "John Doe", age: 35, @@ -143,7 +169,53 @@ export default { --- -### text +### `yaml` + +**YAML loader.** Default for `.yaml` and `.yml`. + +YAML files can be directly imported. Bun will parse them with its fast native YAML parser. + +```js +import config from "./config.yaml"; +console.log(config); + +// via import attribute: +import data from "./data.txt" with { type: "yaml" }; +``` + +During bundling, the parsed YAML is inlined into the bundle as a JavaScript object. + +```js +var config = { + name: "my-app", + version: "1.0.0", + // ...other fields +}; +``` + +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. + + + +```yaml Input +name: John Doe +age: 35 +email: johndoe@example.com +``` + +```js Output +export default { + name: "John Doe", + age: 35, + email: "johndoe@example.com", +}; +``` + + + +--- + +### `text` **Text loader.** Default for `.txt`. @@ -173,7 +245,7 @@ If a `.txt` file is passed as an entrypoint, it will be converted to a `.js` mod Hello, world! ``` -```ts Output +```js Output export default "Hello, world!"; ``` @@ -181,7 +253,7 @@ export default "Hello, world!"; --- -### napi +### `napi` **Native addon loader.** Default for `.node`. @@ -196,7 +268,7 @@ console.log(addon); --- -### sqlite +### `sqlite` **SQLite loader.** Requires `with { "type": "sqlite" }` import attribute. @@ -226,7 +298,9 @@ Otherwise, the database to embed is copied into the `outdir` with a hashed filen --- -### html +### `html` + +**HTML loader.** Default for `.html`. The `html` loader processes HTML files and bundles any referenced assets. It will: @@ -301,7 +375,27 @@ The `html` loader behaves differently depending on how it's used: --- -### sh +### `css` + +**CSS loader.** Default for `.css`. + +CSS files can be directly imported. The bundler will parse and bundle CSS files, handling `@import` statements and `url()` references. + +```js +import "./styles.css"; +``` + +During bundling, all imported CSS files are bundled together into a single `.css` file in the output directory. + +```css +.my-class { + background: url("./image.png"); +} +``` + +--- + +### `sh` **Bun Shell loader.** Default for `.sh` files. @@ -313,7 +407,7 @@ bun run ./script.sh --- -### file +### `file` **File loader.** Default for all unrecognized file types. diff --git a/docs/bundler/plugins.mdx b/docs/bundler/plugins.mdx index 49caa67bae..58908e352f 100644 --- a/docs/bundler/plugins.mdx +++ b/docs/bundler/plugins.mdx @@ -42,7 +42,21 @@ type PluginBuilder = { config: BuildConfig; }; -type Loader = "js" | "jsx" | "ts" | "tsx" | "css" | "json" | "toml"; +type Loader = + | "js" + | "jsx" + | "ts" + | "tsx" + | "json" + | "jsonc" + | "toml" + | "yaml" + | "file" + | "napi" + | "wasm" + | "text" + | "css" + | "html"; ``` ## Usage diff --git a/docs/runtime/plugins.mdx b/docs/runtime/plugins.mdx index a64af263a6..aff34d67a5 100644 --- a/docs/runtime/plugins.mdx +++ b/docs/runtime/plugins.mdx @@ -42,7 +42,21 @@ type PluginBuilder = { config: BuildConfig; }; -type Loader = "js" | "jsx" | "ts" | "tsx" | "css" | "json" | "toml"; +type Loader = + | "js" + | "jsx" + | "ts" + | "tsx" + | "json" + | "jsonc" + | "toml" + | "yaml" + | "file" + | "napi" + | "wasm" + | "text" + | "css" + | "html"; ``` ## Usage diff --git a/packages/bun-types/bun.d.ts b/packages/bun-types/bun.d.ts index c4daec79ac..a4d84f4352 100644 --- a/packages/bun-types/bun.d.ts +++ b/packages/bun-types/bun.d.ts @@ -4041,7 +4041,21 @@ declare module "bun" { | "browser"; /** https://bun.com/docs/bundler/loaders */ - type Loader = "js" | "jsx" | "ts" | "tsx" | "json" | "toml" | "file" | "napi" | "wasm" | "text" | "css" | "html"; + type Loader = + | "js" + | "jsx" + | "ts" + | "tsx" + | "json" + | "jsonc" + | "toml" + | "yaml" + | "file" + | "napi" + | "wasm" + | "text" + | "css" + | "html"; interface PluginConstraints { /**