A React starter built on @restheart-cloud/kit-react. Implements all RESTHeart Cloud auth and multi-tenancy flows out of the box — fork it, point it at your RESTHeart Cloud service, and start building your app.
Works for multi-tenant SaaS (invitations, team switcher) and simpler apps (auth only).
- Signup, login, logout — email/password and Google/GitHub OAuth
- Email verification, password reset
- Team invitations — one page (
/invitations/accept) branching into a new-user "set password" form (callsPATCH /auth/activate) or an existing-user "log in and accept" form - Team switcher — shown only when the user belongs to more than one team
- Authenticated shell with placeholder for your app content
- Lazy-loaded routes with code splitting
- A RESTHeart Cloud service — create one at cloud.restheart.com. Use a free service for development, a shared service (or higher) for production.
- Node.js 18+
git clone https://github.com/your-org/restheart-cloud-starter-react.git
cd restheart-cloud-starter-react
npm installAfter cloning, tell git to ignore local changes to the environment file:
git update-index --assume-unchanged src/environments/environment.tsThen edit src/environments/environment.ts and set apiUrl to your RESTHeart Cloud service URL. Your changes will not show up in git status.
npm run devsrc/
styles.css ← design tokens + the DISPOSABLE default skin
environments/
environment.ts ← apiUrl + feature flags
routes.tsx ← route map, feature-flag gating, lazy loading
App.tsx ← fragment token capture + config screen
main.tsx ← RhAuthProvider + BrowserRouter
theme hook ← light/dark toggle, persisted (in Shell.tsx)
ui/alert/ ← the one shared feedback component
pages/
shell/ ← authenticated frame: header, nav, user menu
home/ ← PLACEHOLDER showcase — replace with your content
auth/ ← login, signup, verify, forgot/reset password
invitations/accept/ ← one page, three flows (see below)
teams/ ← list, detail (members/invites/settings), new
account/ ← profile + change password
| Path | Guard | Shown when |
|---|---|---|
/auth/login |
PublicGuard |
always |
/auth/signup |
PublicGuard |
emailRegistration || oauthLogin |
/auth/verify |
PublicGuard |
emailRegistration |
/auth/forgot-password, /auth/reset-password |
PublicGuard |
passwordReset |
/invitations/accept |
none — works signed-in or out | teamInvitations |
/home, /teams, /teams/new, /teams/:id, /account |
AuthGuard |
always |
Feature flags live in src/environments/environment.ts and must match your service's
Sign-up Mgmt → Features toggles. A flag that's off removes the route and the UI that
links to it.
src/styles.css holds two things: design tokens (section 1) and a disposable
default skin (sections 3–5). The look is deliberately a mockup — cohesive and
intentional, but obviously a scaffold. @restheart-cloud/kit-react ships no UI at all, so
the components and this one stylesheet are the only places styling lives.
Two ways forward. Pick one:
A. Tweak the skin — fastest, roughly an hour to something that looks like yours:
- Change the tokens in
styles.csssection 1 — colours, type scale, spacing, radii. Every component reads them, so this re-themes the whole app including dark mode. - Adjust the skin classes in section 3 if you want different shapes.
- Replace the shell layout in
pages/shell/. - Replace
pages/home/with your own landing content.
B. Adopt a UI framework — Material, shadcn/ui, Tailwind, your own:
- Delete sections 3–5 of
styles.css(they are marked). Keep section 1 if you want the tokens; drop it too if your framework brings its own. - Reskin the components using the swap map below.
Components reference a small, stable vocabulary of semantic class hooks. Restyle them, or replace each element with your framework's component:
| Class hook | Used for | Tailwind (example) | Material (example) |
|---|---|---|---|
.card / .card-header |
Section container + its title row | rounded border p-6 mb-6 |
<Card> |
.btn-primary |
The one accented action per form | px-6 py-2 rounded bg-amber-400 font-semibold |
<Button variant="contained"> |
.btn-secondary |
Quiet bordered action | px-3 py-2 rounded border text-xs uppercase |
<Button variant="outlined"> |
.btn-danger / .btn-danger-text |
Destructive action / inline variant | … text-red-700 border-red-700 |
<Button variant="outlined" color="error"> |
.form-field / .form-field-sm / .form-row |
Label+control stack; -sm is narrow; -row lays fields side by side |
flex flex-col gap-1 / flex gap-3 |
<TextField> |
.password-field / .btn-toggle-password |
Password input with a Show/Hide toggle | relative / absolute right-2 |
<TextField> + end adornment |
.form-error / .field-error |
Form-level / per-field error | rounded border border-red-300 bg-red-50 p-3 |
<FormHelperText error> |
.success-msg |
Success feedback | rounded border border-emerald-300 bg-emerald-50 p-3 |
— (usually a snackbar) |
.muted |
Secondary/caption text | text-sm text-gray-500 |
className="body2" |
.badge |
Small status pill | rounded-full px-2 text-xs uppercase |
<Chip size="small"> |
.back-link / .eyebrow |
Back navigation / label above a title | text-xs uppercase tracking-wide |
— |
.placeholder / .skeleton |
Empty-slot outline / loading block | border border-dashed p-6 / animate-pulse bg-gray-200 |
<LinearProgress> |
.auth-page / .auth-card / .auth-links / .divider |
Centred auth layout | min-h-screen grid place-items-center / w-90 rounded border p-8 |
<Card> |
.config-page / .config-card / .config-status / .config-steps |
"Connect your service" screen | — | — |
Feedback is rendered through one component — src/ui/alert/Alert.tsx — which carries no
styles of its own, only the .success-msg / .form-error hooks plus the correct ARIA
roles. Swap that one component and every success/error message in the app follows.
Page-specific layout (.team-row, .member-row, .feature-grid, …) stays in the
component's own .css file and is not part of this contract.
@restheart-cloud/kit— TypeScript auth logic (framework-agnostic)@restheart-cloud/kit-react— React context, hooks, and guards