CRUD Generator v2

A Node.js CLI tool that generates versioned CRUD configuration files for React/Next.js applications. It uses a two-layer architecture (JSON + TSX) with independent versioning for managing field selections and frontend configurations.

Current Version: 2.44.1 | Branch: main-v2 | Size: 158MB | Config Files: 1,387+

GitHub Repository

Quick Start

Install the Generator


git clone https://github.com/PHPCreation/frontend-components-crud-react-generator.git
cd frontend-components-crud-react-generator
npm install
chmod +x index.js

Generate JSON from API


./index.js generateJson \
  --entity=AccountingBundle/Account \
  --bundleCrud=phprCrud \
  --baseUrl=https://demo.phpreaction.com/open-api/v3

Generate TSX Configuration


./index.js generateTsx \
  --entity=AccountingBundle/Account \
  --bundleCrud=phprCrud

Export to Your Project


./index.js exportEntity \
  --entity=AccountingBundle/Account \
  --destination=../my-frontend/src/entities/

Architecture Overview

The generator uses a two-layer versioning system:


config/versioned/
├── json/                          # Data Layer (API metadata)
│   └── {Entity}/
│       └── v0/
│           ├── data.json          # Raw API metadata
│           └── changes.json       # Field selections & customizations
└── tsx/                           # Presentation Layer (React config)
    └── {Entity}/
        └── v0/
            ├── index.tsx          # Generated React configuration
            └── changes.json       # TSX-specific customizations (optional)

JSON Layer: Stores raw API metadata and field selection customizations TSX Layer: Stores generated React/TypeScript frontend configurations

Each layer versions independently, allowing non-breaking changes to field selections without regenerating TSX files.

Commands Reference

JSON Layer Commands

Command	Alias	Description
`generateJson`	`gen:json`	Generate JSON v0 from API metadata
`generateJsonAll`	-	Generate JSON for ALL entities in bundle
`generateJsonMigration`	-	Create changes.json template
`matchScraperFields`	`match:scraper`	Match with legacy scraper data, create new version
`checkJsonChanges`	`check:json`	Preview JSON customizations
`listJsonVersions`	-	List all JSON versions for entity

TSX Layer Commands

Command	Alias	Description
`generateTsx`	`gen:tsx`	Generate TSX from JSON version
`generateTsxMigration`	-	Create TSX migration template
`applyTsxChanges`	`apply:tsx`	Apply TSX changes, create new version
`checkTsxChanges`	`check:tsx`	Preview TSX changes
`listTsxVersions`	-	List all TSX versions for entity

Validation & Export Commands

Command	Alias	Description
`validateEntity`	`validate`	Validate JSON/TSX consistency
`validateJson`	`validate:json`	Validate JSON layer only
`validateTsx`	`validate:tsx`	Validate TSX layer only
`validateAll`	-	Validate all entities in bundle
`exportEntity`	-	Export TSX to destination folder

Bundle Commands

Command	Description
`generateVersioned`	Generate JSON + TSX for ALL entities
`token`	Generate authentication token

CLI Flags

Required Flags

Flag	Description
`--entity`	Entity name (e.g., `AccountingBundle/Account`)
`--bundleCrud`	Bundle type: `phprCrud`, `ticketCrud`, `configCrud`, `accountCrud`
`--baseUrl`	API endpoint URL (required for API commands)

Version Flags

Flag	Description
`--jsonVersion`	Specific JSON version to use (e.g., `v0`, `v1`)
`--tsxVersion`	Specific TSX version to use
`--version`	Generic version flag

Cache Flags

Cache flags are mutually exclusive. Use only one at a time.

Flag	Description
`--generateFromApi`	Force fetch from API, override cache
`--generateCacheOnly`	Update cache only, skip TSX generation
`--generateFromCache`	Use cache if available, fallback to API

Other Flags

Flag	Description
`--dryRun`	Preview changes without applying
`--destination`	Export destination path
`--debug` / `-d`	Show debug information

Complete Workflow

Generate Authentication Token


./index.js token \
  --baseUrl=https://demo.phpreaction.com \
  --devUsername=admin \
  --devPassword=demo \
  --bundleCrud=phprCrud

Generate JSON v0 (API Metadata)


./index.js generateJson \
  --entity=AccountingBundle/Account \
  --bundleCrud=phprCrud \
  --baseUrl=https://demo.phpreaction.com/open-api/v3

Creates: config/versioned/json/AccountingBundle/Account/v0/data.json

Create Migration Template


./index.js generateJsonMigration --entity=AccountingBundle/Account

Creates: config/versioned/json/AccountingBundle/Account/v0/changes.json

Match with Legacy Scraper (Optional)


./index.js matchScraperFields --entity=AccountingBundle/Account

Creates new version (v1) with scraper-matched field selections.

Use --dryRun to preview without creating:


./index.js matchScraperFields --entity=AccountingBundle/Account --dryRun

Generate TSX Configuration


./index.js generateTsx \
  --entity=AccountingBundle/Account \
  --bundleCrud=phprCrud

Uses latest JSON version by default. Specify version with:


./index.js generateTsx --entity=AccountingBundle/Account --jsonVersion=v1 --bundleCrud=phprCrud

Creates: config/versioned/tsx/AccountingBundle/Account/v0/index.tsx

Validate Consistency


./index.js validateEntity --entity=AccountingBundle/Account

Checks:

changes.json field validity
Resource name consistency
JSON-TSX field mappings

Export to Frontend Project


./index.js exportEntity \
  --entity=AccountingBundle/Account \
  --destination=../my-crud-frontend/src/entities/

Data Structures

data.json (API Metadata)


{
  "entity": "Account",
  "resourceName": "accounts",
  "implementedInterfaces": ["Stringable", "Disableable"],
  "fields": {
    "name": {
      "fieldName": "name",
      "type": "string",
      "nullable": false,
      "unique": false,
      "format": "string",
      "constraints": {}
    }
  },
  "showFields": {...},
  "listingFields": {...},
  "requiredFields": {...},
  "availableSerializationGroups": [...]
}

changes.json (Customizations)


{
  "listingFields": {
    "all": [],
    "selected": ["id", "name", "status"],
    "hide": ["internalId"]
  },
  "formModalFields": {
    "fields": ["name", "description"],
    "hide": []
  },
  "showFields": {
    "sections": {
      "Information": ["name", "description", "status"],
      "System": ["id", "createdAt", "updatedAt"]
    },
    "hide": []
  },
  "formFields": {
    "sections": {
      "General": ["name", "description"]
    },
    "required": ["name"],
    "optional": ["description"],
    "hide": ["slug"]
  },
  "filterFields": {
    "all": [],
    "defaults": ["status"],
    "hide": []
  },
  "sideboxFields": {
    "all": [],
    "hide": []
  },
  "actions": {
    "listing": ["show", "quick-edit", "edit"],
    "showPage": ["edit", "print", "delete", "export"]
  },
  "exclusionList": {
    "listing": ["password", "token"],
    "forms": ["id", "createdAt"]
  }
}

Field Prioritization: The hide array is processed FIRST, then other customizations are applied. This ensures hidden fields are never accidentally included.

Advanced changes.json Options

The changes.json schema also supports:

Sorting configuration: Define sortable columns
Alignment settings: Left, center, right alignment
Icon fields: Add icons to columns
Sectioning: Group fields into logical sections
Validation rules: Define field validation
Custom range filters: Date and number range filtering
Translatable fields: Mark fields for translation
Helper text: Add contextual help to form fields

Supported Projects

Project	Bundle	Base URL
Configuration	`configCrud`	`dev.config.solidservice.link`
Ticket	`ticketCrud`	`dev.ticket.solidservice.link`
PHPReaction	`phprCrud`	`demo.phpreaction.com`
Account	`accountCrud`	`demo1.dev.account.solidservice.link`

Project Scripts

Shell scripts are available for each project type:

Config


# Legacy generation
./scripts/generate-config-entities.sh legacy
 
# Versioned generation (all entities)
./scripts/generate-config-entities.sh versioned
 
# Single entity versioned
./scripts/generate-config-entities.sh versioned-entity ConfigBundle/Parameter

Ticket


# Legacy generation
./scripts/generate-ticket-entities.sh legacy
 
# Versioned generation (all entities)
./scripts/generate-ticket-entities.sh versioned
 
# Single entity versioned
./scripts/generate-ticket-entities.sh versioned-entity Ticket

PHPReaction


# Legacy generation
./scripts/generate-phpr-entities.sh legacy
 
# Versioned generation (all entities)
./scripts/generate-phpr-entities.sh versioned
 
# Single entity versioned
./scripts/generate-phpr-entities.sh versioned-entity AccountingBundle/Account

Account


# Legacy generation
./scripts/generate-account-entities.sh legacy
 
# Versioned generation (all entities)
./scripts/generate-account-entities.sh versioned
 
# Single entity versioned
./scripts/generate-account-entities.sh versioned-entity User

Batch Operations

Generate All Entities


# Generate JSON for all entities in bundle
./index.js generateJsonAll \
  --bundleCrud=phprCrud \
  --baseUrl=https://demo.phpreaction.com/open-api/v3
 
# Generate JSON + TSX for all entities
./index.js generateVersioned \
  --bundleCrud=phprCrud \
  --baseUrl=https://demo.phpreaction.com/open-api/v3

Validate All Entities


./index.js validateAll \
  --bundleCrud=phprCrud \
  --baseUrl=https://demo.phpreaction.com/open-api/v3

Version Management

List Versions


# List JSON versions
./index.js listJsonVersions --entity=AccountingBundle/Account
 
# List TSX versions
./index.js listTsxVersions --entity=AccountingBundle/Account

Use Specific Version


# Generate TSX from specific JSON version
./index.js generateTsx \
  --entity=AccountingBundle/Account \
  --jsonVersion=v1 \
  --bundleCrud=phprCrud

Preview Changes


# Preview JSON changes
./index.js checkJsonChanges --entity=AccountingBundle/Account
 
# Preview TSX changes
./index.js checkTsxChanges --entity=AccountingBundle/Account

Cache Management

Cache Locations


config/
├── fields/{Bundle}/{Entity}.json         # Field metadata
├── showFields/{Bundle}/{Entity}.json     # Show page fields
├── listingFields/{Bundle}/{Entity}.json  # Listing fields
└── requiredFields/{Bundle}/{Entity}.json # Required fields

Cache Operations


# Force fresh API fetch
./index.js generateJson --entity=Entity --generateFromApi ...
 
# Use cache if available
./index.js generateJson --entity=Entity --generateFromCache ...
 
# Update cache only (no TSX)
./index.js generateJson --entity=Entity --generateCacheOnly ...

Clear Cache


# Clear all cache
rm -rf config/fields/* config/showFields/* config/listingFields/* config/requiredFields/*
 
# Clear specific bundle
rm -rf config/fields/AccountingBundle/

Error Logging

Log Locations

config/logs/errorLogs/ - Detailed JSON error logs
config/logs/errorLogs/error-summary.log - Error summary
config/logs/successLogs/success-summary.log - Success summary

View Logs


# View error summary
cat config/logs/errorLogs/error-summary.log
 
# List recent errors
ls -lt config/logs/errorLogs/
 
# Find entity-specific errors
grep "Account" config/logs/errorLogs/error-summary.log

Processing Summary

After batch operations:


================================================================================
PROCESSING SUMMARY
================================================================================
✅ Successfully processed: 145 entities
❌ Failed: 5 entities

Failed entities:
  - BillBundle/Bill: Connection timeout
  - InvoiceBundle/Invoice: API error 500

📁 Detailed error logs available in: ./config/logs/errorLogs/
================================================================================

Troubleshooting

Problem	Solution
Entity not found	Check entity name format: `BundleName/EntityName`
Authentication failed	Regenerate token with `./index.js token ...`
API connection error	Verify `--baseUrl` is accessible
Multiple cache flags	Use only one cache flag at a time
Invalid changes.json	Run `validateJson` to check field names
TSX generation fails	Ensure JSON version exists with `listJsonVersions`
Export fails	Check destination path has write permissions

File Structure


frontend-components-crud-react-generator/
├── index.js                    # CLI entry point (phpr, phpcrt commands)
├── src/
│   ├── api/                    # API integration
│   ├── commands/
│   │   └── versioned-commands.js   # Command handlers
│   ├── core/
│   │   ├── version-manager.js      # Version management
│   │   └── changes-engine.js       # Apply customizations
│   ├── json/
│   │   ├── json-generator.js       # JSON generation
│   │   └── json-applier.js         # JSON version management
│   ├── legacy/                 # Legacy scraper integration
│   ├── process/                # Processing logic
│   ├── templates/              # Generation templates
│   └── tsx/
│       ├── tsx-generator.js        # TSX generation
│       └── tsx-applier.js          # TSX version management
├── config/                     # 1,387+ configuration files
│   ├── versioned/              # Versioned output
│   │   ├── json/               # JSON layer
│   │   └── tsx/                # TSX layer
│   ├── fields/                 # Field metadata cache
│   ├── showFields/             # Show fields cache
│   ├── listingFields/          # Listing fields cache
│   ├── requiredFields/         # Required fields cache
│   ├── generateBundledFiles/   # Bundle generation
│   ├── generateCrudFiles/      # CRUD file generation
│   ├── generateFiles/          # General file generation
│   ├── locales/                # Localization
│   ├── logs/                   # Error/success logs
│   │   ├── errorLogs/          # Detailed error logs
│   │   └── successLogs/        # Success summaries
│   ├── userRoles/              # Role configurations
│   └── config-template.tsx     # TSX template
├── scripts/                    # Project generation scripts
│   ├── generate-config-entities.sh
│   ├── generate-ticket-entities.sh
│   ├── generate-phpr-entities.sh
│   └── generate-account-entities.sh
└── utils/
    ├── cli.js                  # CLI flags definition
    └── functions.js            # Utility functions

Requirements

Node.js: v18+ (recommended v20+)
Package Manager: npm v6+ or pnpm 10+
OS: macOS, Linux, Windows (with WSL)

CLI Commands

The generator provides two CLI commands:

phpr - Primary CLI command
phpcrt - Alias command

Frontend Project Dependencies

Generated TSX files require:


@phpcreation/frontend-utils-react-nextjs-bundle
@phpcreation/frontend-crud-react-nextjs-bundle

Core Dependencies


{
  "axios": "^1.7.x",
  "dotenv": "^16.x",
  "chalk": "^5.x",
  "cli-alerts": "^2.x",
  "fs-extra": "^11.x",
  "meow": "^13.x"
}