Guide › Build & deploy
On this page
Auth and cookies
A signed-in visitor is a cookie the server reads on each request. clarusjs gives every server route and endpoint the request's cookies, and an optional handle() that turns the cookie into locals.user once, before anything loads.
Where things live #
| Static route | Server route | Island | |
|---|---|---|---|
| Runs | once, at build, for everyone | on every request | in the browser |
| Cookies | none (reading them fails the build) | cookies in load() |
sent along with its fetch() calls, never readable when HttpOnly |
| The user | none | locals.user, from handle() |
what an endpoint answers |
| Tokens for other APIs | build-time secrets only | in server code | never: keep them in an endpoint |
Island props and state are written into the page's HTML, so anything you pass to an island is public. Pass the user's name to an island if you like, but never a token.
Signing in #
The pieces, each a few lines:
-
src/server.tsresolves the session on every request:tsimport type { Handle } from 'clarusjs/server' declare module 'clarusjs/server' { interface Locals { user?: { id: string; name: string } } } export const handle: Handle = async ({ cookies, locals }) => { const session = cookies.get('session') if (session) locals.user = await sessions.find(session) } -
An endpoint signs in: it checks the credentials, then sets an HttpOnly cookie holding a random session id (not the user's data):
ts// src/pages/api/session.ts import type { RequestHandler } from 'clarusjs/server' export const POST: RequestHandler = async ({ request, cookies }) => { const { email, password } = await request.json() const user = await users.verify(email, password) if (!user) return Response.json({ error: 'Wrong email or password' }, { status: 401 }) cookies.set('session', await sessions.create(user), { maxAge: 60 * 60 * 24 * 7 }) return Response.json({ name: user.name }) } export const DELETE: RequestHandler = async ({ cookies }) => { await sessions.end(cookies.get('session')) cookies.delete('session') return Response.json({ ok: true }) } -
A server route uses
locals.user, and sends visitors who aren't signed in to the sign-in page:ts// src/pages/account.load.ts ('/account': 'server' in vite.config.ts) import { redirect, type LoadContext } from 'clarusjs/server' export function load({ locals }: LoadContext) { if (!locals.user) return redirect('/sign-in') return { name: locals.user.name } }To protect many routes at once,
handle()can return that redirect itself.
Cookies are secure by default: HttpOnly (scripts can't read them), SameSite=Lax, Secure, and Path=/. See cookies in the server reference.
Islands and endpoints #
An island can't read an HttpOnly cookie, and shouldn't hold a token. It calls an endpoint with fetch(), the browser sends the cookie along, and the endpoint answers with what the island may see. Try it: sign in, reload the page, and you're still signed in. The cookie is the session.
The demo's endpoint is the one above, and handle() turns the cookie into locals.user, so the endpoint just reads locals.user. (In the demo, the "session" is your name itself, which is not something to copy: a real session cookie holds a random id.)
Endpoints refuse writes from other sites: a POST whose Origin isn't your site gets a 403. This blocks cross-site request forgery, where another page makes the visitor's browser send its cookie for you. See endpoints.