@erpsquad/common

A comprehensive React component library for ERP applications, built with Material-UI and TypeScript. This library provides 100+ reusable UI components, theming system, utilities, hooks, and optional Redux integration for building modern ERP applications.

🚀 Features

• 100+ UI Components: Comprehensive set of form controls, data display, navigation, and layout components
• Material-UI Integration: Built on top of Material-UI with custom theming
• TypeScript Support: Full TypeScript definitions for all components and utilities
• Flexible Redux Integration: Optional Redux support - components work with or without Redux
• Theme System: Light/dark themes with RTL/LTR support and customizable colors
• Internationalization: Built-in i18n support with language switching
• ⚡ Optimized Performance: 90%+ bundle size reduction with modular imports and tree-shaking
• 📦 Smart Code Splitting: Automatic chunking for heavy dependencies
• 🚀 Fast Load Times: 75-90% faster with optimized build configuration
• Accessibility: WCAG compliant components with proper ARIA attributes
• Modular Architecture: Import only what you need to minimize bundle size
• Peer Dependency Management: Flexible dependency management for different project setups

⚡ Performance & Deep Imports

New in v1.9.98+: Full deep imports support for maximum performance!

Deep Imports (Recommended)

Import only what you need for optimal bundle size:

// ✅ Deep imports (recommended) - Only ~50-150KB
import { Button } from "@erpsquad/common/components/button";
import { useAuth } from "@erpsquad/common/hooks/useAuth";
import { formatDate } from "@erpsquad/common/utils/dateFormat";

// ❌ Barrel imports (not recommended) - Imports entire library ~2.5MB
import { Button, useAuth, formatDate } from "@erpsquad/common";

Performance Benefits

• 90-97% smaller bundles with deep imports
• 75-90% faster load times with optimized code splitting
• Effective tree-shaking removes unused code automatically
• 250+ individual entry points for components, hooks, utils, contexts, icons, and views

Before: 2.5MB bundle, 5-8s load time
After: 150-300KB bundle, 1-2s load time

Quick Start with Deep Imports

// Components
import { Button } from "@erpsquad/common/components/button";
import { TextField } from "@erpsquad/common/components/text-field";
import { MaterialTable } from "@erpsquad/common/components/material-table";
import ProtectedRoute from "@erpsquad/common/components/protected-route";

// Hooks
import { useAuth } from "@erpsquad/common/hooks/useAuth";
import { usePermissions } from "@erpsquad/common/hooks/use-permissions";

// Utils
import { formatDate } from "@erpsquad/common/utils/dateFormat";
import { api } from "@erpsquad/common/utils/api";

// Contexts
import { AuthProvider } from "@erpsquad/common/contexts/AuthContext";

📚 See Complete Reference for all 700+ import paths
📋 See Quick Reference for common imports
📖 See Deep Imports Guide for complete documentation

Development Environment

For local development, you can create a .env file in your project root with these variables. Make sure to add .env to your .gitignore file to keep sensitive information secure.

Production Deployment

For production deployments, set these environment variables in your hosting environment's configuration panel.

📦 Installation

npm install @erpsquad/common

Peer Dependencies

The library uses peer dependencies to avoid version conflicts and reduce bundle size. Install the dependencies you need based on your usage:

Required (Core functionality)

npm install react react-dom @mui/material @emotion/react @emotion/styled @mui/icons-material

Optional (Feature-specific)

For Redux integration:

npm install @reduxjs/toolkit react-redux

For date components:

npm install @mui/x-date-pickers date-fns

For data grid components:

npm install @mui/x-data-grid

For routing utilities:

npm install react-router-dom

For internationalization:

npm install react-i18next i18next

For utility functions:

npm install lodash axios

Complete Installation (All features)

# Install all peer dependencies for full functionality
npm install react react-dom @mui/material @emotion/react @emotion/styled @mui/icons-material @reduxjs/toolkit react-redux @mui/x-date-pickers @mui/x-data-grid date-fns react-router-dom react-i18next i18next lodash axios

🎯 Quick Start

⚠️ IMPORTANT: Import Styles

Before using any components, you MUST import the CSS file in your main application file:

// main.tsx or App.tsx or index.tsx
import '@erpsquad/common/style.css'; // 👈 REQUIRED - Import this first!

Without this import, components will render but have no styling.

⚡ Performance Best Practice

Use modular imports for optimal bundle size:

// ✅ Good - Only loads what you need (recommended)
import { Button, TextField } from '@erpsquad/common/components';
import { useAuth } from '@erpsquad/common/hooks';
import { formatDate } from '@erpsquad/common/utils';

// ❌ Avoid - Loads entire library (deprecated in v2.0.0)
import { Button, useAuth, formatDate } from '@erpsquad/common';

Impact: 90%+ bundle size reduction, 75%+ faster load times

📚 See Performance Migration Guide for migration steps

Core Usage (Minimal dependencies)

The library provides core functionality without requiring all peer dependencies:

import React from 'react';
// ⚠️ IMPORTANT: Import styles first (in your main file)
import '@erpsquad/common/style.css';

import {
    configureLibrary,
    getLibraryConfig,
    images,
    DEFAULT_LANG,
    type LibraryConfig
} from '@erpsquad/common';

// Configure library for your application
const config: LibraryConfig = {
    routes: {
        login: '/auth/login',
        dashboard: '/dashboard'
    },
    validation: {
        emailRequired: true,
        phoneRequired: false
    },
    dataTransforms: {
        dateFormat: 'dd/MM/yyyy'
    }
};

configureLibrary(config);

function App() {
    const currentConfig = getLibraryConfig();

    return (
        <div>
            <img src={images.logo} alt='Logo' />
            <p>Default language: {DEFAULT_LANG}</p>
            <p>Login route: {currentConfig.routes?.login}</p>
        </div>
    );
}

export default App;

Available Core Exports

The following exports are available without peer dependencies:

// Configuration system
import {
    configureLibrary,
    getLibraryConfig,
    getConfigFunction,
    type LibraryConfig
} from '@erpsquad/common';

// Static assets
import { default as images } from '@erpsquad/common';

// Constants
import { DEFAULT_LANG, LANGUAGES, S3_BUCKET_URL } from '@erpsquad/common';

// TypeScript types
import type {
    BaseComponentProps,
    ThemeConfig,
    SelectOption,
    TableColumn,
    User,
    Permission
} from '@erpsquad/common';

Full Usage (With peer dependencies)

After installing peer dependencies, you can use all components:

import React from 'react';
// ⚠️ Import styles first!
import '@erpsquad/common/style.css';

// Note: Import from specific paths to avoid dependency issues
import { ERPUIProvider } from '@erpsquad/common/contexts';
import { Button, TextField } from '@erpsquad/common/components';

function App() {
    return (
        <ERPUIProvider>
            <div>
                <TextField label='Name' variant='outlined' />
                <Button variant='contained' color='primary'>
                    Submit
                </Button>
            </div>
        </ERPUIProvider>
    );
}

export default App;

With Custom Theme

import React from 'react';
// ⚠️ Import styles first!
import '@erpsquad/common/style.css';

import { ERPUIProvider } from '@erpsquad/common/contexts';
import { Button } from '@erpsquad/common/components';
import { createLightTheme } from '@erpsquad/common/theme';

function App() {
    const { theme } = createLightTheme('#2196f3', 'ltr');

    return (
        <ERPUIProvider
            theme={theme}
            themeMode='dark'
            primaryColor='#2196f3'
            enableCssBaseline={true}>
            <Button variant='contained'>Dark Theme Button</Button>
        </ERPUIProvider>
    );
}

🎨 Theme System

The library includes a comprehensive theming system with support for light/dark modes, RTL/LTR direction, and custom colors.

Theme Configuration

import { ERPUIProvider } from '@erpsquad/common/contexts';

<ERPUIProvider
    themeMode='light' // 'light' | 'dark'
    primaryColor='#1976d2' // Any valid color
    direction='ltr' // 'ltr' | 'rtl'
    enableCssBaseline={true}>
    <App />
</ERPUIProvider>;

Custom Theme Object

import { createLightTheme, createDarkTheme } from '@erpsquad/common/theme';
import { ERPUIProvider } from '@erpsquad/common/contexts';

// Create custom theme
const { theme } = createLightTheme('#1976d2', 'ltr');

// Or create dark theme
const { darkTheme } = createDarkTheme('#1976d2', 'ltr');

<ERPUIProvider theme={theme}>
    <App />
</ERPUIProvider>;

Available Colors

The library supports various color formats:

• Hex colors: #1976d2
• RGB: rgb(25, 118, 210)
• Color names: blue, red, green
• Material-UI color objects

🎨 Styles & SCSS

The library provides a comprehensive styling system with compiled CSS, SCSS variables, mixins, utility classes, and animations.

Import Compiled CSS (Recommended)

Add this to your main application file:

// main.tsx or App.tsx
import '@erpsquad/common/style.css';

This gives you:

• All component styles
• Utility classes for rapid development
• Responsive styles
• Animations

Using Utility Classes

<div className="d-flex justify-content-center align-items-center mb-2">
  <h1 className="h2 bold">Welcome</h1>
  <p className="s2 normal text-center">Description text</p>
</div>

Available utility classes:

• Layout: d-flex, flex-direction-column, justify-content-center, align-items-center
• Spacing: mb-1, mt-2, p-0, pl-2 (padding/margin utilities)
• Typography: h1-h5 (headings), s1-s5 (body text), bold, medium, normal
• Width/Height: w-100, w-50, h-100, vh-100
• Text Alignment: text-center, text-left, text-right

Using SCSS Variables (Advanced)

Import SCSS variables in your .scss files:

// your-component.scss
@import '@erpsquad/common/styles/variables';

.custom-component {
  background-color: $primary-600;
  color: $neutral-100;
  border: 1px solid $neutral-300;
}

Available color scales (100-1000):

• $primary-* (green), $neutral-* (gray), $error-* (red)
• $blue-*, $magenta-*, $olive-*, $green-*, $lightGreen-*

Using SCSS Mixins (Advanced)

// your-component.scss
@import '@erpsquad/common/styles/mixins';

.responsive-layout {
  @include flex(center, space-between, row);
  
  @include media-md {
    flex-direction: column;
  }
}

Available mixins:

• @include flex($align, $justify, $direction) - Flexbox shorthand
• @include transition($time, $motion) - Transition shorthand
• @include center - Absolute center positioning
• Responsive breakpoints: @include media-sm, @include media-md, @include media-l, etc.

Import All SCSS Features

// For complete access to variables, mixins, utilities, and animations
@import '@erpsquad/common/styles/all';

📚 For detailed styles documentation, see:

• Complete Styles Documentation
• Styles Usage Guide
• Migration Guide

📁 Modular Import System

The library uses a modular import system to prevent dependency issues. Import from specific paths based on your needs:

// Core functionality (no peer dependencies required)
import { configureLibrary, images } from '@erpsquad/common';

// Components (requires React, MUI peer dependencies)
import { Button, TextField } from '@erpsquad/common/components';

// Hooks (requires React peer dependencies)
import { useAuth, useLanguage } from '@erpsquad/common/hooks';

// Contexts (requires React peer dependencies)
import { ERPUIProvider, AuthProvider } from '@erpsquad/common/contexts';

// Theme utilities (requires MUI peer dependencies)
import { createLightTheme, createDarkTheme } from '@erpsquad/common/theme';

// Utility functions (may require specific peer dependencies)
import { formatDate, validateEmail } from '@erpsquad/common/utils';

// Redux integration (requires Redux peer dependencies)
import { createLibraryStore, slices } from '@erpsquad/common/redux';

// API clients (requires axios peer dependency)
import { AccountingAPI, InventoryAPI } from '@erpsquad/common/api-client';

// Styles (CSS bundle - recommended)
import '@erpsquad/common/style.css';

// Styles (SCSS imports for advanced usage)
// Import in .scss files only:
// @import '@erpsquad/common/styles/variables';
// @import '@erpsquad/common/styles/mixins';
// @import '@erpsquad/common/styles/all';

🔌 API Clients

The library includes pre-configured API clients for different ERP modules:

import {
    AccountingAPI,
    InventoryAPI,
    ManufacturingAPI,
    PurchaseAPI,
    SalesAPI,
    RentalAPI,
    RbacAPI,
    DriveAPI,
    SystemFeatureAPI
} from '@erpsquad/common/api-client';

// Configure base API client
const baseConfig = {
    baseURL: 'https://api.example.com',
    timeout: 10000,
    headers: {
        'Content-Type': 'application/json'
    }
};

// Use specific API clients
const accountingClient = new AccountingAPI(baseConfig);
const inventoryClient = new InventoryAPI(baseConfig);

// Example usage
const users = await accountingClient.getUsers();
const products = await inventoryClient.getProducts();

🔧 Components

Form Controls

import {
  TextField,
  Select,
  DatePicker,
  Checkbox,
  Radio,
  ToggleSwitch,
  Button
} from '@erpsquad/common/components';

// Text input
<TextField
  label="Email"
  type="email"
  variant="outlined"
  required
/>

// Select dropdown
<Select
  label="Country"
  options={countries}
  value={selectedCountry}
  onChange={handleCountryChange}
/>

// Date picker (requires @mui/x-date-pickers)
<DatePicker
  label="Birth Date"
  value={birthDate}
  onChange={setBirthDate}
/>

Data Display

import {
  MaterialTable,
  Grid,
  CardWrapper,
  Avatar,
  Chip
} from '@erpsquad/common/components';

// Data table (requires @mui/x-data-grid)
<MaterialTable
  columns={columns}
  data={data}
  title="Users"
  options={{
    search: true,
    pagination: true,
    sorting: true
  }}
/>

// Grid layout
<Grid container spacing={2}>
  <Grid item xs={12} md={6}>
    <CardWrapper>Content</CardWrapper>
  </Grid>
</Grid>

Navigation

import {
  Sidebar,
  BreadCrumb,
  Pagination,
  Tabs
} from '@erpsquad/common/components';

// Sidebar navigation
<Sidebar
  items={navigationItems}
  collapsed={isCollapsed}
  onItemClick={handleNavigation}
/>

// Breadcrumb (requires react-router-dom for navigation)
<BreadCrumb
  items={[
    { label: 'Home', href: '/' },
    { label: 'Users', href: '/users' },
    { label: 'Profile' }
  ]}
/>

Feedback

import {
  CustomSnackbar,
  Toast,
  Loader,
  Alert,
  Modal
} from '@erpsquad/common/components';

// Loading indicator
<Loader size="large" text="Loading data..." />

// Alert message
<Alert severity="success" onClose={handleClose}>
  Operation completed successfully!
</Alert>

// Snackbar notification
<CustomSnackbar
  open={isOpen}
  message="Operation completed successfully!"
  severity="success"
  onClose={handleClose}
/>

// Modal dialog
<Modal
  open={isOpen}
  onClose={handleClose}
  title="Confirm Action"
  actions={[
    { label: 'Cancel', onClick: handleClose },
    { label: 'Confirm', onClick: handleConfirm, variant: 'contained' }
  ]}
>
  Are you sure you want to proceed?
</Modal>

🔄 Redux Integration

The library provides flexible Redux integration that works with or without Redux. Requires @reduxjs/toolkit and react-redux peer dependencies.

With Redux (Recommended for complex applications)

import { ERPUIProvider } from '@erpsquad/common/contexts';
import {
    createLibraryStore,
    createConfiguredApiClient
} from '@erpsquad/common/redux';
import { ShareModal } from '@erpsquad/common/components';

// Configure API client
const apiClient = createConfiguredApiClient(baseApiClient, () => ({
    authorization: `Bearer ${getAuthToken()}`
}));

// Create store with library slices
const store = createLibraryStore(
    {
        // Your app reducers
        app: appReducer,
        user: userReducer
    },
    apiClient
);

function App() {
    return (
        <ERPUIProvider useRedux={true} reduxStore={store} apiClient={apiClient}>
            <ShareModal useRedux={true} />
        </ERPUIProvider>
    );
}

Without Redux (Simpler applications)

import { ERPUIProvider } from '@erpsquad/common/contexts';
import { ShareModal } from '@erpsquad/common/components';

function App() {
    const [users, setUsers] = useState([]);
    const [loading, setLoading] = useState(false);

    const fetchUsers = async () => {
        setLoading(true);
        try {
            const response = await api.getUsers();
            setUsers(response.data);
        } finally {
            setLoading(false);
        }
    };

    return (
        <ERPUIProvider useRedux={false}>
            <ShareModal
                useRedux={false}
                users={users}
                loading={loading}
                onFetchUsersAndDepartments={fetchUsers}
            />
        </ERPUIProvider>
    );
}

Available Redux Slices

• shareSlice: User and department data for sharing functionality
• headerSlice: Language data and current language selection
• reportsTitleBarSlice: Company data for reports filtering
• inventoryReportsTitleBarSlice: Inventory-related data for reports

🪝 Hooks

Custom Hooks

import {
    useAuth,
    useLanguage,
    usePermissions,
    usePages,
    useDeepMemo,
    useReduxIntegration
} from '@erpsquad/common/hooks';

// Authentication hook
const { user, isAuthenticated, login, logout } = useAuth();

// Language hook (requires react-i18next)
const { currentLanguage, changeLanguage, t } = useLanguage();

// Permissions hook
const { hasPermission, checkPermission } = usePermissions();

// Deep memoization hook
const memoizedValue = useDeepMemo(() => expensiveCalculation(data), [data]);

Redux Integration Hook

import { useReduxIntegration } from '@erpsquad/common/hooks';

const MyComponent = ({ useRedux, ...props }) => {
    const { data, loading, error, actions } = useReduxIntegration({
        useRedux,
        sliceName: 'share',
        fallbackData: props.users,
        fallbackLoading: props.loading,
        fallbackActions: {
            fetchData: props.onFetchUsers
        }
    });

    // Component logic using unified interface
};

🛠️ Utilities

Common Utilities

import {
    formatDate,
    formatFileSize,
    formatText,
    deformatText,
    colorUtils
} from '@erpsquad/common/utils';

// Date formatting (requires date-fns)
const formattedDate = formatDate(new Date(), 'dd/MM/yyyy');

// File size formatting
const fileSize = formatFileSize(1024000); // "1.02 MB"

// Text formatting
const formatted = formatText('hello world', 'title'); // "Hello World"

// Color utilities
const hexColor = colorUtils.rgbToHex(255, 0, 0); // "#ff0000"

🌐 Internationalization

Requires react-i18next and i18next peer dependencies.

Language Provider

import { ERPUIProvider } from '@erpsquad/common/contexts';

<ERPUIProvider
    enableLanguage={true}
    // Other props
>
    <App />
</ERPUIProvider>;

Using Translations

import { useLanguage } from '@erpsquad/common/hooks';

const MyComponent = () => {
    const { t, currentLanguage, changeLanguage } = useLanguage();

    return (
        <div>
            <p>{t('common.welcome')}</p>
            <button onClick={() => changeLanguage('es')}>Switch to Spanish</button>
        </div>
    );
};

🧪 Testing

The library includes comprehensive testing utilities:

import { render, screen } from '@testing-library/react';
import { ERPUIProvider } from '@erpsquad/common/contexts';
import { Button } from '@erpsquad/common/components';

test('renders button correctly', () => {
    render(
        <ERPUIProvider>
            <Button>Click me</Button>
        </ERPUIProvider>
    );

    expect(screen.getByRole('button')).toBeInTheDocument();
});

📚 API Reference

ERPUIProvider Props

Component Props

All components extend their respective Material-UI component props with additional ERP-specific functionality. Refer to individual component documentation for detailed prop information.

🔧 Development

Building the Library

# Production build
npm run build

# Build with analysis
npm run build:analyze

# Build with validation
npm run build:validate

# Clean build artifacts
npm run clean

Running Tests

# Run all tests
npm test

# Run tests in CI mode
npm run test:ci

# Type checking
npm run type-check

# Linting
npm run lint
npm run lint:fix

Package Validation

# Validate package structure
npm run validate:package

# Check bundle size limits
npm run size-check

# Full validation (lint + type-check + test + build)
npm run validate

📈 Bundle Analysis

# Analyze bundle size and composition
npm run build:analyze

# Check size limits against configuration
npm run size-check

# Validate package contents before publishing
npm run validate:package

🚨 Troubleshooting

Common Issues

⚠️ Components Have No Styling

Problem: Components render but have no styling / look unstyled.

Solution: You MUST import the CSS file in your application:

// In your main file (main.tsx, App.tsx, or index.tsx)
import '@erpsquad/common/style.css'; // 👈 Add this!

// Then import components
import { Button } from '@erpsquad/common/components';

Why: Component styles are bundled separately for optimal tree-shaking and loading performance. The CSS file must be explicitly imported once in your application entry point.

Import Errors

# Error: Cannot resolve '@erpsquad/common/components'
# Solution: Install required peer dependencies
npm install @mui/material @emotion/react @emotion/styled

# Error: Module not found
# Solution: Use correct import paths
import { Button } from '@erpsquad/common/components'; // ✅ Correct
import { Button } from '@erpsquad/common'; // ❌ Incorrect for components

Peer Dependency Warnings

# Warning: peer dependency not installed
# Solution: Install the specific peer dependency
npm install react-redux @reduxjs/toolkit

# Or install all peer dependencies
npm install react react-dom @mui/material @emotion/react @emotion/styled @mui/icons-material

TypeScript Errors

# Error: Cannot find type definitions
# Solution: Ensure TypeScript types are properly imported
import type { LibraryConfig } from '@erpsquad/common';

# Error: Module has no exported member
# Solution: Check if the export requires peer dependencies
import { useAuth } from '@erpsquad/common/hooks'; // Requires React

Build Issues

# Error: Module not found during build
# Solution: Check if all peer dependencies are installed
# and properly configured in your build tool

# For Vite projects, add to vite.config.ts:
export default defineConfig({
  optimizeDeps: {
    include: ['@erpsquad/common']
  }
});

# For Webpack projects, ensure proper externals configuration

Getting Help

• Check the troubleshooting guide
• Review migration documentation
• Search existing issues
• Create a new issue

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-component
3. Make your changes and add tests
4. Run tests: npm test
5. Run linting: npm run lint
6. Commit your changes: git commit -m 'Add new component'
7. Push to the branch: git push origin feature/new-component
8. Submit a pull request

Development Guidelines

• Follow TypeScript best practices
• Write comprehensive tests for new components
• Update documentation for API changes
• Ensure accessibility compliance
• Maintain backward compatibility

📄 License

MIT License - see the LICENSE file for details.

🆘 Support

• Documentation: Library Docs
• Issues: GitHub Issues
• NPM Package: @erpsquad/common
• Changelog: CHANGELOG.md
• Migration Guide: MIGRATION.md
• Troubleshooting: TROUBLESHOOTING.md

📚 Performance Documentation

• Performance Guide: PERFORMANCE_GUIDE.md - Optimization tips and best practices
• Performance Migration: PERFORMANCE_MIGRATION.md - Step-by-step migration guide
• Performance Analysis: PERFORMANCE_ANALYSIS.md - Technical deep-dive
• Optimization Summary: OPTIMIZATION_SUMMARY.md - Quick overview

📋 Changelog

See CHANGELOG.md for a detailed list of changes and version history.