@xplbs/rbac

A comprehensive Role-Based Access Control (RBAC) system featuring a NestJS backend module and a ready-to-use React Admin UI.

Features

• User Management: Built-in user CRUD operations.
• Group/Role Management: Hierarchical groups with inheritance.
• Granular Permissions:
  • Global Permissions (Group-based)
  • Module-specific Permissions (Resource-based)
• Admin UI: Pre-built React components (GroupsPage, UsersPage, etc.) to seamlessy manage access control.
• Prisma & TypeORM Support: Built with modern ORMs in mind.

Installation

npm install @xplbs/rbac

Usage

Backend (NestJS)

Import the core modules into your root AppModule.

import { Module } from '@nestjs/common';
import { APP_GUARD } from '@nestjs/core';
import { 
  UsersModule, 
  AuthModule, 
  ModulesModule,
  GroupPermissionsGuard 
} from '@xplbs/rbac'; // Simplified import

@Module({
  imports: [
    UsersModule,
    AuthModule,
    ModulesModule,
  ],
  providers: [
    {
      provide: APP_GUARD,
      useClass: GroupPermissionsGuard, // Enforce RBAC globally
    },
  ],
})
export class AppModule {}

Frontend (React / Vite)

The package includes a fully functional Admin UI exported via @xplbs/rbac/ui.

1. Import Styles Import the necessary styles in your main entry file (e.g., main.tsx or App.tsx):

import '@xplbs/rbac/ui/styles.css';

2. Configure API If your backend is not running on http://localhost:3000, or you need to pass a JWT token for authentication, use the configureApi function:

import { configureApi } from '@xplbs/rbac/ui';

configureApi({
  baseURL: 'https://your-api-domain.com',
  token: localStorage.getItem('token'), // Optional: Pass token if available
});

3. Use Components

import { GroupsPage, UsersPage, ModulesPage } from '@xplbs/rbac/ui';
import { BrowserRouter, Routes, Route } from 'react-router-dom';

function App() {
  return (
    <BrowserRouter>
      <Routes>
        <Route path="/admin/users" element={<UsersPage />} />
        <Route path="/admin/groups" element={<GroupsPage />} />
        <Route path="/admin/modules" element={<ModulesPage />} />
      </Routes>
    </BrowserRouter>
  );
}

Ensure you import the necessary styles or Tailwind CSS configuration if required by the UI components.

API Documentation

The package includes a Postman collection (RBAC.postman_collection.json) in the root directory for testing API endpoints.

Database Configuration

By default, the package looks for a DATABASE_URL environment variable. You can change your database path by adding it to your .env file:

DATABASE_URL="postgresql://user:password@localhost:5432/your_database"

If you are using this package as a module in your NestJS app, ensure that your environment variables are loaded (e.g., using @nestjs/config).

Database Initializing

After setting up your DATABASE_URL, you must push the RBAC schema to your database. Run the following command from your project root:

npx prisma db push --schema node_modules/@xplbs/rbac/prisma/schema.prisma

This ensures the required tables (User, Group, Module, etc.) are created and compatible with the package.

Integration & Troubleshooting

Prisma Compatibility

Crucial: This package requires Prisma v6. Prisma v7 introduced breaking changes to schema.prisma validation (e.g., removal of url in datasource), which renders this package's schema incompatible. Ensure your project uses Prisma v6:

npm install prisma@^6 @prisma/client@^6

Admin UI Configuration

The UsersPage component enforces strict validation by default (e.g., mandatory password and group selection on creation). You can disable these checks via props if your backend handles them differently or if you want a more flexible UI.

<UsersPage 
  validation={{
    disablePasswordRequirement: true, // Optional: Disable frontend password check
    disableGroupRequirement: true     // Optional: Disable frontend group check
  }} 
/>

Development vs Consumption

Note: The installed node_modules/@xplbs/rbac package is a library, not a development workspace. You cannot run npm run dev inside it. It provides:

1. Compiled backend code (dist/).
2. React components (ui export).
3. Source code for reference (admin-ui/).

Do not attempt to run development scripts directly within node_modules.