diff --git a/docs/api/http.md b/docs/api/http.md index bf8ff9861f..4e4fd43e62 100644 --- a/docs/api/http.md +++ b/docs/api/http.md @@ -61,6 +61,7 @@ Routes in `Bun.serve()` receive a `BunRequest` (which extends [`Request`](https: // Simplified for brevity interface BunRequest extends Request { params: Record; + readonly cookies: CookieMap; } ``` @@ -934,6 +935,83 @@ const server = Bun.serve({ Returns `null` for closed requests or Unix domain sockets. +## Working with Cookies + +Bun provides a built-in API for working with cookies in HTTP requests and responses. The `BunRequest` object includes a `cookies` property that provides a `CookieMap` for easily accessing and manipulating cookies. When using `routes`, `Bun.serve()` automatically tracks `request.cookies.set` and applies them to the response. + +### Reading cookies + +Read cookies from incoming requests using the `cookies` property on the `BunRequest` object: + +```ts +Bun.serve({ + routes: { + "/profile": req => { + // Access cookies from the request + const userId = req.cookies.get("user_id"); + const theme = req.cookies.get("theme") || "light"; + + return Response.json({ + userId, + theme, + message: "Profile page", + }); + }, + }, +}); +``` + +### Setting cookies + +To set cookies, use the `set` method on the `CookieMap` from the `BunRequest` object. + +```ts +Bun.serve({ + routes: { + "/login": req => { + const cookies = req.cookies; + + // Set a cookie with various options + cookies.set("user_id", "12345", { + maxAge: 60 * 60 * 24 * 7, // 1 week + httpOnly: true, + secure: true, + path: "/", + }); + + // Add a theme preference cookie + cookies.set("theme", "dark"); + + // Modified cookies from the request are automatically applied to the response + return new Response("Login successful"); + }, + }, +}); +``` + +`Bun.serve()` automatically tracks modified cookies from the request and applies them to the response. + +### Deleting cookies + +To delete a cookie, use the `delete` method on the `request.cookies` (`CookieMap`) object: + +```ts +Bun.serve({ + routes: { + "/logout": req => { + // Delete the user_id cookie + req.cookies.delete("user_id", { + path: "/", + }); + + return new Response("Logged out successfully"); + }, + }, +}); +``` + +Deleted cookies become a `Set-Cookie` header on the response with the `maxAge` set to `0` and an empty `value`. + ## Server Metrics ### server.pendingRequests and server.pendingWebSockets diff --git a/docs/nav.ts b/docs/nav.ts index c83130021a..c0e93ee94c 100644 --- a/docs/nav.ts +++ b/docs/nav.ts @@ -364,7 +364,7 @@ export default { page("api/console", "Console", { description: `Bun implements a Node.js-compatible \`console\` object with colorized output and deep pretty-printing.`, }), // "`Node-API`"), - page("api/cookies", "Cookies", { + page("api/cookie", "Cookie", { description: "Bun's native Cookie API simplifies working with HTTP cookies.", }), // "`Node-API`"), page("api/ffi", "FFI", {