bun-types 1.3.3-canary.20251112T140644 → 1.3.3-canary.20251114T140703

package/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 {
     /**
@@ -6430,6 +6444,16 @@ declare module "bun" {
     /** @see https://bun.com/docs/install/catalogs */
     catalogs?: Record<string, Record<string, string>>;
 
+    /**
+     * `0` / `undefined` for projects created before v1.3.2, `1` for projects created after.
+     *
+     * ---
+     * Right now this only changes the default [install linker strategy](https://bun.com/docs/pm/cli/install#isolated-installs):
+     * - With `0`, the linker is hoisted.
+     * - With `1`, the linker is isolated for workspaces and hoisted for single-package projects.
+     */
+    configVersion?: 0 | 1;
+
     /**
      * ```
      * INFO = { prod/dev/optional/peer dependencies, os, cpu, libc (TODO), bin, binDir }

package/docs/bundler/css.mdx

@@ -34,7 +34,7 @@ By default, Bun's CSS bundler targets the following browsers:
 
 The CSS Nesting specification allows you to write more concise and intuitive stylesheets by nesting selectors inside one another. Instead of repeating parent selectors across your CSS file, you can write child styles directly within their parent blocks.
 
-```css title="styles.css" icon="file-code"
+```scss title="styles.css" icon="file-code"
 /* With nesting */
 .card {
   background: white;
@@ -100,7 +100,7 @@ This compiles to:
 
 The `color-mix()` function gives you an easy way to blend two colors together according to a specified ratio in a chosen color space. This powerful feature lets you create color variations without manually calculating the resulting values.
 
-```css title="styles.css" icon="file-code"
+```scss title="styles.css" icon="file-code"
 .button {
   /* Mix blue and red in the RGB color space with a 30/70 proportion */
   background-color: color-mix(in srgb, blue 30%, red);

package/docs/bundler/esbuild.mdx

@@ -231,23 +231,67 @@ const myPlugin: BunPlugin = {
 ### onResolve
 
 <Tabs>
-  <Tab title="options">- 🟢 `filter` - 🟢 `namespace`</Tab>
+  <Tab title="options">
+
+    - 🟢 `filter`
+    - 🟢 `namespace`
+
+  </Tab>
   <Tab title="arguments">
-    - 🟢 `path` - 🟢 `importer` - 🔴 `namespace` - 🔴 `resolveDir` - 🔴 `kind` - 🔴 `pluginData`
+
+    - 🟢 `path`
+    - 🟢 `importer`
+    - 🔴 `namespace`
+    - 🔴 `resolveDir`
+    - 🔴 `kind`
+    - 🔴 `pluginData`
+
   </Tab>
   <Tab title="results">
-    - 🟢 `namespace` - 🟢 `path` - 🔴 `errors` - 🔴 `external` - 🔴 `pluginData` - 🔴 `pluginName` - 🔴 `sideEffects` -
-    🔴 `suffix` - 🔴 `warnings` - 🔴 `watchDirs` - 🔴 `watchFiles`
+
+    - 🟢 `namespace`
+    - 🟢 `path`
+    - 🔴 `errors`
+    - 🔴 `external`
+    - 🔴 `pluginData`
+    - 🔴 `pluginName`
+    - 🔴 `sideEffects`
+    - 🔴 `suffix`
+    - 🔴 `warnings`
+    - 🔴 `watchDirs`
+    - 🔴 `watchFiles`
+
   </Tab>
 </Tabs>
 
 ### onLoad
 
 <Tabs>
-  <Tab title="options">- 🟢 `filter` - 🟢 `namespace`</Tab>
-  <Tab title="arguments">- 🟢 `path` - 🔴 `namespace` - 🔴 `suffix` - 🔴 `pluginData`</Tab>
+  <Tab title="options">
+
+    - 🟢 `filter`
+    - 🟢 `namespace`
+
+  </Tab>
+  <Tab title="arguments">
+  
+    - 🟢 `path`
+    - 🔴 `namespace`
+    - 🔴 `suffix`
+    - 🔴 `pluginData`
+
+  </Tab>
   <Tab title="results">
-    - 🟢 `contents` - 🟢 `loader` - 🔴 `errors` - 🔴 `pluginData` - 🔴 `pluginName` - 🔴 `resolveDir` - 🔴 `warnings` -
-    🔴 `watchDirs` - 🔴 `watchFiles`
+
+    - 🟢 `contents`
+    - 🟢 `loader`
+    - 🔴 `errors`
+    - 🔴 `pluginData`
+    - 🔴 `pluginName`
+    - 🔴 `resolveDir`
+    - 🔴 `warnings`
+    - 🔴 `watchDirs`
+    - 🔴 `watchFiles`
+
   </Tab>
 </Tabs>

package/docs/bundler/executables.mdx

@@ -216,7 +216,7 @@ However, with the `BUN_BE_BUN=1` environment variable, it acts just like the `bu
 
 ```bash icon="terminal" terminal
 # With the env var, the executable acts like the `bun` CLI
-bun_BE_BUN=1 ./such-bun install
+BUN_BE_BUN=1 ./such-bun install
 ```
 
 ```txt

package/docs/bundler/html-static.mdx

@@ -237,13 +237,27 @@ Then, reference TailwindCSS in your HTML via `<link>` tag, `@import` in CSS, or
 
 <Tabs>
   <Tab title="index.html">
+
     ```html title="index.html" icon="file-code"
-    {/* Reference TailwindCSS in your HTML */}
+    <!-- Reference TailwindCSS in your HTML -->
     <link rel="stylesheet" href="tailwindcss" />
     ```
+
+  </Tab>
+  <Tab title="styles.css">
+
+    ```css title="styles.css" icon="file-code"
+    @import "tailwindcss";
+    ```
+
+  </Tab>
+  <Tab title="app.ts">
+
+    ```ts title="app.ts" icon="/icons/typescript.svg"
+    import "tailwindcss";
+    ```
+
   </Tab>
-  <Tab title="styles.css">```css title="styles.css" icon="file-code" @import "tailwindcss"; ```</Tab>
-  <Tab title="app.ts">```ts title="app.ts" icon="/icons/typescript.svg" import "tailwindcss"; ```</Tab>
 </Tabs>
 
 <Info>Only one of those are necessary, not all three.</Info>

package/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.<br/><br/>`js<br/>import pkg from "./package.json";<br/>pkg.name; // => "my-package"<br/>`                                                                                                                                                                                          |
+| `.jsonc`                                              | JSON with comments. Files are parsed and inlined into the bundle as a JavaScript object.<br/><br/>`js<br/>import config from "./config.jsonc";<br/>config.name; // => "my-config"<br/>`                                                                                                                                                                      |
 | `.toml`                                               | TOML files are parsed and inlined into the bundle as a JavaScript object.<br/><br/>`js<br/>import config from "./bunfig.toml";<br/>config.logLevel; // => "debug"<br/>`                                                                                                                                                                                      |
+| `.yaml` `.yml`                                        | YAML files are parsed and inlined into the bundle as a JavaScript object.<br/><br/>`js<br/>import config from "./config.yaml";<br/>config.name; // => "my-app"<br/>`                                                                                                                                                                                         |
 | `.txt`                                                | The contents of the text file are read and inlined into the bundle as a string.<br/><br/>`js<br/>import contents from "./file.txt";<br/>console.log(contents); // => "Hello, world!"<br/>`                                                                                                                                                                   |
+| `.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[];

package/docs/bundler/loaders.mdx

@@ -7,14 +7,16 @@ 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.
 
-You can explicitly specify which loader to use using the `'loader'` import attribute.
+You can explicitly specify which loader to use using the `'type'` import attribute.
 
 ```ts title="index.ts" icon="/icons/typescript.svg"
-import my_toml from "./my_file" with { loader: "toml" };
+import my_toml from "./my_file" with { type: "toml" };
+// or with dynamic imports
+const { default: my_toml } = await import("./my_file", { with: { type: "toml" } });
 ```
 
 ## Built-in loaders
@@ -85,7 +87,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 +99,32 @@ 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",
+};
+```
+
+<Note>
+  Bun automatically uses the `jsonc` loader for `tsconfig.json`, `jsconfig.json`, `package.json`, and `bun.lock` files.
+</Note>
+
+---
+
+### `toml`
 
 **TOML loader.** Default for `.toml`.
 
@@ -131,7 +158,7 @@ age = 35
 email = "johndoe@example.com"
 ```
 
-```ts Output
+```js Output
 export default {
   name: "John Doe",
   age: 35,
@@ -143,7 +170,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.
+
+<CodeGroup>
+
+```yaml Input
+name: John Doe
+age: 35
+email: johndoe@example.com
+```
+
+```js Output
+export default {
+  name: "John Doe",
+  age: 35,
+  email: "johndoe@example.com",
+};
+```
+
+</CodeGroup>
+
+---
+
+### `text`
 
 **Text loader.** Default for `.txt`.
 
@@ -173,7 +246,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 +254,7 @@ export default "Hello, world!";
 
 ---
 
-### napi
+### `napi`
 
 **Native addon loader.** Default for `.node`.
 
@@ -196,7 +269,7 @@ console.log(addon);
 
 ---
 
-### sqlite
+### `sqlite`
 
 **SQLite loader.** Requires `with { "type": "sqlite" }` import attribute.
 
@@ -226,7 +299,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 +376,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 +408,7 @@ bun run ./script.sh
 
 ---
 
-### file
+### `file`
 
 **File loader.** Default for all unrecognized file types.