@kolaylogin/react

React SDK for KolayLogin. Provides a <KolayLoginProvider />, hooks for session state, and a background refresh loop that keeps the short-lived __session JWT valid without interrupting your UI.

Install

npm install @kolaylogin/react

Requires React 18 or newer.

Quick start

// app.tsx
import { KolayLoginProvider } from '@kolaylogin/react';

export default function App({ children }: { children: React.ReactNode }) {
  return (
    <KolayLoginProvider baseUrl={process.env.REACT_APP_KL_API_URL!}>
      {children}
    </KolayLoginProvider>
  );
}

// any component
import { useSession, useUserId } from '@kolaylogin/react';

export function Avatar() {
  const session = useSession();
  const userId = useUserId();

  if (session.status === 'signed_out') return <SignInButton />;
  return <span>Signed in as {userId}</span>;
}

API

<KolayLoginProvider />

| Prop | Type | Default | Description | | --------------------- | --------- | ------- | ---------------------------------------------------------------------------- | | baseUrl | string | — | Instance API base URL (e.g. https://auth.example.com). | | autoRefresh | boolean | true | Runs the refresh loop in the background to keep __session fresh. | | refreshSkewSeconds | number | 15 | How many seconds before JWT expiry to trigger a refresh. |

The provider reads the __session cookie on mount, decodes its claims, and exposes them to descendants. When autoRefresh is on, it schedules a refresh that fires refreshSkewSeconds before exp and repeats for the lifetime of the session.

Hooks

• useSession() — returns { status: 'signed_in', jwt, claims } | { status: 'signed_out' }.
• useUserId() — returns the sub claim when signed in, otherwise null.
• useKolayLogin() — returns { client, session, refresh }. refresh() lets you trigger a token refresh manually (e.g. after a password change).

Low-level client

KolayLoginReactClient is exposed if you want to skip the provider — useful for scripts or non-React roots. Most apps should not need it.

How the refresh loop works

Your instance issues two cookies:

• __client (httpOnly, long-lived) — held by the browser, used only for the refresh call.
• __session (readable by JS, ~60s) — the JWT your frontend sends to your backend.

The SDK decodes __session.exp, schedules setTimeout(refresh, exp - skew), hits the instance's /v1/auth/refresh endpoint, and re-reads the new __session cookie. The httpOnly __client never touches JS memory. If the refresh fails (revoked, network error), state transitions to signed_out and children re-render.

Next.js + Server Components

This package is a Client SDK ('use client' under the hood). For App Router middleware and server-side session access, use @kolaylogin/nextjs.

Error handling

• useSession() never throws — it simply reports signed_out when the cookie is missing or invalid.
• Manual refresh() can throw network errors; wrap it in a try/catch if you surface retry UI.

License

MIT