Multi-Tenant React: Role-Based UI Without Redeploying
If you sell software to many organisations, every customer wants slightly different things: different modules switched on, different roles, different menus. If each of those needs a code change and a deploy, onboarding becomes your bottleneck. I am building a white-label, multi-tenant hospital management system in React 19 and TypeScript where modules, menu items and permissions are configurable per role and per tenant, and onboarding a new hospital needs zero frontend changes. This post explains the approach.
Key takeaways
- Let the server describe what the user can see, and let the frontend render that description.
- Model permissions as data: tenant features, then roles, then individual permissions.
- Use a small
can()helper and a<Can>component instead of scattered role checks. - The UI only hides things. The server must enforce every permission.
The core idea: a navigation manifest
After login, the API returns a manifest describing the user's world. The frontend builds its menu and routes from it.
type Permission = `${string}.${"read" | "create" | "update" | "delete"}`;
interface ModuleConfig {
key: string;
label: string;
path: string;
icon: string;
permissions: Permission[];
}
interface SessionManifest {
tenantId: string;
roles: string[];
permissions: Permission[];
modules: ModuleConfig[];
branding: { name: string; primaryColor: string };
}A hospital might receive modules such as patients, appointments, billing, pharmacy and lab. A smaller clinic gets only some of them. The code is identical, and only the manifest differs.
Three layers of control
- Tenant features. Which modules this customer has bought or enabled.
- Roles. Named bundles of permissions such as receptionist, doctor or admin, defined per tenant.
- Permissions. The fine-grained actions, such as
billing.readorpatients.update.
A user sees a module only if the tenant has it and one of their roles grants a permission inside it.
A small permissions API
Centralise the checks so components never inspect role names directly.
const PermissionContext = createContext<Set<Permission>>(new Set());
export function usePermissions() {
const granted = useContext(PermissionContext);
return {
can: (permission: Permission) => granted.has(permission),
canAny: (list: Permission[]) => list.some((p) => granted.has(p)),
};
}
export function Can({ permission, children, fallback = null }: CanProps) {
const { can } = usePermissions();
return can(permission) ? <>{children}</> : <>{fallback}</>;
}Usage stays readable:
<Can permission="billing.update">
<button type="button">Edit invoice</button>
</Can>;Render routes and menus from data
Build the router and sidebar by mapping over manifest.modules, and lazy-load each module so a tenant only downloads the code for features they use. Guard each route with the module's permissions and redirect to a clear "no access" page.
Theming per tenant
Treat branding as design tokens. Set CSS variables such as --primary from the manifest at startup, and every component picks them up without per-customer builds. A shared component library with tokens keeps modules visually consistent while still looking like each customer's product.
Security rules that do not change
- The UI is not the security boundary. Hiding a button does not stop a request. The API must check the tenant and permission on every call.
- Never trust IDs from the client. Derive the tenant from the authenticated session.
- Log sensitive actions. In healthcare and finance, audit logs are a requirement and not a nice to have.
- Refresh the manifest on change. If a role changes, update the session promptly rather than waiting for the next login.
Why this pays off
Because behaviour comes from configuration, you can onboard customers, add modules and change roles without touching the frontend or redeploying it. It also forces a clean contract between frontend and backend, which I agree early with the backend team so the manifest, the data models and the authentication flow are stable before screens are built.
This is the kind of system I describe in my web application development service, and it is also how Dashify, my multi-tenant SaaS project, is organised.
- React
- multi-tenant
- RBAC
- SaaS
- architecture