Add docs for html imports

bench/snippets/hash.mjs

@@ -0,0 +1,97 @@
+import { bench, run } from "../runner.mjs";
+
+// Can be strings or buffers.
+const shortStr = Buffer.from("abcd1234"); // 8 chars
+const longStr = Buffer.alloc(128 * 1024, "xABcDpQrStUvWxYz=-1]23]12312312][3123][123][");
+
+// Short string benchmarks
+
+bench("wyhash (short)", () => {
+  Bun.hash.wyhash(shortStr);
+});
+
+bench("adler32 (short)", () => {
+  Bun.hash.adler32(shortStr);
+});
+
+bench("crc32 (short)", () => {
+  Bun.hash.crc32(shortStr);
+});
+
+bench("cityHash32 (short)", () => {
+  Bun.hash.cityHash32(shortStr);
+});
+
+bench("cityHash64 (short)", () => {
+  Bun.hash.cityHash64(shortStr);
+});
+
+bench("xxHash32 (short)", () => {
+  Bun.hash.xxHash32(shortStr);
+});
+
+bench("xxHash64 (short)", () => {
+  Bun.hash.xxHash64(shortStr);
+});
+
+bench("xxHash3 (short)", () => {
+  Bun.hash.xxHash3(shortStr);
+});
+
+bench("murmur32v3 (short)", () => {
+  Bun.hash.murmur32v3(shortStr);
+});
+
+bench("murmur32v2 (short)", () => {
+  Bun.hash.murmur32v2(shortStr);
+});
+
+bench("murmur64v2 (short)", () => {
+  Bun.hash.murmur64v2(shortStr);
+});
+
+bench("wyhash (128 KB)", () => {
+  Bun.hash.wyhash(longStr);
+});
+
+bench("adler32 (128 KB)", () => {
+  Bun.hash.adler32(longStr);
+});
+
+bench("crc32 (128 KB)", () => {
+  Bun.hash.crc32(longStr);
+});
+
+bench("cityHash32 (128 KB)", () => {
+  Bun.hash.cityHash32(longStr);
+});
+
+bench("cityHash64 (128 KB)", () => {
+  Bun.hash.cityHash64(longStr);
+});
+
+bench("xxHash32 (128 KB)", () => {
+  Bun.hash.xxHash32(longStr);
+});
+
+bench("xxHash64 (128 KB)", () => {
+  Bun.hash.xxHash64(longStr);
+});
+
+bench("xxHash3 (128 KB)", () => {
+  Bun.hash.xxHash3(longStr);
+});
+
+bench("murmur32v3 (128 KB)", () => {
+  Bun.hash.murmur32v3(longStr);
+});
+
+bench("murmur32v2 (128 KB)", () => {
+  Bun.hash.murmur32v2(longStr);
+});
+
+bench("murmur64v2 (128 KB)", () => {
+  Bun.hash.murmur64v2(longStr);
+});
+
+run();

docs/bundler/fullstack.md

@@ -0,0 +1,152 @@
+As of Bun v1.1.44, we've added initial support for bundling frontend apps directly in Bun's HTTP server: `Bun.serve()`. Run your frontend and backend in the same app with no extra steps.
+
+To get started, import your HTML files and pass them to the `static` option in `Bun.serve()`.
+
+```ts
+import dashboard from "./dashboard.html";
+import homepage from "./index.html";
+
+Bun.serve({
+  // Add HTML imports to `static`
+  static: {
+    // Bundle & route index.html to "/"
+    "/": homepage,
+    // Bundle & route dashboard.html to "/dashboard"
+    "/dashboard": dashboard,
+  },
+
+  // Enable development mode for:
+  // - Detailed error messages
+  // - Rebuild on request
+  development: true,
+
+  // Handle API requests
+  async fetch(req) {
+    if (req.url.endsWith("/api/users")) {
+      const users = await sql`SELECT * FROM users`;
+      return Response.json(users);
+    }
+
+    // Return 404 for unmatched routes
+    return new Response("Not Found", { status: 404 });
+  },
+});
+```
+
+You'll need to run your app with `bun --experimental-html` to enable this feature:
+
+```bash
+$ bun --experimental-html run app.ts
+```
+
+## HTML imports are routes
+
+The web starts with HTML, and so does Bun's fullstack dev server.
+
+To specify entrypoints to your frontend, import HTML files into your JavaScript/TypeScript/TSX/JSX files.
+
+```ts
+import dashboard from "./dashboard.html";
+import homepage from "./index.html";
+```
+
+These HTML files are used as routes in Bun's dev server you can pass to `Bun.serve()`.
+
+```ts
+Bun.serve({
+  static: {
+    "/": homepage,
+    "/dashboard": dashboard,
+  }
+
+  fetch(req) {
+    // ... api requests
+  },
+});
+```
+
+When you make a request to `/dashboard` or `/`, Bun automatically bundles the `<script>` and `<link>` tags in the HTML files, exposes them as static routes, and serves the result.
+
+### Development mode
+
+When building locally, enable development mode by setting `development: true` in `Bun.serve()`.
+
+```js-diff
+import homepage from "./index.html";
+import dashboard from "./dashboard.html";
+
+Bun.serve({
+  static: {
+    "/": homepage,
+    "/dashboard": dashboard,
+  }
+
++ development: true,
+
+  fetch(req) {
+    // ... api requests
+  },
+});
+```
+
+When `development` is `true`, Bun will:
+
+- Include the `SourceMap` header in the response so that devtools can show the original source code
+- Disable minification
+- Re-bundle assets on each request to a .html file
+
+#### Production mode
+
+When serving your app in production, set `development: false` in `Bun.serve()`.
+
+- Enable in-memory caching of bundled assets. Bun will bundle assets lazily on the first request to an `.html` file, and cache the result in memory until the server restarts.
+- Enables `Cache-Control` headers and `ETag` headers
+- Minifies JavaScript/TypeScript/TSX/JSX files
+
+## How this works
+
+Bun uses [`HTMLRewriter`](/docs/api/html-rewriter) to scan for `<script>` and `<link>` tags in HTML files, uses them as entrypoints for [Bun's bundler](/docs/bundler), generates an optimized bundle for the JavaScript/TypeScript/TSX/JSX and CSS files, and serves the result.
+
+1. **`<script>` processing**
+
+   - Transpiles TypeScript, JSX, and TSX in `<script>` tags
+   - Bundles imported dependencies
+   - Generates sourcemaps for debugging
+   - Minifies when `development` is not `true` in `Bun.serve()`
+
+   ```html
+   <script type="module" src="./counter.tsx"></script>
+   ```
+
+2. **`<link>` processing**
+
+   - Processes CSS imports and `<link>` tags
+   - Concatenates CSS files
+   - Rewrites `url` and asset paths to include content-addressable hashes in URLs
+
+   ```html
+   <link rel="stylesheet" href="./styles.css" />
+   ```
+
+3. **`<img>` & asset processing**
+
+   - Links to assets are rewritten to include content-addressable hashes in URLs
+   - Small assets in CSS files are inlined into `data:` URLs, reducing the total number of HTTP requests sent over the wire
+
+4. **Rewrite HTML**
+
+   - Combines all `<script>` tags into a single `<script>` tag with a content-addressable hash in the URL
+   - Combines all `<link>` tags into a single `<link>` tag with a content-addressable hash in the URL
+   - Outputs a new HTML file
+
+5. **Serve**
+
+   - All the output files from the bundler are exposed as static routes, using the same mechanism internally as when you pass a `Response` object to [`static` in `Bun.serve()`](/docs/api/http#static-routes).
+
+This works similarly to how [`Bun.build` processes HTML files](/docs/bundler/html).
+
+## This is a work in progress
+
+- Client-side hot reloading isn't wired up yet. It will be in the future.
+- This doesn't support `bun build` yet. It also will in the future.
+- We haven't figured out plugins yet. This probably will live in `bunfig.toml` with the same API as in `Bun.build` otherwise.

docs/nav.ts

@@ -217,6 +217,9 @@ export default {
     page("bundler/html", "HTML", {
       description: `Bundle html files with Bun's native bundler.`,
     }),
+    page("bundler/fullstack", "Fullstack Dev Server", {
+      description: "Serve your frontend and backend from the same app with Bun's dev server.",
+    }),
     page("bundler/loaders", "Loaders", {
       description: "Bun's built-in loaders for the bundler and runtime",
     }),