🛡️ react-permify

A powerful, light-weight, and type-safe React package for Permission and Role-Based Access Control (RBAC).

🔥 Features

• ⚛️ Pure React: Built with standard Hooks and Context.
• 🛡️ Type-Safe: First-class TypeScript support.
• 🧩 Flexible Components: Conditional rendering with <Can />.
• 🪝 Custom Hooks: Access permissions anywhere with usePermission().
• 🏗️ HOC Support: Protect components with withPermission().
• 🗺️ Permission Mapping: Map roles to permissions automatically.
• 🔄 Dynamic Updates: Update user roles/permissions on the fly.
• 💾 Persistence: Built-in support for localStorage persistence.
• 📦 Zero-Dependencies: Extremely small bundle size.

🚀 Installation

npm install react-permify
# or
yarn add react-permify

🛠️ Quick Start

1. Wrap your App

import { PermissionProvider } from 'react-permify';

const user = { 
  id: 1, 
  role: 'admin',
  permissions: ['DELETE_USER'] 
};

// Optional: Map roles to permissions automatically
const permissionMap = {
  admin: ['EDIT_POST', 'DELETE_POST'],
  editor: ['EDIT_POST'],
  viewer: ['VIEW_POST']
};

function App() {
  return (
    <PermissionProvider 
      user={user} 
      permissionMap={permissionMap}
      persistKey="my-app-auth" // Optional: persistence
    >
      <Dashboard />
    </PermissionProvider>
  );
}

2. Guard Components with <Can />

import { Can } from 'react-permify';

// Check by Role
<Can role="admin">
  <DeleteButton />
</Can>

// Check by Permission
<Can permission="EDIT_POST">
  <EditButton />
</Can>

// With Fallback
<Can 
  role={['admin', 'manager']} 
  fallback={<p>Access Denied</p>}
>
  <AdminPanel />
</Can>

// Require All
<Can 
  permission={['READ', 'WRITE']} 
  requireAll={true}
>
  <SecretEditor />
</Can>

3. Use the usePermission Hook

import { usePermission } from 'react-permify';

const MyComponent = () => {
  const { hasRole, hasPermission, user, updatePermissionState } = usePermission();

  const handleLogin = (userData) => {
    // Update state dynamically after login
    updatePermissionState({
      user: userData,
      roles: userData.roles,
    });
  };

  if (hasPermission('DELETE_USER')) {
    return <button>Delete User</button>;
  }

  return <div>Welcome, {user?.name}</div>;
};

4. High-Order Component (HOC)

import { withPermission } from 'react-permify';

const SensitiveComponent = () => <div>Top Secret</div>;

export default withPermission(SensitiveComponent, {
  role: 'admin',
  fallback: <Redirect to="/unauthorized" />
});

📖 API Reference

<PermissionProvider />

| Prop | Type | Description | | :--- | :--- | :--- | | user | User | Initial user object. | | roles | string[] | Global roles for the session. | | permissions | string[] | Global permissions for the session. | | permissionMap | Record<string, string[]> | Mapping of roles to permissions. | | isLoading | boolean | Set to true while fetching data. | | loadingComponent| ReactNode | Component to show while isLoading is true. | | persistKey | string | localStorage key for persistence. |

<Can />

| Prop | Type | Description | | :--- | :--- | :--- | | role | string \| string[] | Role(s) required to view children. | | permission | string \| string[] | Permission(s) required to view children. | | requireAll | boolean | If true, all roles/perms must match. (default: false) | | fallback | ReactNode | Rendered if access is denied. |

📜 License

MIT © react-permify