cml-webui-commons

CodingMonkeyLabs WebUI Commons - A comprehensive React component library with authentication, styling, and common utilities. Build modern web applications with a production-ready component library and design system.

Features

• 🎨 Premium Design System - "Luminous Excellence" design system with SCSS and Tailwind CSS
• 🔐 Authentication System - Complete auth flow with JWT, RBAC, and permission management
• 🧩 Reusable Components - Layout, Modal, Form, and UI components
• 🪝 Custom Hooks - useAuth, usePermission, useRole, and more
• 📦 State Management - Zustand stores for auth and theme
• 🌙 Dark Mode - Built-in theme switching with Light, Dark, and Neon themes
• 🔧 TypeScript - Fully typed with TypeScript
• ✅ Validation - Zod schemas for form validation
• 🎯 API Client - Configurable Axios client factory with interceptors and token refresh
• ♻️ Generic & Reusable - Framework-agnostic utilities and helpers

Installation

npm install cml-webui-commons

Quick Start

1. Import Styles

Import the styles in your main entry file:

import 'cml-webui-commons/styles'

2. Configure Tailwind

Extend your Tailwind configuration with the preset:

// tailwind.config.js
import { tailwindPreset } from 'cml-webui-commons/tailwind-preset'

export default {
  presets: [tailwindPreset],
  content: [
    "./index.html",
    "./src/**/*.{js,ts,jsx,tsx}",
    "./node_modules/cml-webui-commons/dist/**/*.js",
  ],
}

3. Setup Authentication

Wrap your app with the AuthProvider:

import { AuthProvider } from 'cml-webui-commons'

function App() {
  return (
    <AuthProvider>
      {/* Your app content */}
    </AuthProvider>
  )
}

4. Use Components

import { Layout, Header, Sidebar, Modal, AuthGuard } from 'cml-webui-commons'

function Dashboard() {
  return (
    <AuthGuard requireAuth>
      <Layout>
        <Header />
        <Sidebar />
        <main>{/* Your content */}</main>
      </Layout>
    </AuthGuard>
  )
}

5. Configure API Client

Create your API clients with the configurable factory:

import { createApiClient } from 'cml-webui-commons'

// Create a client for your API
const apiClient = createApiClient({
  baseURL: 'https://api.example.com/v1',
  refreshTokenUrl: 'https://api.example.com/v1/auth/refresh',
  timeout: 30000,
  onUnauthorized: () => {
    // Custom handler for 401 responses
    console.log('Unauthorized! Redirecting...')
  }
})

// Use the client
const response = await apiClient.get('/users')
const user = await apiClient.post('/users', { name: 'John Doe' })

API Client Features

• ✅ Automatic bearer token injection from auth store
• ✅ Automatic token refresh on 401 responses
• ✅ Custom unauthorized handler
• ✅ Configurable timeout and headers
• ✅ TypeScript support with exported types

Core Exports

Components

import {
  // Layout Components
  Layout,
  PageLayout,
  Header,
  Sidebar,

  // Auth Components
  LoginPage,
  AuthGuard,

  // Modals
  Modal,
  AssignRoleModal,
  AssignPermissionModal,

  // UI Security Components
  PasswordStrengthIndicator,
  RoleBadge,
  RoleCard,
  PermissionChip,
  UserStatusBadge,
  UserCard,
  UserTableRow,
} from 'cml-webui-commons'

Hooks

import {
  useAuth,
  usePermissions,
  useRoles,
  useUsers,
} from 'cml-webui-commons'

Services & API

import {
  createApiClient,
  type ApiClientConfig,
  type AxiosInstance,
  type AxiosResponse,
  type AxiosError,
} from 'cml-webui-commons'

Stores (Zustand)

import {
  useAuthStore,
  useThemeStore,
} from 'cml-webui-commons'

Utilities

import { cn } from 'cml-webui-commons'

// Merge class names
const className = cn('base-class', condition && 'conditional-class', 'another-class')

Documentation

For detailed documentation, see the docs folder:

• Components Guide
• Design System
• Authentication Flow
• API Patterns

Package Structure

cml-webui-commons/
├── components       # React components
├── hooks           # Custom React hooks
├── services        # API services and client
├── stores          # Zustand stores
├── contexts        # React contexts
├── types           # TypeScript types
├── schemas         # Zod validation schemas
├── utils           # Utility functions
└── styles          # SCSS and Tailwind preset

Examples

Using the Theme Store

import { useThemeStore } from 'cml-webui-commons'

function ThemeToggle() {
  const { theme, toggleTheme } = useThemeStore()

  return (
    <button onClick={toggleTheme}>
      Current theme: {theme}
    </button>
  )
}

Using Auth Hook

import { useAuth } from 'cml-webui-commons'

function UserProfile() {
  const { user, logout } = useAuth()

  return (
    <div>
      <p>Welcome, {user?.name}</p>
      <button onClick={logout}>Logout</button>
    </div>
  )
}

Protected Routes

import { AuthGuard } from 'cml-webui-commons'

function AdminPage() {
  return (
    <AuthGuard requireAuth requiredRoles={['admin']}>
      <div>Admin Only Content</div>
    </AuthGuard>
  )
}

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Requirements

• React 18.0.0 or 19.0.0
• React DOM 18.0.0 or 19.0.0
• React Router DOM 6.0.0 or 7.0.0
• Node.js >= 20.0.0
• npm >= 10.0.0

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

License

MIT © CodingMonkeyLabs

Author

CodingMonkeyLabs

• GitHub: @codingmonkeylabs

Changelog

See CHANGELOG.md for version history and updates.