Every sign-in ends in a session. Make yours type-safe and predictable.
Session kit is the session layer for React apps that have their own backend. Give it the tokens your sign-in endpoint returns, and it saves the session, restores it on reload, refreshes tokens before they expire, keeps every tab in sync, and guards your routes. It never signs users in: your backend does, and Session kit takes over from its response.
It works with TanStack Router, React Router, and Expo Router, renders on the server with TanStack Start, Next.js, and React Router, and comes with an Effect service and an effetch plugin.
Release candidate. The API is frozen for 0.1, and later 0.1 releases only add to it. See the release notes.
Documentation: session-kit.pages.dev
npm install @monarcode/session-kit zodAny Standard Schema library describes users. The examples use Zod. Peer dependencies such as React and your router are optional: install the ones your setup uses. Compatibility lists the supported versions.
Release candidates are published to the latest tag, so pin an exact version
and read the release notes before upgrading.
Your backend keeps its sign-in and refresh endpoints. Session kit takes the tokens they return and manages the session from there. A React app needs three files.
1. Create the client. It checks every user against your schema, saves the
session, and calls your refresh before the access token expires:
import { createAuth, webStorage } from "@monarcode/session-kit";
import { z } from "zod";
export const auth = createAuth({
// Keeps this app's saved session apart from others on the same origin.
name: "my-app",
// Every user is checked against this schema, and typed by it.
user: z.object({ id: z.string(), name: z.string() }),
// Saves the session in localStorage, so it survives reloads.
storage: webStorage(),
refresh: async ({ refreshToken, signal }) => {
const response = await fetch("/api/auth/refresh", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ refreshToken }),
signal,
});
if (response.status === 401) return null; // rejected: sign out
if (!response.ok) throw new Error(`Refresh failed (${response.status})`);
return response.json();
},
});
// Types the React hooks with this client's user.
declare module "@monarcode/session-kit" {
interface Register {
auth: typeof auth;
}
}2. Sign in. Pass signIn what your backend's sign-in returned, the tokens
and the user:
import { auth } from "./auth.js";
export async function signIn(email: string, password: string) {
const response = await fetch("/api/auth/login", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ email, password }),
});
if (!response.ok) throw new Error(`Sign-in failed (${response.status})`);
// { accessToken, refreshToken, expiresIn, user }
const tokens = await response.json();
await auth.signIn(tokens);
}3. Render by the session's status. useAuth re-renders when it changes,
in this tab or another:
import {
AuthProvider,
useAuth,
useAuthClient,
} from "@monarcode/session-kit/react";
import { auth } from "./auth.js";
import { SignInForm } from "./sign-in-form.js"; // your form, calling signIn
export function App() {
return (
<AuthProvider client={auth}>
<Home />
</AuthProvider>
);
}
function Home() {
const session = useAuth();
const client = useAuthClient();
if (session.status === "initializing") return <p>Restoring your session…</p>;
if (session.status === "unauthenticated") return <SignInForm />;
if (session.status === "unavailable") {
// The session couldn't be restored or refreshed, say while offline.
return (
<button onClick={() => client.retry().catch(console.error)}>
Try again
</button>
);
}
return (
<main>
<h1>Welcome, {session.user.name}</h1>
<button onClick={() => client.signOut().catch(console.error)}>
Sign out
</button>
</main>
);
}To call your API, createAuthFetch from @monarcode/session-kit/http adds
the access token to each request and refreshes it after a 401.
Getting started builds
this app step by step against a real test backend, and the guides below add
your router's guards or server rendering.
Each setup has a guide:
| Setup | Guide |
|---|---|
| React without a router | Getting started |
| TanStack Router, and TanStack Start as a single-page app (SPA) | TanStack Router |
| TanStack Start with server rendering | TanStack Start |
| React Router: declarative, data, framework SPA | React Router |
| React Router, framework mode with server rendering | React Router with SSR |
| Next.js 16, App Router | Next.js |
| Expo Router on iOS and Android, SDK 53+ | Expo Router |
| Effect and effetch, with any setup | Effect and effetch |
All but the first have a runnable app in examples/.
See CONTRIBUTING.md.
