🚀 React Role Permission Pro

Complete Role & Permission Management System for React & Next.js with Beautiful UI, Auto Setup, and Advanced Features

✨ Features

🎯 Core Features

• ✅ Role Management - Create, edit, delete roles with Active/Inactive status
• ✅ Permission Management - Organize permissions by modules
• ✅ Role-Permission Assignment - Flexible permission assignment with presets
• ✅ User-Role Assignment - Single or multiple roles per user
• ✅ Super Admin - Bypass all permission checks
• ✅ Route Protection - Next.js middleware for automatic route protection
• ✅ Component Guards - React components for UI-level protection
• ✅ Data Ownership - Scoped permissions (own, team, department, any)

🎨 UI Features

• ✅ Beautiful Tailwind UI - Modern, responsive components
• ✅ Dark Mode Support - Full dark mode compatibility
• ✅ Dynamic Sidebar - Auto hide/show based on permissions
• ✅ Permission Matrix - Visual permission assignment
• ✅ Search & Filters - Fast role and permission filtering

🔐 Advanced Features

• ✅ Impersonation - Login as another user for debugging
• ✅ Temporary Access - Time-based role assignment
• ✅ Audit Logging - Track all role/permission changes
• ✅ Activity History - Monitor user actions
• ✅ Soft Delete - Safe role deletion with recovery
• ✅ Permission Presets - Quick role setup with templates
• ✅ Frontend Caching - Fast permission checks with encryption
• ✅ API Security - Backend guards for API routes

📦 Installation

npm install react-role-permission-pro
# or
yarn add react-role-permission-pro
# or
pnpm add react-role-permission-pro

🚀 Quick Start

1. Initialize the Package

npx role-permission init

This will:

• ✅ Detect your project type (Next.js/React)
• ✅ Copy necessary configuration files
• ✅ Setup database tables and migrations
• ✅ Seed default roles and permissions
• ✅ Create example routes

2. Configure Environment Variables

# Database
DATABASE_URL="postgresql://user:password@localhost:5432/mydb"

# JWT Secret
JWT_SECRET=your-super-secret-jwt-key

# App Configuration
NEXT_PUBLIC_APP_URL=http://localhost:3000

3. Wrap Your App with Provider

// app/layout.js or _app.js
import { RolePermissionProvider } from 'react-role-permission-pro';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <RolePermissionProvider
          config={{
            apiBaseUrl: '/api',
            cacheEnabled: true
          }}
        >
          {children}
        </RolePermissionProvider>
      </body>
    </html>
  );
}

4. Protect Your Routes

// middleware.js
import { middleware } from 'react-role-permission-pro/middleware';

export { middleware };

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico|public).*)']
};

📖 Usage Examples

Component Level Protection

import { PermissionGate, Can, PermissionButton } from 'react-role-permission-pro';

function MyComponent() {
  return (
    <div>
      {/* Method 1: Using PermissionGate */}
      <PermissionGate permission="product.create">
        <button>Create Product</button>
      </PermissionGate>

      {/* Method 2: Using Can */}
      <Can permission="product.update">
        <button>Edit Product</button>
      </Can>

      {/* Method 3: Using PermissionButton */}
      <PermissionButton
        permission="product.delete"
        onClick={handleDelete}
        variant="danger"
      >
        Delete Product
      </PermissionButton>

      {/* Multiple Permissions (require all) */}
      <Can permission={['product.read', 'product.update']} requireAll>
        <button>Advanced Edit</button>
      </Can>

      {/* Multiple Permissions (require any) */}
      <Can permission={['admin', 'manager']}>
        <button>Management Panel</button>
      </Can>
    </div>
  );
}

Hook-based Permission Checks

import { usePermission, useRole, useAuth } from 'react-role-permission-pro';

function ProductCard({ product }) {
  const canEdit = usePermission('product.update');
  const canDelete = usePermission('product.delete');
  const { hasRole } = useRole();
  const { user } = useAuth();

  const isAdmin = hasRole('admin');

  return (
    <div>
      <h3>{product.name}</h3>
      {canEdit && <button>Edit</button>}
      {canDelete && <button>Delete</button>}
      {isAdmin && <button>Advanced Settings</button>}
    </div>
  );
}

Data Ownership Checks

import { useCanAccessResource } from 'react-role-permission-pro';

function ProductEditPage({ product }) {
  // Checks both permission AND ownership
  const canEdit = useCanAccessResource('product.update', product);

  if (!canEdit) {
    return <div>You can only edit your own products</div>;
  }

  return <ProductForm product={product} />;
}

API Route Protection (Next.js)

// app/api/products/route.js
import { withPermission, withOwnership } from 'react-role-permission-pro/middleware';

// Simple permission check
export const GET = withPermission('product.read', async (request, user) => {
  const products = await db.product.findMany();
  return NextResponse.json({ data: products });
});

// With ownership check
export const PUT = withOwnership(
  'product.update',
  async (id) => await db.product.findUnique({ where: { id } }),
  async (request, user, context, product) => {
    const body = await request.json();
    const updated = await db.product.update({
      where: { id: product.id },
      data: body
    });
    return NextResponse.json({ data: updated });
  }
);

Beautiful UI Components

import { 
  RoleList, 
  PermissionMatrix, 
  DynamicSidebar,
  AuditLogViewer
} from 'react-role-permission-pro/components';

function AdminPage() {
  return (
    <div className="container mx-auto p-6">
      {/* Roles Management */}
      <RoleList
        onEdit={handleRoleEdit}
        onDelete={handleRoleDelete}
        roleManager={roleManager}
      />

      {/* Permission Matrix */}
      <PermissionMatrix
        roleId={selectedRoleId}
        onUpdate={handlePermissionUpdate}
      />

      {/* Dynamic Sidebar */}
      <DynamicSidebar
        items={sidebarItems}
        collapsible
      />

      {/* Audit Log Viewer */}
      <AuditLogViewer
        filters={{ entityType: 'role' }}
        pageSize={20}
      />
    </div>
  );
}

Impersonation (Super Admin Feature)

import { useAuth } from 'react-role-permission-pro';

function UserManagement() {
  const { impersonate, stopImpersonation, isImpersonating } = useAuth();

  const handleImpersonate = async (userId) => {
    try {
      await impersonate(userId);
      // Now logged in as that user
    } catch (error) {
      console.error('Impersonation failed:', error);
    }
  };

  return (
    <div>
      {isImpersonating() && (
        <div className="bg-yellow-100 p-4">
          <p>You are impersonating another user</p>
          <button onClick={stopImpersonation}>
            Stop Impersonation
          </button>
        </div>
      )}

      {/* User list with impersonate button */}
    </div>
  );
}

🎯 Permission Scopes

The package supports different permission scopes for data ownership:

| Scope | Description | Use Case | |-------|-------------|----------| | own | User can only access their own resources | Sellers editing their products | | team | User can access team resources | Team members sharing projects | | department | User can access department resources | Department managers | | any | User can access all resources | Admins and super users |

Setting Permission Scopes

// When creating permissions
const permission = {
  slug: 'product.update',
  scope: 'own', // Default
  // User with this permission can only update their own products
};

// Admin with 'any' scope
const adminPermission = {
  slug: 'product.update',
  scope: 'any',
  // Can update any product
};

🗂️ Database Schema

The package automatically creates these tables:

• roles - Role definitions
• permissions - Permission definitions
• role_permissions - Role-Permission mapping
• user_roles - User-Role assignment
• permission_groups - Permission presets
• audit_logs - Change tracking
• activity_history - User activity tracking

Supports: Prisma, Sequelize, TypeORM, Mongoose

🎨 Styling & Customization

Tailwind Configuration

// tailwind.config.js
module.exports = {
  content: [
    './node_modules/react-role-permission-pro/**/*.{js,jsx}'
  ],
  // Your config...
};

Theme Customization

<RolePermissionProvider
  config={{
    theme: {
      colors: {
        primary: '#3B82F6',
        danger: '#EF4444',
        success: '#10B981'
      }
    }
  }}
>
  {children}
</RolePermissionProvider>

🔧 CLI Commands

# Initialize package in your project
npx role-permission init

# Setup database
npx role-permission setup-db

# Generate TypeScript types
npx role-permission generate-types

# Sync routes with permissions
npx role-permission sync-routes

# Show help
npx role-permission help

📊 Pre-built Permission Presets

import { PermissionManager } from 'react-role-permission-pro';

const permissionManager = new PermissionManager();

// Apply preset to a role
await permissionManager.applyPreset(roleId, 'editor');

// Available presets:
// - admin: Full access
// - editor: Content management
// - support: Customer support
// - viewer: Read-only access

🐛 Debugging & Logging

<RolePermissionProvider
  config={{
    debug: true, // Enable console logs
    logLevel: 'verbose' // 'verbose' | 'info' | 'error'
  }}
>
  {children}
</RolePermissionProvider>

📝 TypeScript Support

Full TypeScript definitions included:

import type { 
  Role, 
  Permission, 
  User,
  PermissionScope 
} from 'react-role-permission-pro';

const role: Role = {
  id: '123',
  name: 'Admin',
  slug: 'admin',
  isActive: true,
  isSuperAdmin: false
};

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide.

📄 License

MIT © SNDP Bag

🙏 Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

🌟 Show Your Support

Give a ⭐️ if this project helped you!

Made with ❤️ by SNDP Bag