react-cool-auth-lib

A minimal, permissions-first React library for frontend permission management with glob pattern support.

Installation

npm install react-cool-auth-lib

Quick Start

import { PermissionsProvider, Guard, usePermissions } from 'react-cool-auth-lib';

// 1. Create a loader function
async function loadPermissions() {
  const res = await fetch('/api/permissions');
  const data = await res.json();
  return { permissions: data.permissions };
}

// 2. Wrap your app
function App() {
  return (
    <PermissionsProvider loader={loadPermissions}>
      <Dashboard />
    </PermissionsProvider>
  );
}

// 3. Use the Guard component or hook
function Dashboard() {
  const { hasPermission } = usePermissions();

  return (
    <>
      <Guard allOf={["admin.access"]} fallback={<AccessDenied />}>
        <AdminPanel />
      </Guard>

      {hasPermission("reports.view") && <ReportsButton />}
    </>
  );
}

Features

• <Guard> Component - Declarative conditional rendering with allOf, anyOf, and not props
• usePermissions() Hook - Imperative checks with hasPermission(), hasAll(), hasAny()
• createPermissionChecker() - For router guards and use outside React components
• Pattern Matching - Glob patterns via picomatch ("org.*" matches "org.read", "org.write")
• TypeScript - Full type safety

Pattern Matching

// User has: ["org.users.read", "org.settings.read"]

hasPermission("org.*")         // true - matches any org permission
hasPermission("org.users.*")   // true
hasPermission("*.read")        // true - matches all read permissions
hasAll(["org.*", "billing.*"]) // false - no billing permissions

Guard Component

<Guard
  allOf={["org.read"]}              // Must have ALL of these
  anyOf={["org.write", "admin.*"]}  // Must have ANY of these
  not={["account.suspended"]}       // Must NOT have any of these
  fallback={<AccessDenied />}
  loading={<Spinner />}
>
  <ProtectedContent />
</Guard>

Router Integration

import { createPermissionChecker } from 'react-cool-auth-lib';

// Works with React Router, TanStack Router, etc.
const checker = createPermissionChecker(userPermissions);

if (!checker.can({ allOf: ['admin.access'] })) {
  redirect('/forbidden');
}

API Reference

See llms.txt for comprehensive API documentation and examples.

License

MIT