Skip to main content
You can call the Headless API by hand with fetch, but the official packages add type safety, error handling and Next.js integration.
If you use create-leaderos-theme, the packages come pre-installed. This page is for adding them to an existing project or understanding how they work.

@leaderos/headless-sdk

Installation

Creating a client

Usage

The SDK mirrors the API groups:
Available groups include site, auth, account, store, cart, payments, credits, chest, forum, support, blog, help, suggestions, applications, forms and server (play, vote, staff). To see which method maps to which endpoint, check the operationId values in OpenAPI.

Error handling

LeaderOSError fields: code, status, fields, details. Branch on code, not on message.

Per-request options

The last parameter of every method is an options object (query, headers, signal, fetch):

Types

All schemas generated from OpenAPI are exported:

@leaderos/headless-react

Installation

Provider and hooks

Do not delete, hide or replace <PoweredBy />. It can only be removed when config.branding.canRemove is true.

Next.js integration

Environment variables (.env.local):

Server client (Server Components / Server Actions)

This client reads the user token from the httpOnly cookie and forwards the visitor’s IP to the API via X-Forwarded-For.

Proxy route (browser requests)

The browser client (createBrowserClient()) sends its requests to this route. The proxy:
  • adds the public key and user token on the server (the browser never sees the token),
  • writes the token to an httpOnly cookie on login/registration, rotates it on password/e-mail change and clears it on logout,
  • blocks cross-site mutating requests.
This means you do not even need CORS settings, because the browser only talks to your own domain.
The public key may be visible in the browser, but with the proxy it never is. Using the proxy in production is recommended.