npm - bun-types - Versions diffs - 1.3.2-canary.20251105T140650 → 1.3.2 - Mend

bun-types 1.3.2-canary.20251105T140650 → 1.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (370) hide show

package/docs/bundler/{html.md → html-static.mdx} RENAMED Viewed

@@ -1,6 +1,11 @@
+---
+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#index.html
+```html title="index.html" icon="file-code"
 <!doctype html>
 <html>
   <head>
@@ -15,7 +20,16 @@ Bun's bundler has first-class support for HTML. Build static sites, landing page
 To get started, pass HTML files to `bun`.
-{% bunDevServerTerminal alt="bun ./index.html" path="./index.html" routes="" /%}
+```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:
@@ -26,19 +40,26 @@ Bun's development server provides powerful features with zero configuration:
 - **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
+- **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:
+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
+```
-{% bunDevServerTerminal alt="bun index.html" path="index.html" routes="" /%}
+```
+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#index.html
+```html title="index.html" icon="file-code"
 <!doctype html>
 <html>
   <head>
@@ -53,9 +74,21 @@ Your React or other SPA will work out of the box — no configuration needed. Al
 ## 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`
+Some projects have several separate routes or HTML files as entry points. To support multiple entry points, pass them all to `bun`:
-{% bunDevServerTerminal alt="bun ./index.html ./about.html" path="./index.html ./about.html" routes="[{\"path\": \"/\", \"file\": \"./index.html\"}, {\"path\": \"/about\", \"file\": \"./about.html\"}]" /%}
+```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:
@@ -66,19 +99,44 @@ This will serve:
 To specify multiple files, you can use glob patterns that end in `.html`:
-{% bunDevServerTerminal alt="bun ./**/*.html" path="./**/*.html" routes="[{\"path\": \"/\", \"file\": \"./index.html\"}, {\"path\": \"/about\", \"file\": \"./about.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.
-{% bunDevServerTerminal alt="bun ./index.html ./about/index.html ./about/foo/index.html" path="./index.html ./about/index.html ./about/foo/index.html" routes="[{\"path\": \"/\", \"file\": \"./index.html\"}, {\"path\": \"/about\", \"file\": \"./about/index.html\"}, {\"path\": \"/about/foo\", \"file\": \"./about/foo/index.html\"}]" /%}
+```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](/docs/bundler/loaders).
+Bun's transpiler natively implements JavaScript, TypeScript, and JSX support. Learn more about loaders in Bun.
-Bun's transpiler is also used at runtime.
+<Note>Bun's transpiler is also used at runtime.</Note>
 ### ES Modules & CommonJS
@@ -86,7 +144,7 @@ You can use ESM and CJS in your JavaScript, TypeScript, and JSX files. Bun will
 There is no pre-build or separate optimization step. It's all done at the same time.
-Learn more about [module resolution in Bun](/docs/runtime/modules).
+Learn more about module resolution in Bun.
 ## CSS
@@ -96,7 +154,9 @@ It's also a CSS bundler. You can use `@import` in your CSS files to import other
 For example:
-```css#styles.css
+<CodeGroup>
+```css styles.css icon="file-code"
 @import "./abc.css";
 .container {
@@ -104,15 +164,17 @@ For example:
 }
 ```
-```css#abc.css
+```css abc.css
 body {
   background-color: red;
 }
 ```
+</CodeGroup>
 This outputs:
-```css#styles.css
+```css
 body {
   background-color: red;
 }
@@ -126,7 +188,7 @@ body {
 You can reference local assets in your CSS files.
-```css#styles.css
+```css styles.css icon="file-code"
 body {
   background-image: url("./logo.png");
 }
@@ -134,7 +196,7 @@ body {
 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
+```css styles.css icon="file-code"
 body {
   background-image: url("./logo-[ABC123].png");
 }
@@ -144,7 +206,7 @@ body {
 To associate a CSS file with a JavaScript file, you can import it in your JavaScript file.
-```ts#app.ts
+```ts app.ts icon="/icons/typescript.svg"
 import "./styles.css";
 import "./more-styles.css";
 ```
@@ -159,84 +221,57 @@ The dev server supports plugins.
 To use TailwindCSS, install the `bun-plugin-tailwind` plugin:
-```bash
+```bash terminal icon="terminal"
 # Or any npm client
-$ bun install --dev bun-plugin-tailwind
+bun install --dev bun-plugin-tailwind
 ```
 Then, add the plugin to your `bunfig.toml`:
-```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.
-{% codetabs %}
-```html#index.html
-<!-- Reference TailwindCSS in your HTML -->
-<link rel="stylesheet" href="tailwindcss" />
-```
+Then, reference TailwindCSS in your HTML via `<link>` tag, `@import` in CSS, or import in JavaScript.
-```css#styles.css
-/* Import TailwindCSS in your CSS */
-@import "tailwindcss";
-```
-```ts#app.ts
-/* Import TailwindCSS in your JavaScript */
-import "tailwindcss";
-```
+<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>
-{% /codetabs %}
+<Info>Only one of those are necessary, not all three.</Info>
-Only one of those are necessary, not all three.
-### Echo console logs from browser to terminal
+## 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.
-{% bunDevServerTerminal alt="bun ./index.html --console" path="./index.html --console" routes="" /%}
-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](https://chromium.googlesource.com/devtools/devtools-frontend/+/main/docs/ecosystem/automatic_workspace_folders.md) in Chrome DevTools, which lets you save edits to files in the browser.
-{% image src="/images/bun-chromedevtools.gif" alt="Bun's frontend dev server has support for Automatic Workspace Folders in Chrome DevTools, which lets you save edits to files in the browser." /%}
-{% details summary="How it works" %}
-Bun's dev server automatically adds a `/.well-known/appspecific/com.chrome.devtools.json` route to the server.
-This route returns a JSON object with the following shape:
+```bash terminal icon="terminal"
+bun ./index.html --console
+```
-```json
-{
-  "workspace": {
-    "root": "/path/to/your/project",
-    "uuid": "a-unique-identifier-for-this-workspace"
-  }
-}
+```
+Bun v1.2.20
+ready in 6.62ms
+→ http://localhost:3000/
+Press h + Enter to show shortcuts
 ```
-For security reasons, this is only enabled when:
+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.
-1. The request is coming from localhost, 127.0.0.1, or ::1.
-2. Hot Module Reloading is enabled.
-3. The `chromeDevToolsAutomaticWorkspaceFolders` flag is set to `true` or `undefined`.
-4. There are no other routes that match the request.
+Internally, this reuses the existing WebSocket connection from hot module reloading to send the logs.
-You can disable this by passing `development: { chromeDevToolsAutomaticWorkspaceFolders: false }` in `Bun.serve`'s options.
+## Edit files in the browser
-{% /details %}
+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
@@ -244,45 +279,45 @@ While the server is running:
 - `o + Enter` - Open in browser
 - `c + Enter` - Clear console
-- `q + Enter` (or Ctrl+C) - Quit server
+- `q + Enter` (or `Ctrl+C`) - Quit server
 ## Build for Production
 When you're ready to deploy, use `bun build` to create optimized production bundles:
-{% codetabs %}
-```bash#CLI
-$ bun build ./index.html --minify --outdir=dist
-```
-```ts#API
-Bun.build({
-  entrypoints: ["./index.html"],
-  outdir: "./dist",
-  minify: {
-    whitespace: true,
-    identifiers: true,
-    syntax: true,
-  }
-});
-```
-{% /codetabs %}
-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.
+<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.
-You've never seen a watch mode this fast.
+<Info>You've never seen a watch mode this fast.</Info>
-### Plugin API
+## Plugin API
 Need more control? Configure the bundler through the JavaScript API and use Bun's builtin `HTMLRewriter` to preprocess HTML.
-```ts
+```ts title="build.ts" icon="/icons/typescript.svg"
 await Bun.build({
   entrypoints: ["./index.html"],
   outdir: "./dist",
@@ -322,28 +357,30 @@ await Bun.build({
 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
+- **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.
-## This is a work in progress
+<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/js/internal/html.ts). You could even copy paste that file into your project and use it as a starting point.
+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
+## Adding a backend to your frontend
-To add a backend to your frontend, you can use the `"routes"` option in `Bun.serve`.
+To add a backend to your frontend, you can use the "routes" option in `Bun.serve`.
-Learn more in [the full-stack docs](/docs/bundler/fullstack).
+Learn more in the full-stack docs.