aboutsummaryrefslogtreecommitdiff
path: root/docs/guides/http
diff options
context:
space:
mode:
Diffstat (limited to 'docs/guides/http')
-rw-r--r--docs/guides/http/hot.md55
-rw-r--r--docs/guides/http/index.json4
-rw-r--r--docs/guides/http/simple.md18
-rw-r--r--docs/guides/http/stream-file.md48
-rw-r--r--docs/guides/http/tls.md30
5 files changed, 155 insertions, 0 deletions
diff --git a/docs/guides/http/hot.md b/docs/guides/http/hot.md
new file mode 100644
index 000000000..c033e5be5
--- /dev/null
+++ b/docs/guides/http/hot.md
@@ -0,0 +1,55 @@
+---
+name: Hot reload an HTTP server
+---
+
+Bun supports the [`--hot`](/docs/runtime/hot#hot-mode) flag to run a file with hot reloading enabled. When any module or file changes, Bun re-runs the file.
+
+```sh
+bun --hot run index.ts
+```
+
+---
+
+To avoid re-running `Bun.serve()` during `--hot` reloads, you should assign the `Server` instance as a property of `globalThis`. The `globalThis` object survives hot reloads.
+
+```ts
+import { type Serve, type Server } from "bun";
+
+// make TypeScript happy
+declare global {
+ var server: Server;
+}
+
+// define server parameters
+const serveOptions: Serve = {
+ port: 3000,
+ fetch(req) {
+ return new Response(`Hello world`);
+ },
+};
+
+if (!globalThis.server) {
+ globalThis.server = Bun.serve(serveOptions);
+} else {
+ globalThis.server.reload(serveOptions);
+}
+```
+
+---
+
+To avoid manually calling `server.reload()`, you can use start a server with Bun's [object syntax](/docs/runtime/hot#http-servers). If you `export default` a plain object with a `fetch` handler defined, then run this file with Bun, Bun will start an HTTP server as if you'd passed this object into `Bun.serve()`.
+
+With this approach, Bun automatically reloads the server when reloads happen.
+
+See [HTTP > Hot Reloading](<[/docs/api/http](https://bun.sh/docs/api/http#hot-reloading)>) for full docs.
+
+```ts
+import { type Serve } from "bun";
+
+export default {
+ port: 3000,
+ fetch(req) {
+ return new Response(`Hello world`);
+ },
+} satisfies Serve;
+```
diff --git a/docs/guides/http/index.json b/docs/guides/http/index.json
new file mode 100644
index 000000000..d018e1bdd
--- /dev/null
+++ b/docs/guides/http/index.json
@@ -0,0 +1,4 @@
+{
+ "name": "HTTP",
+ "description": "A collection of guides for building HTTP servers with Bun"
+}
diff --git a/docs/guides/http/simple.md b/docs/guides/http/simple.md
new file mode 100644
index 000000000..be5147541
--- /dev/null
+++ b/docs/guides/http/simple.md
@@ -0,0 +1,18 @@
+---
+name: Write a simple HTTP server
+---
+
+This starts an HTTP server listening on port `3000`. It responds to all requests with a `Response` with status `200` and body `"Welcome to Bun!"`.
+
+See [`Bun.serve`](/docs/api/http) for details.
+
+```ts
+const server = Bun.serve({
+ port: 3000,
+ fetch(request) {
+ return new Response("Welcome to Bun!");
+ },
+});
+
+console.log(`Listening on localhost:\${server.port}`);
+```
diff --git a/docs/guides/http/stream-file.md b/docs/guides/http/stream-file.md
new file mode 100644
index 000000000..66c8c247b
--- /dev/null
+++ b/docs/guides/http/stream-file.md
@@ -0,0 +1,48 @@
+---
+name: Stream a file as an HTTP Response
+---
+
+This snippet reads a file from disk using [`Bun.file()`](/docs/api/file-io#reading-files-bun-file). This returns a `BunFile` instance, which can be passed directly into the `new Response` constructor.
+
+```ts
+const path = "/path/to/file.txt";
+const file = Bun.file(path);
+const resp = new Response(file);
+```
+
+---
+
+The `Content-Type` is read from the file and automatically set on the `Response`.
+
+```ts
+new Response(Bun.file("./package.json")).headers.get("Content-Type");
+// => application/json;charset=utf-8
+
+new Response(Bun.file("./test.txt")).headers.get("Content-Type");
+// => text/plain;charset=utf-8
+
+new Response(Bun.file("./index.tsx")).headers.get("Content-Type");
+// => text/javascript;charset=utf-8
+
+new Response(Bun.file("./img.png")).headers.get("Content-Type");
+// => image/png
+```
+
+---
+
+Putting it all together with [`Bun.serve()`](/docs/api/http#serving-files-bun-serve).
+
+```ts
+// static file server
+Bun.serve({
+ async fetch(req) {
+ const path = new URL(req.url).pathname;
+ const file = Bun.file(path);
+ return new Response(file);
+ },
+});
+```
+
+---
+
+See [Docs > API > File I/O](/docs/api/file-io#writing-files-bun-write) for complete documentation of `Bun.write()`.
diff --git a/docs/guides/http/tls.md b/docs/guides/http/tls.md
new file mode 100644
index 000000000..a7e59dfea
--- /dev/null
+++ b/docs/guides/http/tls.md
@@ -0,0 +1,30 @@
+---
+name: Configure TLS on an HTTP server
+---
+
+Set the `tls` key to configure TLS. Both `key` and `cert` are required. The `key` should be the contents of your private key; `cert` should be the contents of your issued certificate. Use [`Bun.file()`](/docs/api/file-io#reading-files-bun-file) to read the contents.
+
+```ts
+const server = Bun.serve({
+ fetch: (request) => new Response("Welcome to Bun!"),
+ tls: {
+ cert: Bun.file("cert.pem"),
+ key: Bun.file("key.pem"),
+ },
+});
+```
+
+---
+
+By default Bun trusts the default Mozilla-curated list of well-known root CAs. To override this list, pass an array of certificates as `ca`.
+
+```ts
+const server = Bun.serve({
+ fetch: (request) => new Response("Welcome to Bun!"),
+ tls: {
+ cert: Bun.file("cert.pem"),
+ key: Bun.file("key.pem"),
+ ca: [Bun.file("ca1.pem"), Bun.file("ca2.pem")],
+ },
+});
+```