README.md

react-rbac-permissions

Type-safe role-based access control (RBAC) for React with declarative components and hooks.

Features

• 🔒 Type-safe — Full TypeScript support with autocomplete for roles and permissions
• 🎯 Declarative — <Can> component for conditional rendering
• 🪝 Hooks — usePermissions hook for programmatic access
• 🔗 Role inheritance — Roles can inherit permissions from other roles
• 🃏 Wildcards — Support for * (all) and resource:* (all actions) patterns
• 📦 Lightweight — Zero dependencies, tiny bundle size

Installation

pnpm add react-rbac-permissions

Quick Start

1. Define your permissions config

// permissions.ts
import { createPermissions } from 'react-rbac-permissions'

export const {
  PermissionProvider,
  usePermissions,
  Can,
} = createPermissions({
  roles: ['admin', 'editor', 'viewer'],
  resources: {
    posts: ['create', 'read', 'update', 'delete'],
    users: ['read', 'invite', 'ban'],
  },
  permissions: {
    admin: {
      can: ['*'], // all permissions
    },
    editor: {
      can: ['posts:*'], // all post actions
      inherits: ['viewer'],
    },
    viewer: {
      can: ['posts:read', 'users:read'],
    },
  },
})

2. Wrap your app with the provider

// App.tsx
import { PermissionProvider } from './permissions'

function App() {
  const userRoles = ['editor'] // from your auth system

  return (
    <PermissionProvider roles={userRoles}>
      <Dashboard />
    </PermissionProvider>
  )
}

3. Use the <Can> component or hook

import { Can, usePermissions } from './permissions'

function Dashboard() {
  const { can, hasRole } = usePermissions()

  return (
    <div>
      {/* Declarative with <Can> component */}
      <Can do="posts:create">
        <button>Create Post</button>
      </Can>

      {/* With fallback */}
      <Can do="users:ban" fallback={<p>No access</p>}>
        <button>Ban User</button>
      </Can>

      {/* Multiple permissions (all required by default) */}
      <Can do={['posts:update', 'posts:delete']}>
        <button>Edit Post</button>
      </Can>

      {/* Any permission matches */}
      <Can do={['posts:update', 'posts:delete']} mode="any">
        <button>Manage Post</button>
      </Can>

      {/* Programmatic with hook */}
      {can('posts:read') && <PostList />}
      {hasRole('admin') && <AdminPanel />}
    </div>
  )
}

API Reference

createPermissions(config)

Factory function that creates type-safe permission utilities.

Config

Property	Type	Description
roles	string[]	List of role names
resources	Record<string, string[]>	Resources and their actions
permissions	Record<role, { can, inherits? }>	Permission mappings per role

Returns

Export	Description
PermissionProvider	React context provider
usePermissions	Hook for accessing permission utilities
Can	Declarative component for conditional rendering
allRoles	Set of all defined roles
allPermissions	Set of all possible permissions
getPermissionsForRole(role)	Get all permissions for a role
getRolesWithPermission(permission)	Get all roles that have a permission

<Can> Component

Prop	Type	Default	Description
do	Permission | Permission[]	required	Permission(s) to check
mode	'all' | 'any'	'all'	Require all or any permission
fallback	ReactNode	null	Rendered when access denied
children	ReactNode	required	Rendered when access granted

usePermissions() Hook

Returns an object with:

Method	Description
can(permission)	Check single permission
canAll(permissions)	Check all permissions
canAny(permissions)	Check any permission
hasRole(role)	Check if user has role
hasAllRoles(roles)	Check all roles
hasAnyRole(roles)	Check any role
roles	Current user's roles
permissions	Set of resolved permissions
getPermissionsForRole(role)	Get permissions for a role
getRolesWithPermission(permission)	Get roles with a permission

Wildcards

permissions: {
  admin: {
    can: ['*'], // All permissions
  },
  editor: {
    can: ['posts:*'], // All actions on posts resource
  },
}

Role Inheritance

Roles can inherit from other roles:

permissions: {
  admin: {
    can: ['users:*'],
    inherits: ['editor'], // Gets all editor permissions too
  },
  editor: {
    can: ['posts:*'],
    inherits: ['viewer'],
  },
  viewer: {
    can: ['posts:read'],
  },
}

Development

Prerequisites

• Node.js 18+
• pnpm

Setup

# Install dependencies
pnpm install

# Run playground
pnpm play

# Run tests
pnpm test

# Run tests in watch mode
pnpm test --watch

# Type check
pnpm typecheck

# Build
pnpm build

Project Structure

├── src/
│   ├── index.ts              # Entry point
│   ├── create-permissions.tsx # Main implementation
│   └── create-permissions.test.tsx # Tests
├── playground/               # Development playground
│   └── src/
│       ├── App.tsx
│       └── config/permissions.ts
└── dist/                     # Built output