CRUD Bundle

Version: 2.80.0 | TypeScript Files: 97 (74 TSX + 23 TS) | Components: 49+

Introduction

A powerful CRUD (Create, Read, Update, Delete) components library that transforms complex data operations into simple, reusable components. Built for Next.js 14+ with React 18+, TypeScript 5+, and Tailwind CSS.

Quick Navigation

Installation

To use @phpcreation/frontend-crud-react-nextjs-bundle in your project, follow these steps:

npm login --scope=@phpcreation --auth-type=legacy --registry=https://npm.pkg.github.com

npm install @phpcreation/frontend-crud-react-nextjs-bundle

Setup

Environment Variables

Follow these steps to manage environment variables correctly :

# App Id
NEXT_PUBLIC_APP_ID= # The App Id
 
# Feedback form
NEXT_PUBLIC_TICKET_FEEDBACK= # The URL to the feedback form
 
# Icons
NEXT_PUBLIC_ICONS_URL= # The url provided by the ICONS Library (@phpcreation/frontend-icons-react-nextjs-bundle)
 
# Components Bundle
NEXT_PUBLIC_DROPDOWN_API_SUFFIX = 1 # 0 - Don't add suffix to dropdown API call (/dropdown) instead of (/dropdown/get)
 
# CRUD Bundle - The fun configuration part!
NEXT_PUBLIC_Role_Accessibility_Check = 0 # 0 = No role checks (perfect for development)
NEXT_PUBLIC_KVS_DATA_STORE_TOGGLE = 0 # 0 = Skip KVS (Key-Value Store for user preferences)
NEXT_PUBLIC_KVS_API_RESOURCE_NAME = "key_values" # OPTIONAL - Custom KVS resource name
NEXT_PUBLIC_USE_PUT_METHOD = 0 # 0 = Use PATCH instead of PUT (recommended for partial updates)
NEXT_PUBLIC_IMPORT_FEATURE_TOGGLE  = 0 # 0 = Hide import buttons (set to 1 to enable bulk imports)

Project Structure

The CRUD bundle v2.80.0 follows a structured architecture with 97 TypeScript files across 89 directories:

src/
├── components/              # 20 component directories (61 files)
│   ├── ActionButtons/       # Reusable action buttons with dropdown support
│   ├── AddEntity/           # Form, Footer for creating entities
│   ├── DebugFooter/         # Debug information display
│   ├── DetailShow/          # Actions, Associations, File, Footer, GeneralDetails, Header
│   ├── DraggableDropdown/   # Drag and drop functionality
│   ├── EditEntity/          # Form for editing entities
│   ├── ImportEntity/        # DocumentationSidebox, FileUploader, ImportForm, ImportTable, ReviewContainer
│   ├── InfoBadge/           # Information badges
│   ├── Listing/             # 9 sub-components: Actions, DefaultFiltersMenu, Filters, Footer, Header, KanbanBoard, ListingTable, Pagination, QueryString
│   ├── MetadataEntity/      # APITab, FieldsTab, Footer, Header, InterfacesTab, OverviewTab
│   ├── MetadataFooter/      # Metadata footer component
│   ├── Modals/              # 16 modal types (see Modal Components)
│   ├── Navbar/              # Navigation with breadcrumbs
│   ├── QueryString/         # URL query string management
│   ├── RenderFilterFields/  # Dynamic filter rendering (431 lines)
│   ├── RenderFormFields/    # Dynamic form rendering (360 lines)
│   ├── SidebarMenu/         # Collapsible sidebar navigation
│   ├── Sidebox/             # Contextual sidebar content
│   ├── Tour/                # Guided tours with CustomTooltip
│   └── TranslatableFields/  # Multi-language field support
├── contexts/                # 4 React contexts
│   ├── DebugContext/        # Debugging utilities
│   ├── DetailShowContext/   # Entity detail view state
│   ├── KanbanListingContext/# Kanban board state & drag-drop
│   └── ListingContext/      # Data listing, filtering, pagination
├── sitedata/                # 7 data modules
│   ├── AddFilterModal/      # Filter modal configuration
│   ├── Countries/           # Country data
│   ├── Dashboard/           # Dashboard configuration
│   ├── DefaultTime/         # Time zone defaults
│   ├── Help/                # Help content
│   ├── ImportJobDocumentation/ # Import documentation
│   └── SystemFields/        # System field definitions
├── styles/                  # Global CSS (globals.css)
└── utils/
    ├── HOC/                 # getPageConfig
    ├── default/             # TenantWhitelist, TenantIgnorelist
    ├── functions/           # 9 utility functions
    │   ├── formatEntityName
    │   ├── validateFormSchema
    │   ├── callAPI
    │   ├── getTenant
    │   ├── getTenantBackend
    │   ├── importEntitySchema
    │   ├── logger
    │   ├── getUpdatedFormFields
    │   └── verifyUser
    └── hooks/               # 6 custom hooks
        ├── useKVS
        ├── useTreeView
        ├── useFormValues
        ├── useDefaultFormValues
        ├── useScrollToError
        └── useActionButtons

Core Components

Listing Components

The listing components provide comprehensive data table functionality:

• ListingTable: Main table component with sorting, filtering, and pagination
• ListingActions: Action buttons for bulk operations (delete, edit, etc.)
• ListingFilters: Advanced filtering interface
• KanbanBoard: Kanban-style board view for data visualization
• TablePagination: Pagination controls for large datasets

Entity Management

Entity management components handle the complete CRUD lifecycle:

• AddEntityForm: Form component for creating new entities
• EditEntityForm: Form component for editing existing entities
• GeneralDetails: Display component for entity details
• DetailShowHeader: Header component for detail views

Modal Components

The bundle includes various modal dialogs:

• ConfirmationModal: User confirmation dialogs
• QuickAddModal: Quick entity creation
• QuickEdit: Quick entity editing
• ImportModal: Bulk data import interface
• TranslationModal: Multi-language content management
• ImageModal: Image viewing and management

Form Components

Dynamic form rendering with comprehensive field type support:

• RenderFormFields: Dynamic form field rendering based on configuration
• RenderFilterFields: Filter field rendering with validation
• TranslatableFields: Multi-language form field support

Import/Export Features

Bulk data operations with validation and progress tracking:

• ImportEntity: Complete import workflow
• FileUploader: File upload interface
• ImportTable: Preview and validate import data
• ReviewContainer: Review imported data before saving

Context Providers

The bundle uses React Context for state management (4 contexts):

ListingContext

Manages state for data listing views including:

• Current page and pagination
• Applied filters and sorting
• Selected items
• Loading states
• Bulk operations (delete, duplicate)

DetailShowContext

Handles state for entity detail views:

• Current entity data
• Edit mode state
• Related entity information
• Fields and sections configuration

KanbanListingContext

Manages kanban board state:

• Column configurations with visibility toggling
• Drag and drop operations via react-beautiful-dnd
• URL-based column persistence
• Column color customization (10 default colors)

DebugContext

Provides debugging utilities:

• Debug mode toggling
• Development helpers

Utility Functions

Core Functions

• CallAPI: Centralized API calling with error handling
• formatEntityName: Entity name formatting utilities
• getTenant: Tenant information retrieval
• importEntitySchema: Schema validation for imports
• validateFormSchema: Form validation using Zod

Custom Hooks (6 hooks)

• useKVS: Key-value store integration for user preferences
• useTreeView: Tree view navigation and management
• useFormValues: Form value handling and state
• useDefaultFormValues: Default form value initialization
• useScrollToError: Scroll to form validation errors
• useActionButtons: Action button configuration and state management

Additional Components

The bundle also includes navigation and utility components:

• ActionButtons: Flexible action button system with customizable layouts
• Navbar: Main navigation with breadcrumbs and user actions
• SidebarMenu: Collapsible sidebar with hierarchical navigation
• Sidebox: Contextual sidebar for additional information
• DraggableDropdown: Drag-and-drop enabled dropdown components
• AdminFooter: Admin interface footer component

Metadata Components

The bundle includes a comprehensive metadata management system:

• MetadataEntity: Entity metadata management and API documentation
• OverviewTab: Basic entity information and statistics
• FieldsTab: Detailed field information with types and relationships
• APITab: Generated API documentation for entities
• InterfacesTab: Interface and schema documentation

Styling and Themes

The bundle uses Tailwind CSS for styling with:

• Responsive design principles
• Dark/light theme support
• Consistent spacing and typography
• Customizable color schemes

Global styles are located in src/styles/globals.css and follow the design system patterns.

Dependencies

Key dependencies include:

Usage Examples

Basic Listing Implementation

import {
  ListingTable,
  ListingContextProvider,
  ListingActions,
} from "@phpcreation/frontend-crud-react-nextjs-bundle/components";
 
function MyListing() {
  return (
    <ListingContextProvider>
      <ListingActions resource="users" />
      <ListingTable resource="users" columns={columns} data={data} />
    </ListingContextProvider>
  );
}

Form Integration

import {
  AddEntityForm,
  RenderFormFields,
} from "@phpcreation/frontend-crud-react-nextjs-bundle/components";
 
function CreateUser() {
  return (
    <AddEntityForm
      resource="users"
      formInputs={userFormFields}
      fqcn_bui={fqcnConfig}
      onSuccess={handleSuccess}
    />
  );
}

Common Issues