bun-types 1.3.2-canary.20251106T140813 → 1.3.2

package/docs/bundler/hot-reloading.mdx

@@ -0,0 +1,229 @@
+---
+title: Hot reloading
+description: Hot Module Replacement (HMR) for Bun's development server
+---
+
+Hot Module Replacement (HMR) allows you to update modules in a running application without needing a full page reload. This preserves the application state and improves the development experience.
+
+<Note>HMR is enabled by default when using Bun's full-stack development server.</Note>
+
+## `import.meta.hot` API Reference
+
+Bun implements a client-side HMR API modeled after [Vite's `import.meta.hot` API](https://vitejs.dev/guide/api-hmr.html). It can be checked for with `if (import.meta.hot)`, tree-shaking it in production.
+
+```ts title="index.ts" icon="/icons/typescript.svg"
+if (import.meta.hot) {
+  // HMR APIs are available.
+}
+```
+
+However, this check is often not needed as Bun will dead-code-eliminate calls to all of the HMR APIs in production builds.
+
+```ts title="index.ts" icon="/icons/typescript.svg"
+// This entire function call will be removed in production!
+import.meta.hot.dispose(() => {
+  console.log("dispose");
+});
+```
+
+<Warning>
+For this to work, Bun forces these APIs to be called without indirection. That means the following do not work:
+
+```ts title="index.ts" icon="/icons/typescript.svg"
+// INVALID: Assigning `hot` to a variable
+const hot = import.meta.hot;
+hot.accept();
+
+// INVALID: Assigning `import.meta` to a variable
+const meta = import.meta;
+meta.hot.accept();
+console.log(meta.hot.data);
+
+// INVALID: Passing to a function
+doSomething(import.meta.hot.dispose);
+
+// OK: The full phrase "import.meta.hot.<API>" must be called directly:
+import.meta.hot.accept();
+
+// OK: `data` can be passed to functions:
+doSomething(import.meta.hot.data);
+```
+
+</Warning>
+
+<Note>
+The HMR API is still a work in progress. Some features are missing. HMR can be disabled in `Bun.serve` by setting the development option to `{ hmr: false }`.
+</Note>
+
+## API Methods
+
+| Method             | Status | Notes                                                                 |
+| ------------------ | ------ | --------------------------------------------------------------------- |
+| `hot.accept()`     | ✅     | Indicate that a hot update can be replaced gracefully.                |
+| `hot.data`         | ✅     | Persist data between module evaluations.                              |
+| `hot.dispose()`    | ✅     | Add a callback function to run when a module is about to be replaced. |
+| `hot.invalidate()` | ❌     |                                                                       |
+| `hot.on()`         | ✅     | Attach an event listener                                              |
+| `hot.off()`        | ✅     | Remove an event listener from `on`.                                   |
+| `hot.send()`       | ❌     |                                                                       |
+| `hot.prune()`      | 🚧     | NOTE: Callback is currently never called.                             |
+| `hot.decline()`    | ✅     | No-op to match Vite's `import.meta.hot`                               |
+
+## import.meta.hot.accept()
+
+The `accept()` method indicates that a module can be hot-replaced. When called without arguments, it indicates that this module can be replaced simply by re-evaluating the file. After a hot update, importers of this module will be automatically patched.
+
+```ts title="index.ts" icon="/icons/typescript.svg"
+// index.ts
+import { getCount } from "./foo.ts";
+
+console.log("count is ", getCount());
+
+import.meta.hot.accept();
+
+export function getNegativeCount() {
+  return -getCount();
+}
+```
+
+This creates a hot-reloading boundary for all of the files that `index.ts` imports. That means whenever `foo.ts` or any of its dependencies are saved, the update will bubble up to `index.ts` will re-evaluate. Files that import `index.ts` will then be patched to import the new version of `getNegativeCount()`. If only `index.ts` is updated, only the one file will be re-evaluated, and the counter in `foo.ts` is reused.
+
+This may be used in combination with `import.meta.hot.data` to transfer state from the previous module to the new one.
+
+<Info>
+  When no modules call `import.meta.hot.accept()` (and there isn't React Fast Refresh or a plugin calling it for you),
+  the page will reload when the file updates, and a console warning shows which files were invalidated. This warning is
+  safe to ignore if it makes more sense to rely on full page reloads.
+</Info>
+
+### With callback
+
+When provided one callback, `import.meta.hot.accept` will function how it does in Vite. Instead of patching the importers of this module, it will call the callback with the new module.
+
+```ts title="index.ts" icon="/icons/typescript.svg"
+export const count = 0;
+
+import.meta.hot.accept(newModule => {
+  if (newModule) {
+    // newModule is undefined when SyntaxError happened
+    console.log("updated: count is now ", newModule.count);
+  }
+});
+```
+
+<Tip>
+  Prefer using `import.meta.hot.accept()` without an argument as it usually makes your code easier to understand.
+</Tip>
+
+### Accepting other modules
+
+```ts title="index.ts" icon="/icons/typescript.svg"
+import { count } from "./foo";
+
+import.meta.hot.accept("./foo", () => {
+  if (!newModule) return;
+
+  console.log("updated: count is now ", count);
+});
+```
+
+Indicates that a dependency's module can be accepted. When the dependency is updated, the callback will be called with the new module.
+
+### With multiple dependencies
+
+```ts title="index.ts" icon="/icons/typescript.svg"
+import.meta.hot.accept(["./foo", "./bar"], newModules => {
+  // newModules is an array where each item corresponds to the updated module
+  // or undefined if that module had a syntax error
+});
+```
+
+Indicates that multiple dependencies' modules can be accepted. This variant accepts an array of dependencies, where the callback will receive the updated modules, and `undefined` for any that had errors.
+
+## import.meta.hot.data
+
+`import.meta.hot.data` maintains state between module instances during hot replacement, enabling data transfer from previous to new versions. When `import.meta.hot.data` is written into, Bun will also mark this module as capable of self-accepting (equivalent of calling `import.meta.hot.accept()`).
+
+```jsx title="index.ts" icon="/icons/typescript.svg"
+import { createRoot } from "react-dom/client";
+import { App } from "./app";
+
+const root = (import.meta.hot.data.root ??= createRoot(elem));
+root.render(<App />); // re-use an existing root
+```
+
+In production, `data` is inlined to be `{}`, meaning it cannot be used as a state holder.
+
+<Tip>
+  The above pattern is recommended for stateful modules because Bun knows it can minify `{}.prop ??= value` into `value`
+  in production.
+</Tip>
+
+## import.meta.hot.dispose()
+
+Attaches an on-dispose callback. This is called:
+
+- Just before the module is replaced with another copy (before the next is loaded)
+- After the module is detached (removing all imports to this module, see `import.meta.hot.prune()`)
+
+```ts title="index.ts" icon="/icons/typescript.svg"
+const sideEffect = setupSideEffect();
+
+import.meta.hot.dispose(() => {
+  sideEffect.cleanup();
+});
+```
+
+<Warning>This callback is not called on route navigation or when the browser tab closes.</Warning>
+
+Returning a promise will delay module replacement until the module is disposed. All dispose callbacks are called in parallel.
+
+## import.meta.hot.prune()
+
+Attaches an on-prune callback. This is called when all imports to this module are removed, but the module was previously loaded.
+
+This can be used to clean up resources that were created when the module was loaded. Unlike `import.meta.hot.dispose()`, this pairs much better with `accept` and `data` to manage stateful resources. A full example managing a WebSocket:
+
+```ts title="index.ts" icon="/icons/typescript.svg"
+import { something } from "./something";
+
+// Initialize or re-use a WebSocket connection
+export const ws = (import.meta.hot.data.ws ??= new WebSocket(location.origin));
+
+// If the module's import is removed, clean up the WebSocket connection.
+import.meta.hot.prune(() => {
+  ws.close();
+});
+```
+
+<Info>
+  If `dispose` was used instead, the WebSocket would close and re-open on every hot update. Both versions of the code
+  will prevent page reloads when imported files are updated.
+</Info>
+
+## import.meta.hot.on() and off()
+
+`on()` and `off()` are used to listen for events from the HMR runtime. Event names are prefixed with a prefix so that plugins do not conflict with each other.
+
+```ts title="index.ts" icon="/icons/typescript.svg"
+import.meta.hot.on("bun:beforeUpdate", () => {
+  console.log("before a hot update");
+});
+```
+
+When a file is replaced, all of its event listeners are automatically removed.
+
+### Built-in events
+
+| Event                  | Emitted when                                                                                    |
+| ---------------------- | ----------------------------------------------------------------------------------------------- |
+| `bun:beforeUpdate`     | before a hot update is applied.                                                                 |
+| `bun:afterUpdate`      | after a hot update is applied.                                                                  |
+| `bun:beforeFullReload` | before a full page reload happens.                                                              |
+| `bun:beforePrune`      | before prune callbacks are called.                                                              |
+| `bun:invalidate`       | when a module is invalidated with `import.meta.hot.invalidate()`                                |
+| `bun:error`            | when a build or runtime error occurs                                                            |
+| `bun:ws:disconnect`    | when the HMR WebSocket connection is lost. This can indicate the development server is offline. |
+| `bun:ws:connect`       | when the HMR WebSocket connects or re-connects.                                                 |
+
+<Note>For compatibility with Vite, the above events are also available via `vite:*` prefix instead of `bun:*`.</Note>

package/docs/bundler/html-static.mdx

@@ -0,0 +1,386 @@
+---
+title: HTML & static sites
+description: Build static sites, landing pages, and web applications with Bun's bundler
+---
+
+Bun's bundler has first-class support for HTML. Build static sites, landing pages, and web applications with zero configuration. Just point Bun at your HTML file and it handles everything else.
+
+```html title="index.html" icon="file-code"
+<!doctype html>
+<html>
+  <head>
+    <link rel="stylesheet" href="./styles.css" />
+    <script src="./app.ts" type="module"></script>
+  </head>
+  <body>
+    <img src="./logo.png" />
+  </body>
+</html>
+```
+
+To get started, pass HTML files to `bun`.
+
+```bash terminal icon="terminal"
+bun ./index.html
+```
+
+```
+Bun v1.2.20
+ready in 6.62ms
+→ http://localhost:3000/
+Press h + Enter to show shortcuts
+```
+
+Bun's development server provides powerful features with zero configuration:
+
+- **Automatic Bundling** - Bundles and serves your HTML, JavaScript, and CSS
+- **Multi-Entry Support** - Handles multiple HTML entry points and glob entry points
+- **Modern JavaScript** - TypeScript & JSX support out of the box
+- **Smart Configuration** - Reads `tsconfig.json` for paths, JSX options, experimental decorators, and more
+- **Plugins** - Plugins for TailwindCSS and more
+- **ESM & CommonJS** - Use ESM and CommonJS in your JavaScript, TypeScript, and JSX files
+- **CSS Bundling & Minification** - Bundles CSS from `<link>` tags and `@import` statements
+- **Asset Management** - Automatic copying & hashing of images and assets; Rewrites asset paths in JavaScript, CSS, and HTML
+
+## Single Page Apps (SPA)
+
+When you pass a single `.html` file to Bun, Bun will use it as a fallback route for all paths. This makes it perfect for single page apps that use client-side routing:
+
+```bash terminal icon="terminal"
+bun index.html
+```
+
+```
+Bun v1.2.20
+ready in 6.62ms
+→ http://localhost:3000/
+Press h + Enter to show shortcuts
+```
+
+Your React or other SPA will work out of the box — no configuration needed. All routes like `/about`, `/users/123`, etc. will serve the same HTML file, letting your client-side router handle the navigation.
+
+```html title="index.html" icon="file-code"
+<!doctype html>
+<html>
+  <head>
+    <title>My SPA</title>
+    <script src="./app.tsx" type="module"></script>
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>
+```
+
+## Multi-page apps (MPA)
+
+Some projects have several separate routes or HTML files as entry points. To support multiple entry points, pass them all to `bun`:
+
+```bash terminal icon="terminal"
+bun ./index.html ./about.html
+```
+
+```txt
+Bun v1.2.20
+ready in 6.62ms
+→ http://localhost:3000/
+Routes:
+  / ./index.html
+  /about ./about.html
+Press h + Enter to show shortcuts
+```
+
+This will serve:
+
+- `index.html` at `/`
+- `about.html` at `/about`
+
+### Glob patterns
+
+To specify multiple files, you can use glob patterns that end in `.html`:
+
+```bash terminal icon="terminal"
+bun ./**/*.html
+```
+
+```
+Bun v1.2.20
+ready in 6.62ms
+→ http://localhost:3000/
+Routes:
+  / ./index.html
+  /about ./about.html
+Press h + Enter to show shortcuts
+```
+
+### Path normalization
+
+The base path is chosen from the longest common prefix among all the files.
+
+```bash terminal icon="terminal"
+bun ./index.html ./about/index.html ./about/foo/index.html
+```
+
+```
+Bun v1.2.20
+ready in 6.62ms
+→ http://localhost:3000/
+Routes:
+  / ./index.html
+  /about ./about/index.html
+  /about/foo ./about/foo/index.html
+Press h + Enter to show shortcuts
+```
+
+## JavaScript, TypeScript, and JSX
+
+Bun's transpiler natively implements JavaScript, TypeScript, and JSX support. Learn more about loaders in Bun.
+
+<Note>Bun's transpiler is also used at runtime.</Note>
+
+### ES Modules & CommonJS
+
+You can use ESM and CJS in your JavaScript, TypeScript, and JSX files. Bun will handle the transpilation and bundling automatically.
+
+There is no pre-build or separate optimization step. It's all done at the same time.
+
+Learn more about module resolution in Bun.
+
+## CSS
+
+Bun's CSS parser is also natively implemented (clocking in around 58,000 lines of Zig).
+
+It's also a CSS bundler. You can use `@import` in your CSS files to import other CSS files.
+
+For example:
+
+<CodeGroup>
+
+```css styles.css icon="file-code"
+@import "./abc.css";
+
+.container {
+  background-color: blue;
+}
+```
+
+```css abc.css
+body {
+  background-color: red;
+}
+```
+
+</CodeGroup>
+
+This outputs:
+
+```css
+body {
+  background-color: red;
+}
+
+.container {
+  background-color: blue;
+}
+```
+
+### Referencing local assets in CSS
+
+You can reference local assets in your CSS files.
+
+```css styles.css icon="file-code"
+body {
+  background-image: url("./logo.png");
+}
+```
+
+This will copy `./logo.png` to the output directory and rewrite the path in the CSS file to include a content hash.
+
+```css styles.css icon="file-code"
+body {
+  background-image: url("./logo-[ABC123].png");
+}
+```
+
+### Importing CSS in JavaScript
+
+To associate a CSS file with a JavaScript file, you can import it in your JavaScript file.
+
+```ts app.ts icon="/icons/typescript.svg"
+import "./styles.css";
+import "./more-styles.css";
+```
+
+This generates `./app.css` and `./app.js` in the output directory. All CSS files imported from JavaScript will be bundled into a single CSS file per entry point. If you import the same CSS file from multiple JavaScript files, it will only be included once in the output CSS file.
+
+## Plugins
+
+The dev server supports plugins.
+
+### Tailwind CSS
+
+To use TailwindCSS, install the `bun-plugin-tailwind` plugin:
+
+```bash terminal icon="terminal"
+# Or any npm client
+bun install --dev bun-plugin-tailwind
+```
+
+Then, add the plugin to your `bunfig.toml`:
+
+```toml title="bunfig.toml" icon="settings"
+[serve.static]
+plugins = ["bun-plugin-tailwind"]
+```
+
+Then, reference TailwindCSS in your HTML via `<link>` tag, `@import` in CSS, or import in JavaScript.
+
+<Tabs>
+  <Tab title="index.html">
+    ```html title="index.html" icon="file-code"
+    {/* 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>
+</Tabs>
+
+<Info>Only one of those are necessary, not all three.</Info>
+
+## Echo console logs from browser to terminal
+
+Bun's dev server supports streaming console logs from the browser to the terminal.
+
+To enable, pass the `--console` CLI flag.
+
+```bash terminal icon="terminal"
+bun ./index.html --console
+```
+
+```
+Bun v1.2.20
+ready in 6.62ms
+→ http://localhost:3000/
+Press h + Enter to show shortcuts
+```
+
+Each call to `console.log` or `console.error` will be broadcast to the terminal that started the server. This is useful to see errors from the browser in the same place you run your server. This is also useful for AI agents that watch terminal output.
+
+Internally, this reuses the existing WebSocket connection from hot module reloading to send the logs.
+
+## Edit files in the browser
+
+Bun's frontend dev server has support for Automatic Workspace Folders in Chrome DevTools, which lets you save edits to files in the browser.
+
+## Keyboard Shortcuts
+
+While the server is running:
+
+- `o + Enter` - Open in browser
+- `c + Enter` - Clear console
+- `q + Enter` (or `Ctrl+C`) - Quit server
+
+## Build for Production
+
+When you're ready to deploy, use `bun build` to create optimized production bundles:
+
+<Tabs>
+  <Tab title="CLI">
+    ```bash terminal icon="terminal"
+    bun build ./index.html --minify --outdir=dist
+    ```
+  </Tab>
+  <Tab title="API">
+    ```ts title="build.ts" icon="/icons/typescript.svg"
+    await Bun.build({
+      entrypoints: ["./index.html"],
+      outdir: "./dist",
+      minify: true,
+    });
+    ```
+  </Tab>
+</Tabs>
+
+<Warning>
+  Currently, plugins are only supported through `Bun.build`'s API or through `bunfig.toml` with the frontend dev server
+  - not yet supported in `bun build`'s CLI.
+</Warning>
+
+### Watch Mode
+
+You can run `bun build --watch` to watch for changes and rebuild automatically. This works nicely for library development.
+
+<Info>You've never seen a watch mode this fast.</Info>
+
+## Plugin API
+
+Need more control? Configure the bundler through the JavaScript API and use Bun's builtin `HTMLRewriter` to preprocess HTML.
+
+```ts title="build.ts" icon="/icons/typescript.svg"
+await Bun.build({
+  entrypoints: ["./index.html"],
+  outdir: "./dist",
+  minify: true,
+
+  plugins: [
+    {
+      // A plugin that makes every HTML tag lowercase
+      name: "lowercase-html-plugin",
+      setup({ onLoad }) {
+        const rewriter = new HTMLRewriter().on("*", {
+          element(element) {
+            element.tagName = element.tagName.toLowerCase();
+          },
+          text(element) {
+            element.replace(element.text.toLowerCase());
+          },
+        });
+
+        onLoad({ filter: /\.html$/ }, async args => {
+          const html = await Bun.file(args.path).text();
+
+          return {
+            // Bun's bundler will scan the HTML for <script> tags, <link rel="stylesheet"> tags, and other assets
+            // and bundle them automatically
+            contents: rewriter.transform(html),
+            loader: "html",
+          };
+        });
+      },
+    },
+  ],
+});
+```
+
+## What Gets Processed?
+
+Bun automatically handles all common web assets:
+
+- **Scripts** (`<script src>`) are run through Bun's JavaScript/TypeScript/JSX bundler
+- **Stylesheets** (`<link rel="stylesheet">`) are run through Bun's CSS parser & bundler
+- **Images** (`<img>`, `<picture>`) are copied and hashed
+- **Media** (`<video>`, `<audio>`, `<source>`) are copied and hashed
+- Any `<link>` tag with an `href` attribute pointing to a local file is rewritten to the new path, and hashed
+
+All paths are resolved relative to your HTML file, making it easy to organize your project however you want.
+
+<Warning>
+**This is a work in progress**
+- Need more plugins
+- Need more configuration options for things like asset handling
+- Need a way to configure CORS, headers, etc.
+
+If you want to submit a PR, most of the code is [here](https://github.com/oven-sh/bun/blob/main/src/bun.js/api/bun/html-rewriter.ts). You could even copy paste that file into your project and use it as a starting point.
+
+</Warning>
+
+## How this works
+
+This is a small wrapper around Bun's support for HTML imports in JavaScript.
+
+## Adding a backend to your frontend
+
+To add a backend to your frontend, you can use the "routes" option in `Bun.serve`.
+
+Learn more in the full-stack docs.