@franksauvag/rpg-commons

Getting Started ​

@franksauvag/rpg-commons is a React component library and SRD data client shared across the Les Héritiers du Donjon projects. It provides the design system (45+ shadcn/ui components, dark RPG theme), RPG-specific shared components, and a typed HTTP client for the MaChaine SRD backend.

Prerequisites ​

ToolVersion
Node.js>=22 <26
pnpm10.x
React^19.0.0 (peer dep)
Tailwind CSS^4.0.0 (peer dep)

The package is published to GitHub Packages (npm.pkg.github.com). Authentication is required even for public packages.

1. Authenticate with GitHub Packages ​

Create a Personal Access Token with read:packages scope (fine-grained or classic).

Keep secrets out of the repo: store the registry + token in your user npmrc (e.g. ~/.npmrc on macOS/Linux, %USERPROFILE%\.npmrc on Windows):

ini
@franksauvag:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_PAT

Then npm install / pnpm install in any clone works without exporting environment variables.

Optional: committed project .npmrc (registry only) ​

You may commit a project .npmrc that sets only the scoped registry (no token), so teammates and CI know where @franksauvag/* resolves; authentication still comes from ~/.npmrc locally or from CI (below):

ini
@franksauvag:registry=https://npm.pkg.github.com

CI (GitHub Actions) ​

Add a PAT with read:packages as a repository secret (e.g. PACKAGES_READ_TOKEN). Use actions/setup-node with registry-url, scope, and NODE_AUTH_TOKEN so the workflow writes a temporary auth line — do not commit the token:

yaml
- uses: actions/setup-node@v5
  with:
    node-version: "24"
    cache: npm
    registry-url: https://npm.pkg.github.com
    scope: "@franksauvag"
  env:
    NODE_AUTH_TOKEN: ${{ secrets.PACKAGES_READ_TOKEN }}

- name: Install dependencies
  run: npm ci

Note: The built-in GITHUB_TOKEN of a consumer repo can only access packages published by that same repo. A PAT is required to read packages published from rpg-commons.

2. Install ​

bash
pnpm add @franksauvag/rpg-commons

Peer dependencies (install if not already present):

bash
pnpm add react react-dom tailwindcss

3. Import styles ​

In your app's main CSS file (e.g. src/index.css), import the design system before your own Tailwind setup:

css
/* Dark RPG theme tokens + all component styles */
@import "@franksauvag/rpg-commons/style";

/* Optional: Cinzel (headings) + Crimson Text (body) via Google Fonts */
@import "@franksauvag/rpg-commons/fonts";

@import "tailwindcss";
/* your own overrides below */

Note: the library is dark-first — :root already maps to the dark RPG theme. If your app uses a .dark class toggle, both :root and .dark use the same values by default. You can override individual tokens in your own CSS.

4. Use components ​

tsx
import { Button, Card, CardHeader, CardTitle, Badge } from "@franksauvag/rpg-commons";

export function ClassCard({ name, hitDie }: { name: string; hitDie: string }) {
  return (
    <Card className="w-64">
      <CardHeader>
        <div className="flex items-center justify-between">
          <CardTitle>{name}</CardTitle>
          <Badge variant="outline">{hitDie}</Badge>
        </div>
      </CardHeader>
    </Card>
  );
}

5. Use the SRD client ​

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

const srd = createSrdClient({
  apiBaseUrl: import.meta.env.VITE_API_BASE_URL,
});

const classes = await srd.buildClassesBundle();

See SRD overview and the API reference.

6. Browse the component library ​

Run Storybook locally:

bash
pnpm storybook
# -> http://localhost:6006

Or browse the hosted version at libs.heritiersdudonjon.com/storybook.