React Access Control

A flexible, lightweight React library for implementing permission-based access control and feature flags in your applications.

Features

• 🔐 Permission-based Access Control - Granular control over what users can see and do
• 🚩 Feature Flags - Toggle features on/off for different user groups
• 🛡️ Route Protection - Protect entire routes based on permissions
• 💾 Flexible Storage - Multiple storage adapters (localStorage, sessionStorage, AsyncStorage, IndexedDB)
• 🔒 Security - Encrypted storage options available
• 🚀 Framework Agnostic - Works with Next.js, React Router, and other routing solutions
• 📱 React Native Support - Full support for React Native applications
• 🎯 TypeScript First - Built with TypeScript for excellent developer experience

Installation

npm install @clywell/react-access-control
# or
yarn add @clywell/react-access-control
# or
pnpm add @clywell/react-access-control

Quick Start

1. Wrap your app with AccessControlProvider

import { AccessControlProvider } from '@clywell/react-access-control';

function App() {
  return (
    <AccessControlProvider>
      <YourApp />
    </AccessControlProvider>
  );
}

2. Set user context after authentication

import { useAccessControl } from '@clywell/react-access-control';

function LoginComponent() {
  const { setUserContext } = useAccessControl();

  const handleLogin = async (credentials) => {
    const user = await authenticateUser(credentials);
    
    setUserContext({
      user: { id: user.id, name: user.name },
      permissions: user.permissions, // ['READ_USERS', 'WRITE_POSTS', etc.]
      featureFlags: user.featureFlags // ['BETA_UI', 'NEW_DASHBOARD', etc.]
    });
  };

  return (
    // Your login form
  );
}

3. Control access with AccessGuard

import { AccessGuard } from '@clywell/react-access-control';

function UserManagement() {
  return (
    <div>
      {/* Always visible */}
      <h1>User Management</h1>
      
      {/* Only visible with READ_USERS permission */}
      <AccessGuard permissions={['READ_USERS']}>
        <UserList />
      </AccessGuard>
      
      {/* Only visible with WRITE_USERS permission */}
      <AccessGuard permissions={['WRITE_USERS']}>
        <AddUserButton />
      </AccessGuard>
      
      {/* Only visible when BETA_UI feature flag is enabled */}
      <AccessGuard featureFlags={['BETA_UI']}>
        <NewUserInterface />
      </AccessGuard>
    </div>
  );
}

4. Protect routes with RouteGuard

import { RouteGuard } from '@clywell/react-access-control';

function AdminRoute() {
  return (
    <RouteGuard 
      permissions={['ACCESS_ADMIN']}
      fallbackPath="/unauthorized"
    >
      <AdminDashboard />
    </RouteGuard>
  );
}

Advanced Usage

Custom Storage Adapter

import { AccessControlProvider, LocalStorageAdapter } from '@clywell/react-access-control';

// Use localStorage with custom prefix
const storageAdapter = new LocalStorageAdapter('my-app');

function App() {
  return (
    <AccessControlProvider storageAdapter={storageAdapter}>
      <YourApp />
    </AccessControlProvider>
  );
}

Encrypted Storage

import { 
  AccessControlProvider, 
  LocalStorageAdapter, 
  EncryptedStorageAdapter 
} from '@clywell/react-access-control';

const baseAdapter = new LocalStorageAdapter('my-app');
const encryptedAdapter = new EncryptedStorageAdapter(baseAdapter, 'your-secret-key');

function App() {
  return (
    <AccessControlProvider storageAdapter={encryptedAdapter}>
      <YourApp />
    </AccessControlProvider>
  );
}

React Native with AsyncStorage

import AsyncStorage from '@react-native-async-storage/async-storage';
import { 
  AccessControlProvider, 
  AsyncStorageAdapter 
} from '@clywell/react-access-control';

const storageAdapter = new AsyncStorageAdapter(AsyncStorage);

function App() {
  return (
    <AccessControlProvider storageAdapter={storageAdapter}>
      <YourApp />
    </AccessControlProvider>
  );
}

Multiple Storage Tiers

import { 
  AccessControlProvider,
  MultiTierStorageAdapter,
  IndexedDBStorageAdapter,
  LocalStorageAdapter
} from '@clywell/react-access-control';

// Try IndexedDB first, fallback to localStorage
const storageAdapter = new MultiTierStorageAdapter([
  new IndexedDBStorageAdapter(),
  new LocalStorageAdapter()
]);

function App() {
  return (
    <AccessControlProvider storageAdapter={storageAdapter}>
      <YourApp />
    </AccessControlProvider>
  );
}

Framework Integration

Next.js App Router

import { NextJSAdapter } from '@clywell/react-access-control/adapters/nextjs';

const navigationAdapter = new NextJSAdapter();

function App() {
  return (
    <AccessControlProvider navigationAdapter={navigationAdapter}>
      <YourApp />
    </AccessControlProvider>
  );
}

React Router

import { ReactRouterAdapter } from '@clywell/react-access-control/adapters/react-router';
import { useNavigate } from 'react-router-dom';

function App() {
  const navigate = useNavigate();
  const navigationAdapter = new ReactRouterAdapter(navigate);

  return (
    <AccessControlProvider navigationAdapter={navigationAdapter}>
      <YourApp />
    </AccessControlProvider>
  );
}

API Reference

AccessControlProvider

| Prop | Type | Description | |------|------|-------------| | storageAdapter | StorageAdapter | Custom storage implementation | | navigationAdapter | NavigationAdapter | Custom navigation implementation | | children | ReactNode | Your app components |

AccessGuard

| Prop | Type | Description | |------|------|-------------| | permissions | string[] | Required permissions (OR logic) | | featureFlags | string[] | Required feature flags (OR logic) | | requireAll | boolean | Use AND logic instead of OR | | fallback | ReactNode | Fallback component when access denied | | children | ReactNode | Content to protect |

RouteGuard

| Prop | Type | Description | |------|------|-------------| | permissions | string[] | Required permissions | | featureFlags | string[] | Required feature flags | | requireAll | boolean | Use AND logic instead of OR | | fallbackPath | string | Redirect path when access denied | | fallback | ReactNode | Fallback component instead of redirect | | children | ReactNode | Content to protect |

useAccessControl Hook

const {
  user,              // Current user info
  permissions,       // User's permissions array
  featureFlags,      // User's feature flags array
  hasPermission,     // (permission: string) => boolean
  hasFeatureFlag,    // (flag: string) => boolean
  hasAnyPermission,  // (permissions: string[]) => boolean
  hasAllPermissions, // (permissions: string[]) => boolean
  hasAnyFeatureFlag, // (flags: string[]) => boolean
  hasAllFeatureFlags,// (flags: string[]) => boolean
  setUserContext,    // (context: UserContext) => void
  updatePermissions, // (permissions: string[]) => void
  updateFeatureFlags,// (flags: string[]) => void
  logout,            // () => void
  isLoading          // boolean
} = useAccessControl();

Storage Adapters

Built-in Adapters

• LocalStorageAdapter - Browser localStorage
• SessionStorageAdapter - Browser sessionStorage
• AsyncStorageAdapter - React Native AsyncStorage
• IndexedDBStorageAdapter - Browser IndexedDB
• EncryptedStorageAdapter - Encrypted wrapper for any adapter
• MultiTierStorageAdapter - Multiple adapters with fallback

Custom Storage Adapter

import { StorageAdapter } from '@clywell/react-access-control';

class CustomStorageAdapter implements StorageAdapter {
  async getItem(key: string): Promise<string | null> {
    // Your implementation
  }

  async setItem(key: string, value: string): Promise<void> {
    // Your implementation
  }

  async removeItem(key: string): Promise<void> {
    // Your implementation
  }
}

Examples

Check out the examples directory for complete working examples:

• Basic Usage - Simple permission and feature flag demo
• Next.js Integration - App Router with server-side access control
• React Native - Mobile app integration

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

MIT © Clywell

Support

• 📖 Documentation
• 🐛 Issues
• 💬 Discussions