Skip to Content
FrontendCrud V2Crud GeneratorGenerator v2Workflow & Versioning

Workflow & Versioning

Full Workflow

Generate an Auth Token

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

Token is saved to config/token.txt and used automatically by all subsequent commands.

Fetch API Metadata (JSON v0)

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

Creates:

config/versioned/json/AccountingBundle/Account/v0/
  ├── data.json       ← raw metadata from API
  └── changes.json    ← empty customization template

Customise changes.json

Open the generated changes.json and edit your field selections. See the changes.json Reference for all options.

Preview before generating:

./index.js preview:changes \
  --entity=AccountingBundle/Account \
  --version=v0

Validate that all field names exist in the API data:

./index.js validate:changes \
  --entity=AccountingBundle/Account \
  --version=v0

(Optional) Match Legacy Scraper Data

./index.js match:scraper --entity=AccountingBundle/Account
# Preview without writing
./index.js match:scraper --entity=AccountingBundle/Account --dryRun

Generate TSX Configuration

./index.js gen:tsx \
  --entity=AccountingBundle/Account \
  --bundleCrud=phprCrud

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

Pin to a specific JSON version:

./index.js gen:tsx \
  --entity=AccountingBundle/Account \
  --jsonVersion=v1 \
  --bundleCrud=phprCrud

Validate

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

Checks JSON–TSX consistency, resource names, and field mappings.

Export to Frontend Project

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

Incremental Generation

When the API schema changes, create a new JSON version that inherits your customizations instead of starting from scratch.

# Create v1 based on v0 — re-fetches API data, merges your changes.json
./index.js gen:json \
  --entity=AccountingBundle/Account \
  --bundleCrud=phprCrud \
  --baseUrl=https://demo.phpreaction.com/open-api/v3 \
  --fromVersion=v0

What happens internally:

  1. Loads v0/data.json and v0/changes.json
  2. Fetches fresh metadata from the API
  3. Merges your v0 customizations into a new v1/changes.json
  4. Writes updated raw metadata to v1/data.json

Custom field selections, ordering, validation rules, and all other changes.json settings are preserved automatically across versions. Only fields that no longer exist in the API are removed.

Version Management

List Versions

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

Pin to a Specific JSON Version

./index.js gen:tsx \
  --entity=AccountingBundle/Account \
  --jsonVersion=v1 \
  --bundleCrud=phprCrud

Check What Changed Between Versions

./index.js check:json \
  --entity=AccountingBundle/Account \
  --version=v1

Preview & Validate Changes

Always preview and validate before generating TSX.

Preview

Shows what each changes.json section will produce without writing any files:

./index.js preview:changes \
  --entity=AccountingBundle/Account \
  --version=v0

Example output:

LISTING FIELDS
  ✔ selected: id, name, status, createdAt  (4 fields)
  ✖ hidden: internalId, slug

FORM FIELDS
  General: name, description, type  (3 fields)
  Pricing: price, priceSpecial      (2 fields)
  ✖ excluded (MANY_TO_MANY): tags, categories

FILTER FIELDS
  ✔ defaults: status, createdAt
  ✔ range: createdAt, price

Validate

Checks every field name in changes.json against the actual API data:

./index.js validate:changes \
  --entity=AccountingBundle/Account \
  --version=v0

Reports invalid references:

✖ formFields.sections.General → "nonExistentField" not found in API data
✖ filterFields.all → "oldFieldName" removed from API
✔ listingFields: all 4 fields valid

Cache Management

Cache Locations

config/
├── fields/{Bundle}/{Entity}.json         ← form/all fields
├── showFields/{Bundle}/{Entity}.json     ← detail page fields
├── listingFields/{Bundle}/{Entity}.json  ← list view fields
└── requiredFields/{Bundle}/{Entity}.json ← required constraints

Cache Modes

Cache flags are mutually exclusive — use only one per command.

# Always fresh — fetch from API even if cache exists
./index.js gen:json --entity=Bundle/Entity --generateFromApi ...
 
# Smart — use cache if available, fallback to API
./index.js gen:json --entity=Bundle/Entity --generateFromCache ...
 
# Cache only — update cache files, skip generation
./index.js gen:json --entity=Bundle/Entity --generateCacheOnly ...

Clear Cache

# Clear everything
rm -rf config/fields/* config/showFields/* config/listingFields/* config/requiredFields/*
 
# Clear one bundle
rm -rf config/fields/AccountingBundle/

Error Logs

Batch operations write structured logs automatically:

config/logs/
├── errorLogs/
│   ├── error-summary.log        ← quick overview
│   └── {Entity}-error.json      ← full detail per entity
└── successLogs/
    └── success-summary.log
# View summary
cat config/logs/errorLogs/error-summary.log
 
# Find errors for a specific bundle
grep "AccountingBundle" config/logs/errorLogs/error-summary.log

After batch operations the terminal prints:

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

  - BillBundle/Bill         Connection timeout
  - InvoiceBundle/Invoice   API error 500

📁 Detailed logs: ./config/logs/errorLogs/
================================================================================
Last updated on
Architecturechanges.json Reference