diff options
Diffstat (limited to 'docs/guides/http')
-rw-r--r-- | docs/guides/http/hot.md | 55 | ||||
-rw-r--r-- | docs/guides/http/index.json | 4 | ||||
-rw-r--r-- | docs/guides/http/simple.md | 18 | ||||
-rw-r--r-- | docs/guides/http/stream-file.md | 48 | ||||
-rw-r--r-- | docs/guides/http/tls.md | 30 |
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")], + }, +}); +``` |