SRD client — overview

The SRD module (@franksauvag/rpg-commons/srd) provides typed access to the MaChaine SRD backend.

Recommended: createSrdRuntime

Use one runtime per app lifetime — unified cache for bundles, entry lists, meta, and translation stats.

import { createSrdRuntime } from "@franksauvag/rpg-commons/srd";

export const srdRuntime = createSrdRuntime({
  apiBaseUrl: import.meta.env.VITE_API_BASE_URL,
  defaultLocale: "fr",
});

const skills = await srdRuntime.loadTypeEntries("skills", "fr");
const classes = await srdRuntime.loadBundle("classes");

await srdRuntime.preload({
  bundles: ["classes", "spells"],
  typeEntries: [{ typeId: "skills", lang: "fr" }],
});

const locales = await srdRuntime.getLocales();
const stats = await srdRuntime.getTranslationStats("fr");

See Choosing a client and the API reference.

Lower-level clients

• createSrdClient — bundle builders + raw fetchDataset (deduplicated inflight requests).
• createSrdEntryListClient — Candlekeep-style rows (bulk + locale overlay).

Prefer the runtime for new code; do not stack a second cache for the same SRD keys.

Errors

import { SrdHttpError } from "@franksauvag/rpg-commons/srd";

try {
  await srdRuntime.loadBundle("classes");
} catch (err) {
  if (err instanceof SrdHttpError) {
    console.error(err.status, err.message);
  }
}

Media URLs

import { resolveSrdMediaUrl, resolveEntryMediaSrc } from "@franksauvag/rpg-commons/srd";

const url = resolveSrdMediaUrl("srd/classes/barbarian.webp", apiBaseUrl);
const src = resolveEntryMediaSrc(entry.image, apiBaseUrl);

TanStack Query

Only meta and translation-stats keys are provided by the library:

import { srdQueryKeys, SRD_QUERY_STALE_MS } from "@franksauvag/rpg-commons/srd";

useQuery({
  queryKey: srdQueryKeys.metaLocales(),
  queryFn: () => srdRuntime.getLocales(),
  staleTime: SRD_QUERY_STALE_MS,
});

For bundle data, use the runtime (or wrap loadBundle in your own query keys).

Architecture

Transport, two façades, and cache keys are described in Architecture.