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

package/docs/quickstart.mdx

@@ -12,198 +12,204 @@ Build a minimal HTTP server with `Bun.serve`, run it locally, then evolve it by
 ---
 
 <Steps>
-	<Step title="Step 1">
-		Initialize a new project with `bun init`.
-
-    	```bash terminal icon="terminal"
-    	bun init my-app
-    	```
-
-    	It'll prompt you to pick a template, either `Blank`, `React`, or `Library`. For this guide, we'll pick `Blank`.
-
-    	```bash terminal icon="terminal"
-    	bun init my-app
-    	```
-    	```txt
-    	✓ Select a project template: Blank
-
-- .gitignore
-- CLAUDE.md
-- .cursor/rules/use-bun-instead-of-node-vite-npm-pnpm.mdc -> CLAUDE.md
-- index.ts
-- tsconfig.json (for editor autocomplete)
-- README.md
-
-  ````
-
-      	This automatically creates a `my-app` directory with a basic Bun app.
-      </Step>
-      <Step title="Step 2">
-
-      	Run the `index.ts` file using `bun run index.ts`.
-
-      	```bash terminal icon="terminal"
-      	cd my-app
-      	bun run index.ts
-      	```
-      	```txt
-      Hello via Bun!
-      	```
-
-      	You should see a console output saying `"Hello via Bun!"`.
-      </Step>
-      <Step title="Step 3">
-      	Replace the contents of `index.ts` with the following code:
-
-      	```ts index.ts icon="/icons/typescript.svg"
-      	const server = Bun.serve({
-      		port: 3000,
-      		routes: {
-      			"/": () => new Response('Bun!'),
-      		}
-      	});
-
-      	console.log(`Listening on ${server.url}`);
-      	```
-
-      	Run the `index.ts` file again using `bun run index.ts`.
-
-      	```bash terminal icon="terminal"
-      	bun run index.ts
-      	```
-      	```txt
-      	Listening on http://localhost:3000
-      	```
-
-      	Visit [`http://localhost:3000`](http://localhost:3000) to test the server. You should see a simple page that says `"Bun!"`.
-
-
-      	<Accordion title="Seeing TypeScript errors on Bun?">
-      		If you used `bun init`, Bun will have automatically installed Bun's TypeScript declarations and configured your `tsconfig.json`. If you're trying out Bun in an existing project, you may see a type error on the `Bun` global.
-
-      		To fix this, first install `@types/bun` as a dev dependency.
-
-      		```bash terminal icon="terminal"
-      		bun add -d @types/bun
-      		```
-
-      		Then add the following to your `compilerOptions` in `tsconfig.json`:
-
-      		```json tsconfig.json icon="file-code"
-      		{
-      			"compilerOptions": {
-      				"lib": ["ESNext"],
-      				"target": "ESNext",
-      				"module": "Preserve",
-      				"moduleDetection": "force",
-      				"moduleResolution": "bundler",
-      				"allowImportingTsExtensions": true,
-      				"verbatimModuleSyntax": true,
-      				"noEmit": true
-      			}
-      		}
-      		```
-
-      	</Accordion>
-
-      </Step>
-      <Step title="Step 4">
-      	Install the `figlet` package and its type declarations. Figlet is a utility for converting strings into ASCII art.
-
-      	```bash terminal icon="terminal"
-      	bun add figlet
-      	bun add -d @types/figlet # TypeScript users only
-      	```
-
-      	Update `index.ts` to use `figlet` in `routes`.
-
-      	```ts index.ts icon="/icons/typescript.svg"
-      	import figlet from 'figlet'; // [!code ++]
-
-      	const server = Bun.serve({
-      		port: 3000,
-      		routes: {
-      			"/": () => new Response('Bun!'),
-      			"/figlet": () => { // [!code ++]
-      				const body = figlet.textSync('Bun!'); // [!code ++]
-      				return new Response(body); // [!code ++]
-      			} // [!code ++]
-      		}
-      	});
-
-      	console.log(`Listening on ${server.url}`);
-      	```
-
-      	Run the `index.ts` file again using `bun run index.ts`.
-
-      	```bash terminal icon="terminal"
-      	bun run index.ts
-      	```
-      	```txt
-      	Listening on http://localhost:3000
-      	```
-
-      	Visit [`http://localhost:3000/figlet`](http://localhost:3000/figlet) to test the server. You should see a simple page that says `"Bun!"` in ASCII art.
-
-      	```txt
-      	 ____              _
-      	| __ ) _   _ _ __ | |
-      	|  _ \| | | | '_ \| |
-      	| |_) | |_| | | | |_|
-      	|____/ \__,_|_| |_(_)
-      	```
-      </Step>
-      <Step title="Step 5">
-      	Let's add some HTML. Create a new file called `index.html` and add the following code:
-
-      	```html index.html icon="file-code"
-      	<!DOCTYPE html>
-      	<html lang="en">
-      		<head>
-      			<meta charset="UTF-8">
-      			<meta name="viewport" content="width=device-width, initial-scale=1.0">
-      			<title>Bun</title>
-      		</head>
-      		<body>
-      			<h1>Bun!</h1>
-      		</body>
-      	</html>
-      	```
-
-      	Then, import this file in `index.ts` and serve it from the root `/` route.
-
-      	```ts index.ts icon="/icons/typescript.svg"
-      	import figlet from 'figlet';
-      	import index from './index.html'; // [!code ++]
-
-      	const server = Bun.serve({
-      		port: 3000,
-      		routes: {
-      			"/": index, // [!code ++]
-      			"/figlet": () => {
-      				const body = figlet.textSync('Bun!');
-      				return new Response(body);
-      			}
-      		}
-      	});
-
-      	console.log(`Listening on ${server.url}`);
-      	```
-
-      	Run the `index.ts` file again using `bun run index.ts`.
-
-      	```bash terminal icon="terminal"
-      	bun run index.ts
-      	```
-      	```txt
-      	Listening on http://localhost:3000
-      	```
-
-      	Visit [`http://localhost:3000`](http://localhost:3000) to test the server. You should see the static HTML page.
-      </Step>
-
-  </Steps>
-  ````
+  <Step title="Step 1">
+
+    Initialize a new project with `bun init`.
+
+    ```bash terminal icon="terminal"
+    bun init my-app
+    ```
+
+    It'll prompt you to pick a template, either `Blank`, `React`, or `Library`. For this guide, we'll pick `Blank`.
+
+    ```bash terminal icon="terminal"
+    bun init my-app
+    ```
+    ```txt
+    ✓ Select a project template: Blank
+
+    - .gitignore
+    - CLAUDE.md
+    - .cursor/rules/use-bun-instead-of-node-vite-npm-pnpm.mdc -> CLAUDE.md
+    - index.ts
+    - tsconfig.json (for editor autocomplete)
+    - README.md
+    ```
+
+    This automatically creates a `my-app` directory with a basic Bun app.
+
+  </Step>
+  <Step title="Step 2">
+
+    Run the `index.ts` file using `bun run index.ts`.
+
+    ```bash terminal icon="terminal"
+    cd my-app
+    bun run index.ts
+    ```
+    ```txt
+    Hello via Bun!
+    ```
+
+    You should see a console output saying `"Hello via Bun!"`.
+
+  </Step>
+  <Step title="Step 3">
+
+    Replace the contents of `index.ts` with the following code:
+
+    ```ts index.ts icon="/icons/typescript.svg"
+    const server = Bun.serve({
+      port: 3000,
+      routes: {
+        "/": () => new Response('Bun!'),
+      }
+    });
+
+    console.log(`Listening on ${server.url}`);
+    ```
+
+    Run the `index.ts` file again using `bun run index.ts`.
+
+    ```bash terminal icon="terminal"
+    bun run index.ts
+    ```
+    ```txt
+    Listening on http://localhost:3000
+    ```
+
+    Visit [`http://localhost:3000`](http://localhost:3000) to test the server. You should see a simple page that says `"Bun!"`.
+
+    <Accordion title="Seeing TypeScript errors on Bun?">
+
+      If you used `bun init`, Bun will have automatically installed Bun's TypeScript declarations and configured your `tsconfig.json`. If you're trying out Bun in an existing project, you may see a type error on the `Bun` global.
+
+      To fix this, first install `@types/bun` as a dev dependency.
+
+      ```bash terminal icon="terminal"
+      bun add -d @types/bun
+      ```
+
+      Then add the following to your `compilerOptions` in `tsconfig.json`:
+
+      ```json tsconfig.json icon="file-code"
+      {
+        "compilerOptions": {
+          "lib": ["ESNext"],
+          "target": "ESNext",
+          "module": "Preserve",
+          "moduleDetection": "force",
+          "moduleResolution": "bundler",
+          "allowImportingTsExtensions": true,
+          "verbatimModuleSyntax": true,
+          "noEmit": true
+        }
+      }
+      ```
+
+    </Accordion>
+
+  </Step>
+  <Step title="Step 4">
+
+    Install the `figlet` package and its type declarations. Figlet is a utility for converting strings into ASCII art.
+
+    ```bash terminal icon="terminal"
+    bun add figlet
+    bun add -d @types/figlet # TypeScript users only
+    ```
+
+    Update `index.ts` to use `figlet` in `routes`.
+
+    ```ts index.ts icon="/icons/typescript.svg"
+    import figlet from 'figlet'; // [!code ++]
+
+    const server = Bun.serve({
+      port: 3000,
+      routes: {
+        "/": () => new Response('Bun!'),
+        "/figlet": () => { // [!code ++]
+          const body = figlet.textSync('Bun!'); // [!code ++]
+          return new Response(body); // [!code ++]
+        } // [!code ++]
+      }
+    });
+
+    console.log(`Listening on ${server.url}`);
+    ```
+
+    Run the `index.ts` file again using `bun run index.ts`.
+
+    ```bash terminal icon="terminal"
+    bun run index.ts
+    ```
+    ```txt
+    Listening on http://localhost:3000
+    ```
+
+    Visit [`http://localhost:3000/figlet`](http://localhost:3000/figlet) to test the server. You should see a simple page that says `"Bun!"` in ASCII art.
+
+    ```txt
+    ____              _
+    | __ ) _   _ _ __ | |
+    |  _ \| | | | '_ \| |
+    | |_) | |_| | | | |_|
+    |____/ \__,_|_| |_(_)
+    ```
+
+  </Step>
+  <Step title="Step 5">
+
+    Let's add some HTML. Create a new file called `index.html` and add the following code:
+
+    ```html index.html icon="file-code"
+    <!DOCTYPE html>
+    <html lang="en">
+      <head>
+        <meta charset="UTF-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1.0">
+        <title>Bun</title>
+      </head>
+      <body>
+        <h1>Bun!</h1>
+      </body>
+    </html>
+    ```
+
+    Then, import this file in `index.ts` and serve it from the root `/` route.
+
+    ```ts index.ts icon="/icons/typescript.svg"
+    import figlet from 'figlet';
+    import index from './index.html'; // [!code ++]
+
+    const server = Bun.serve({
+      port: 3000,
+      routes: {
+        "/": index, // [!code ++]
+        "/figlet": () => {
+          const body = figlet.textSync('Bun!');
+          return new Response(body);
+        }
+      }
+    });
+
+    console.log(`Listening on ${server.url}`);
+    ```
+
+    Run the `index.ts` file again using `bun run index.ts`.
+
+    ```bash terminal icon="terminal"
+    bun run index.ts
+    ```
+    ```txt
+    Listening on http://localhost:3000
+    ```
+
+    Visit [`http://localhost:3000`](http://localhost:3000) to test the server. You should see the static HTML page.
+
+  </Step>
+
+</Steps>
 
 🎉 Congratulations! You've built a simple HTTP server with Bun and installed a package.
 
@@ -234,7 +240,7 @@ bun run start
 ```
 
 ```txt
- Listening on http://localhost:3000
+Listening on http://localhost:3000
 ```
 
 <Note>⚡️ **Performance** — `bun run` is roughly 28x faster than `npm run` (6ms vs 170ms of overhead).</Note>

package/docs/runtime/bunfig.mdx

@@ -401,6 +401,7 @@ Environment variable: `BUN_INSTALL_BIN`
 
 ```toml title="bunfig.toml" icon="settings"
 # where globally-installed package bins are linked
+[install]
 globalBinDir = "~/.bun/bin"
 ```
 

package/docs/runtime/file-types.mdx

@@ -5,14 +5,16 @@ description: "File types and loaders supported by Bun's bundler and runtime"
 
 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](/bundler/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
-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" } });
 ```
 
 ---
@@ -84,6 +86,29 @@ export default {
 
 </CodeGroup>
 
+### `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.
+
+```ts
+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.
+
+```ts
+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`.
@@ -128,6 +153,50 @@ export default {
 
 </CodeGroup>
 
+### `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";
+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.
+
+```ts
+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
+```
+
+```ts Output
+export default {
+  name: "John Doe",
+  age: 35,
+  email: "johndoe@example.com",
+};
+```
+
+</CodeGroup>
+
 ### `text`
 
 **Text loader**. Default for `.txt`.
@@ -283,6 +352,18 @@ The `html` loader behaves differently depending on how it's used:
 
 </Note>
 
+### `css`
+
+**CSS loader**. Default for `.css`.
+
+CSS files can be directly imported. This is primarily useful for [full-stack applications](/bundler/html-static) where CSS is bundled alongside HTML.
+
+```ts
+import "./styles.css";
+```
+
+There isn't any value returned from the import, it's only used for side effects.
+
 ### `sh` loader
 
 **Bun Shell loader**. Default for `.sh` files

package/docs/runtime/module-resolution.mdx

@@ -276,7 +276,7 @@ await Bun.build({
 
 ## Path re-mapping
 
-In the spirit of treating TypeScript as a first-class citizen, the Bun runtime will re-map import paths according to the [`compilerOptions.paths`](https://www.typescriptlang.org/tsconfig#paths) field in `tsconfig.json`. This is a major divergence from Node.js, which doesn't support any form of import path re-mapping.
+Bun supports import path re-mapping through TypeScript's [`compilerOptions.paths`](https://www.typescriptlang.org/tsconfig#paths) in `tsconfig.json`, which works well with editors. If you aren't a TypeScript user, you can achieve the same behavior by using a [`jsconfig.json`](https://code.visualstudio.com/docs/languages/jsconfig) in your project root.
 
 ```json tsconfig.json icon="file-json"
 {
@@ -289,7 +289,16 @@ In the spirit of treating TypeScript as a first-class citizen, the Bun runtime w
 }
 ```
 
-If you aren't a TypeScript user, you can create a [`jsconfig.json`](https://code.visualstudio.com/docs/languages/jsconfig) in your project root to achieve the same behavior.
+Bun also supports [Node.js-style subpath imports](https://nodejs.org/api/packages.html#subpath-imports) in `package.json`, where mapped paths must start with `#`. This approach doesn’t work as well with editors, but both options can be used together.
+
+```json package.json icon="file-json"
+{
+  "imports": {
+    "#config": "./config.ts", // map specifier to file
+    "#components/*": "./components/*" // wildcard matching
+  }
+}
+```
 
 <Accordion title="Low-level details of CommonJS interop in Bun">
 

package/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

package/docs/runtime/s3.mdx

@@ -697,7 +697,7 @@ To list some or all (up to 1,000) objects in a bucket, you can use the `S3Client
 ```ts s3.ts icon="/icons/typescript.svg" highlight={12, 15-20, 24-29}
 import { S3Client } from "bun";
 
-const credentials = { ... }
+const credentials = {
   accessKeyId: "your-access-key",
   secretAccessKey: "your-secret-key",
   bucket: "my-bucket",

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.3.3-canary.20251112T140644",
+  "version": "1.3.3-canary.20251114T140703",
   "name": "bun-types",
   "license": "MIT",
   "types": "./index.d.ts",