> ## Documentation Index
> Fetch the complete documentation index at: https://quickbutik.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Server-side rendering
> Use @quickbutik/kit on Node, Hono, Express, Astro and Cloudflare Workers with per-request cookie storage.
The root entry runs the same on a server as in a browser. Server rendering keeps your catalog indexable and lets the server and the browser share **one cart** through cookies.
## One config, one client per request
A server serves many shoppers, so a client must be bound to **this request's cookies**. Keep one long-lived config and bind a client per request with `withStorage()`:
```ts src/kit.server.ts theme={null}
import { createShopkitClient, createRequestCookieStorage } from "@quickbutik/kit"
const base = { publishableKey: process.env.QUICKBUTIK_PUBLISHABLE_KEY! }
export function kitFor(request: Request, setCookies: string[]) {
return createShopkitClient(base).withStorage(
createRequestCookieStorage(request, {
collect: setCookies, // writes become Set-Cookie strings
attributes: { secure: true, sameSite: "lax" }, // no ambient `location` on a server: pass secure explicitly
}),
)
}
```
`createRequestCookieStorage(source, options)` reads cookies straight off a `Request`, a `Headers` object or a raw `Cookie` header string. With `collect`, every write is appended as a serialized `Set-Cookie` string for you to attach to the response. `withStorage()` returns a copy of the client bound to that storage.
**Without per-request storage, the server forgets the cart.** A client with no cookie accessor on a server resolves to memory storage, so `cart.add()` creates a new cart each time and `checkout.start()` without `cartId` hands off an empty cart, which is refused with a `400`.
## Reads versus writes
| In a handler that… | Call | Why |
| - | - | - |
| Only renders (a product page, a layout, a badge) | `cart.current()` | Reads, **never creates**. A crawler or first-time visitor causes no write |
| Can set cookies (POST handler, form action) | `cart.add()`, `cart.ensure()`, `checkout.start()` | These create and remember a cart or session, which needs writable storage |
Cookies must **not** be `httpOnly` if browser code also reads the cart (the elements, `useCart`, the shared cart store). The default leaves `httpOnly` off.
## Hono and Cloudflare Workers
```ts src/index.ts theme={null}
import { Hono } from "hono"
import { kitFor } from "./kit.server"
const app = new Hono()
app.get("/products/:slug", async (c) => {
const setCookies: string[] = []
const kit = kitFor(c.req.raw, setCookies)
const [product, cart] = await Promise.all([
kit.products.getBySlug(c.req.param("slug")),
kit.cart.current(), // read only
])
if (!product) return c.notFound()
return c.html(renderProductPage(product, cart))
})
app.post("/cart", async (c) => {
const setCookies: string[] = []
const kit = kitFor(c.req.raw, setCookies)
const form = await c.req.formData()
await kit.cart.add({
productId: String(form.get("productId")),
variantId: form.get("variantId") ? Number(form.get("variantId")) : undefined,
})
const res = c.redirect("/cart", 303)
for (const cookie of setCookies) res.headers.append("set-cookie", cookie)
return res
})
app.post("/checkout", async (c) => {
const setCookies: string[] = []
const kit = kitFor(c.req.raw, setCookies)
const origin = new URL(c.req.url).origin
const { url } = await kit.checkout.start({
successUrl: `${origin}/success`,
backUrl: `${origin}/`,
language: "sv",
})
const res = c.redirect(url, 303) // the checkout session id is remembered in a cookie for the return leg
for (const cookie of setCookies) res.headers.append("set-cookie", cookie)
return res
})
export default app
```
On Workers, read the key from the env binding (`c.env.QUICKBUTIK_PUBLISHABLE_KEY`) instead of `process.env`.
## Express
Express has no `Request` object, so pass the raw `Cookie` header string as the source:
```ts theme={null}
import express from "express"
import { createShopkitClient, createRequestCookieStorage } from "@quickbutik/kit"
const base = { publishableKey: process.env.QUICKBUTIK_PUBLISHABLE_KEY! }
const app = express()
app.post("/checkout", async (req, res) => {
const setCookies: string[] = []
const kit = createShopkitClient(base).withStorage(
createRequestCookieStorage(req.headers.cookie ?? "", { collect: setCookies, attributes: { secure: true } }),
)
const origin = `${req.protocol}://${req.get("host")}`
const { url } = await kit.checkout.start({ successUrl: `${origin}/success`, backUrl: `${origin}/` })
for (const cookie of setCookies) res.append("Set-Cookie", cookie)
res.redirect(303, url)
})
```
Deriving `origin` from the `Host` header is convenient for `successUrl`. For canonical URLs in SEO tags, use a fixed configured origin instead, because a canonical built from an attacker-supplied `Host` is a known SEO-poisoning vector.
## Astro
Fetch in the frontmatter with a request-bound client, put the `buildSeo()` output in the layout ``, and use the web components in a client `