Introduce bun ./index.html (#16993)

oven-sh · Feb 3, 2025 · 1ea14f4 · 1ea14f4
1 parent ec75115
commit 1ea14f4
Show file tree

Hide file tree

Showing 14 changed files with 1,298 additions and 60 deletions.
diff --git a/docs/bundler/fullstack.md b/docs/bundler/fullstack.md
@@ -1,6 +1,6 @@
-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.
+Using `Bun.serve()`'s `static` option, you can 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()`.
+To get started, import HTML files and pass them to the `static` option in `Bun.serve()`.
 
 ```ts
 import dashboard from "./dashboard.html";
@@ -33,7 +33,7 @@ const server = Bun.serve({
   },
 });
 
-console.log(`Listening on ${server.url}`)
+console.log(`Listening on ${server.url}`);
 ```
 
 ```bash
@@ -211,6 +211,7 @@ For example, enable TailwindCSS on your routes by installing and adding the `bun
 ```sh
 $ bun add bun-plugin-tailwind
 ```
+
 ```toml#bunfig.toml
 [serve.static]
 plugins = ["bun-plugin-tailwind"]

diff --git a/docs/bundler/html.md b/docs/bundler/html.md
@@ -1,4 +1,4 @@
-As of Bun v1.1.43, Bun's bundler now 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.
+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
 <!doctype html>
@@ -13,45 +13,221 @@ As of Bun v1.1.43, Bun's bundler now has first-class support for HTML. Build sta
 </html>
 ```
 
-One command is all you need (won't be experimental after Bun v1.2):
+To get started, pass HTML files to `bun`.
+
+{% bunDevServerTerminal alt="bun ./index.html" path="./index.html" routes="" /%}
+
+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:
+
+{% bunDevServerTerminal alt="bun index.html" path="index.html" routes="" /%}
+
+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
+<!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`
+
+{% bunDevServerTerminal alt="bun ./index.html ./about.html" path="./index.html ./about.html" routes="[{\"path\": \"/\", \"file\": \"./index.html\"}, {\"path\": \"/about\", \"file\": \"./about.html\"}]" /%}
+
+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`:
+
+{% bunDevServerTerminal alt="bun ./**/*.html" path="./**/*.html" routes="[{\"path\": \"/\", \"file\": \"./index.html\"}, {\"path\": \"/about\", \"file\": \"./about.html\"}]" /%}
+
+### 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\"}]" /%}
+
+## 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 is also used at runtime.
+
+### 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](/docs/runtime/modules).
+
+## 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:
+
+```css#styles.css
+@import "./abc.css";
+
+.container {
+  background-color: blue;
+}
+```
+
+```css#abc.css
+body {
+  background-color: red;
+}
+```
+
+This outputs:
+
+```css#styles.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
+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
+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
+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, add the plugin to your `bunfig.toml`:
+
+```toml
+[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" />
+```
+
+```css#styles.css
+/* Import TailwindCSS in your CSS */
+@import "tailwindcss";
+```
+
+```ts#app.ts
+/* Import TailwindCSS in your JavaScript */
+import "tailwindcss";
+```
+
+{% /codetabs %}
+
+Only one of those are necessary, not all three.
+
+## 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:
 
 {% codetabs %}
 
 ```bash#CLI
-$ bun build ./index.html --outdir=dist
+$ bun build ./index.html --minify --outdir=dist
 ```
 
 ```ts#API
 Bun.build({
   entrypoints: ["./index.html"],
   outdir: "./dist",
+  minify: {
+    whitespace: true,
+    identifiers: true,
+    syntax: true,
+  }
 });
 ```
 
 {% /codetabs %}
 
-Bun automatically:
+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.
 
-- Bundles, tree-shakes, and optimizes your JavaScript, JSX and TypeScript
-- Bundles and optimizes your CSS
-- Copies & hashes images and other assets
-- Updates all references to local files or packages in your HTML
+### Watch Mode
 
-## Zero Config, Maximum Performance
-
-The HTML bundler is enabled by default after Bun v1.2+. Drop in your existing HTML files and Bun will handle:
-
-- **TypeScript & JSX** - Write modern JavaScript for browsers without the setup
-- **CSS** - Bundle CSS stylesheets directly from `<link rel="stylesheet">` or `@import`
-- **Images & Assets** - Automatic copying & hashing & rewriting of assets in JavaScript, CSS, and HTML
-
-## Watch mode
-
-You can run `bun build --watch` to watch for changes and rebuild automatically.
+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.
 
-## Plugin API
+### Plugin API
 
 Need more control? Configure the bundler through the JavaScript API and use Bun's builtin `HTMLRewriter` to preprocess HTML.
 
@@ -102,3 +278,22 @@ Bun automatically handles all common web assets:
 - 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
+
+- No HMR support yet
+- 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.
+
+## 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 `"static"` option in `Bun.serve`.
+
+Learn more in [the full-stack docs](/docs/bundler/fullstack).
diff --git a/docs/nav.ts b/docs/nav.ts
@@ -214,7 +214,7 @@ export default {
     page("bundler", "`Bun.build`", {
       description: "Bundle code for consumption in the browser with Bun's native bundler.",
     }),
-    page("bundler/html", "HTML", {
+    page("bundler/html", "Frontend & static sites", {
       description: `Bundle html files with Bun's native bundler.`,
     }),
     page("bundler/fullstack", "Fullstack Dev Server", {

diff --git a/src/bun.js/api/server.zig b/src/bun.js/api/server.zig
@@ -1110,7 +1110,7 @@ pub const ServerConfig = struct {
         var port = args.address.tcp.port;
 
         if (arguments.vm.transpiler.options.transform_options.origin) |origin| {
-            args.base_uri = origin;
+            args.base_uri = try bun.default_allocator.dupeZ(u8, origin);
         }
 
         defer {
@@ -1150,16 +1150,15 @@ pub const ServerConfig = struct {
 
                 while (try iter.next()) |key| {
                     const path, const is_ascii = key.toOwnedSliceReturningAllASCII(bun.default_allocator) catch bun.outOfMemory();
+                    errdefer bun.default_allocator.free(path);
 
                     const value = iter.value;
 
-                    if (path.len == 0 or path[0] != '/') {
-                        bun.default_allocator.free(path);
+                    if (path.len == 0 or (path[0] != '/' and path[0] != '*')) {
                         return global.throwInvalidArguments("Invalid static route \"{s}\". path must start with '/'", .{path});
                     }
 
                     if (!is_ascii) {
-                        bun.default_allocator.free(path);
                         return global.throwInvalidArguments("Invalid static route \"{s}\". Please encode all non-ASCII characters in the path.", .{path});
                     }
 
@@ -1219,6 +1218,9 @@ pub const ServerConfig = struct {
 
                 if (sliced.len > 0) {
                     defer sliced.deinit();
+                    if (args.base_uri.len > 0) {
+                        bun.default_allocator.free(@constCast(args.base_uri));
+                    }
                     args.base_uri = bun.default_allocator.dupe(u8, sliced.slice()) catch unreachable;
                 }
             }
@@ -1413,6 +1415,8 @@ pub const ServerConfig = struct {
                 const protocol: string = if (args.ssl_config != null) "https" else "http";
                 const hostname = args.base_url.hostname;
                 const needsBrackets: bool = strings.isIPV6Address(hostname) and hostname[0] != '[';
+                const original_base_uri = args.base_uri;
+                defer bun.default_allocator.free(@constCast(original_base_uri));
                 if (needsBrackets) {
                     args.base_uri = (if ((port == 80 and args.ssl_config == null) or (port == 443 and args.ssl_config != null))
                         std.fmt.allocPrint(bun.default_allocator, "{s}://[{s}]/{s}", .{
@@ -7449,8 +7453,30 @@ pub fn NewServer(comptime NamespaceType: type, comptime ssl_enabled_: bool, comp
             if (this.dev_server) |dev| {
                 dev.attachRoutes(this) catch bun.outOfMemory();
             } else {
-                bun.assert(this.config.onRequest != .zero);
-                app.any("/*", *ThisServer, this, onRequest);
+                const @"has /*" = brk: {
+                    for (this.config.static_routes.items) |route| {
+                        if (strings.eqlComptime(route.path, "/*")) {
+                            break :brk true;
+                        }
+                    }
+
+                    break :brk false;
+                };
+
+                // "/*" routes are added backwards, so if they have a static route, it will never be matched
+                // so we need to check for that first
+                if (!@"has /*") {
+                    bun.assert(this.config.onRequest != .zero);
+                    app.any("/*", *ThisServer, this, onRequest);
+                } else if (this.config.onRequest != .zero) {
+                    app.post("/*", *ThisServer, this, onRequest);
+                    app.put("/*", *ThisServer, this, onRequest);
+                    app.patch("/*", *ThisServer, this, onRequest);
+                    app.delete("/*", *ThisServer, this, onRequest);
+                    app.options("/*", *ThisServer, this, onRequest);
+                    app.trace("/*", *ThisServer, this, onRequest);
+                    app.connect("/*", *ThisServer, this, onRequest);
+                }
             }
         }
 

diff --git a/src/bun.js/api/server/HTMLBundle.zig b/src/bun.js/api/server/HTMLBundle.zig
@@ -68,6 +68,7 @@ pub const HTMLBundleRoute = struct {
     }
 
     pub fn init(html_bundle: *HTMLBundle) *HTMLBundleRoute {
+        html_bundle.ref();
         return HTMLBundleRoute.new(.{
             .html_bundle = html_bundle,
             .pending_responses = .{},