bun-types 1.3.2-canary.20251105T140650 → 1.3.2

package/docs/quickstart.mdx

@@ -0,0 +1,240 @@
+---
+title: Quickstart
+description: Build your first app with Bun
+---
+
+## Overview
+
+Build a minimal HTTP server with `Bun.serve`, run it locally, then evolve it by installing a package.
+
+<Info>Prerequisites: Bun installed and available on your `PATH`. See [installation](/installation) for setup.</Info>
+
+---
+
+<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.
+
+---
+
+## Run a script
+
+Bun can also execute `"scripts"` from your `package.json`. Add the following script:
+
+```json package.json icon="file-code"
+{
+  "name": "quickstart",
+  "module": "index.ts",
+  "type": "module",
+  "scripts": {
+    "start": "bun run index.ts"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  }
+}
+```
+
+Then run it with `bun run start`.
+
+```bash terminal icon="terminal"
+bun run start
+```
+
+```txt
+ 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/{autoimport.md → auto-install.mdx}

@@ -1,8 +1,13 @@
+---
+title: "Auto-install"
+description: "Bun's automatic package installation feature for standalone script execution"
+---
+
 If no `node_modules` directory is found in the working directory or higher, Bun will abandon Node.js-style module resolution in favor of the **Bun module resolution algorithm**.
 
-Under Bun-style module resolution, all imported packages are auto-installed on the fly into a [global module cache](https://bun.com/docs/install/cache) during execution (the same cache used by [`bun install`](https://bun.com/docs/cli/install)).
+Under Bun-style module resolution, all imported packages are auto-installed on the fly into a [global module cache](/pm/global-cache) during execution (the same cache used by [`bun install`](/pm/cli/install)).
 
-```ts
+```ts index.ts icon="/icons/typescript.svg"
 import { foo } from "foo"; // install `latest` version
 
 foo();
@@ -10,6 +15,8 @@ foo();
 
 The first time you run this script, Bun will auto-install `"foo"` and cache it. The next time you run the script, it will use the cached version.
 
+---
+
 ## Version resolution
 
 To determine which version to install, Bun follows the following algorithm:
@@ -18,6 +25,8 @@ To determine which version to install, Bun follows the following algorithm:
 2. Otherwise, scan up the tree for a `package.json` that includes `"foo"` as a dependency. If found, use the specified semver version or version range.
 3. Otherwise, use `latest`.
 
+---
+
 ## Cache behavior
 
 Once a version or version range has been determined, Bun will:
@@ -26,20 +35,26 @@ Once a version or version range has been determined, Bun will:
 2. When resolving `latest`, Bun will check if `package@latest` has been downloaded and cached in the last _24 hours_. If so, use it.
 3. Otherwise, download and install the appropriate version from the `npm` registry.
 
+---
+
 ## Installation
 
 Packages are installed and cached into `<cache>/<pkg>@<version>`, so multiple versions of the same package can be cached at once. Additionally, a symlink is created under `<cache>/<pkg>/<version>` to make it faster to look up all versions of a package that exist in the cache.
 
+---
+
 ## Version specifiers
 
 This entire resolution algorithm can be short-circuited by specifying a version or version range directly in your import statement.
 
-```ts
+```ts index.ts icon="/icons/typescript.svg"
 import { z } from "zod@3.0.0"; // specific version
 import { z } from "zod@next"; // npm tag
 import { z } from "zod@^3.20.0"; // semver range
 ```
 
+---
+
 ## Benefits
 
 This auto-installation approach is useful for a few reasons:
@@ -49,46 +64,34 @@ This auto-installation approach is useful for a few reasons:
 - **Convenience** — There's no need to run `npm install` or `bun install` before running a file or script. Just `bun run` it.
 - **Backwards compatibility** — Because Bun still respects the versions specified in `package.json` if one exists, you can switch to Bun-style resolution with a single command: `rm -rf node_modules`.
 
+---
+
 ## Limitations
 
 - No Intellisense. TypeScript auto-completion in IDEs relies on the existence of type declaration files inside `node_modules`. We are investigating various solutions to this.
 - No [patch-package](https://github.com/ds300/patch-package) support
 
-<!-- - The implementation details of Bun's install cache will change between versions. Don't think of it as an API. To reliably resolve packages, use Bun's builtin APIs (such as `Bun.resolveSync` or `import.meta.resolve`) instead of relying on the filesystem directly. Bun will likely move to a binary archive format where packages may not correspond to files/folders on disk at all - so if you depend on the filesystem structure instead of the JavaScript API, your code will eventually break. -->
-
-<!-- ## Customizing behavior
+---
 
-To prefer locally-installed versions of packages. Instead of checking npm for latest versions, you can pass the `--prefer-offline` flag to prefer locally-installed versions of packages.
-
-```bash
-$ bun run --prefer-offline my-script.ts
-```
-
-This will check the install cache for installed versions of packages before checking the npm registry. If no matching version of a package is installed, only then will it check npm for the latest version.
-
-#### Prefer latest
-
-To always use the latest version of a package, you can pass the `--prefer-latest` flag.
+## FAQ
 
-```bash
-$ bun run --prefer-latest my-script.ts
-``` -->
+<AccordionGroup>
 
-## FAQ
+    <Accordion title="How is this different from what pnpm does?">
 
-{% details summary="How is this different from what pnpm does?" %}
+    With pnpm, you have to run `pnpm install`, which creates a `node_modules` folder of symlinks for the runtime to resolve. By contrast, Bun resolves dependencies on the fly when you run a file; there's no need to run any `install` command ahead of time. Bun also doesn't create a `node_modules` folder.
 
-With pnpm, you have to run `pnpm install`, which creates a `node_modules` folder of symlinks for the runtime to resolve. By contrast, Bun resolves dependencies on the fly when you run a file; there's no need to run any `install` command ahead of time. Bun also doesn't create a `node_modules` folder.
+    </Accordion>
 
-{% /details %}
+    <Accordion title="How is this different from Yarn Plug'N'Play does?">
+    With Yarn, you must run `yarn install` before you run a script. By contrast, Bun resolves dependencies on the fly when you run a file; there's no need to run any `install` command ahead of time.
 
-{% details summary="How is this different from Yarn Plug'N'Play does?" %}
-With Yarn, you must run `yarn install` before you run a script. By contrast, Bun resolves dependencies on the fly when you run a file; there's no need to run any `install` command ahead of time.
+    Yarn Plug'N'Play also uses zip files to store dependencies. This makes dependency loading [slower at runtime](https://twitter.com/jarredsumner/status/1458207919636287490), as random access reads on zip files tend to be slower than the equivalent disk lookup.
+    </Accordion>
 
-Yarn Plug'N'Play also uses zip files to store dependencies. This makes dependency loading [slower at runtime](https://twitter.com/jarredsumner/status/1458207919636287490), as random access reads on zip files tend to be slower than the equivalent disk lookup.
-{% /details %}
+    <Accordion title="How is this different from what Deno does?">
 
-{% details summary="How is this different from what Deno does?" %}
+    Deno requires an `npm:` specifier before each npm `import`, lacks support for import maps via `compilerOptions.paths` in `tsconfig.json`, and has incomplete support for `package.json` settings. Unlike Deno, Bun does not currently support URL imports.
+    </Accordion>
 
-Deno requires an `npm:` specifier before each npm `import`, lacks support for import maps via `compilerOptions.paths` in `tsconfig.json`, and has incomplete support for `package.json` settings. Unlike Deno, Bun does not currently support URL imports.
-{% /details %}
+</AccordionGroup>