Skip to main content

Development Workflow

This guide walks you through the complete process of creating a new application using @xond/api, from database design to running your generated API.

Overview​

The Xond workflow follows these steps:

  1. Design your database schema
  2. Create database structure from SQL files
  3. Reverse engineer Prisma schema from database
  4. Generate REST API endpoints and frontend models
  5. Insert reference and dummy data

Step-by-Step Guide​

Step 1: Design Your Database​

Design your database using any database design tool (PowerDesigner, MySQL Workbench, pgAdmin, etc.). Export your schema as SQL CREATE statements.

Example SQL file (create-struct-0.0.1.sql):

CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  username VARCHAR(255) NOT NULL UNIQUE,
  email VARCHAR(255) NOT NULL UNIQUE,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE posts (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID REFERENCES users(id),
  title VARCHAR(255) NOT NULL,
  content TEXT,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Step 2: Prepare Excel Reference File​

Create an Excel file (Master Data & Dummy v1.0.0.xlsx) with worksheets for each table containing reference and dummy data. The first row should contain column names matching your database columns.

Example structure:

idusernameemailcreated_at
00000000-0000-0000-0000-000000000001adminadmin@example.com2024-01-01
00000000-0000-0000-0000-000000000002user1user1@example.com2024-01-02

Step 3: Configure Environment​

Update your .env file with paths to your SQL and Excel files:

DATABASE_STRUCTURE_FILE=/absolute/path/to/create-struct-0.0.1.sql
DATABASE_DUMMY_FILE=/absolute/path/to/Master Data & Dummy v1.0.0.xlsx

Step 4: Create Database Structure​

Run the create command to execute your SQL file and build the database:

pnpm xond:create

This will:

  • Execute all CREATE TABLE statements from your SQL file
  • Create indexes, constraints, and relationships
  • Verify the structure was created successfully

With verbose output:

pnpm xond:create --verbose

Step 5: Reverse Engineer Prisma Schema​

Pull the database schema into Prisma:

pnpm prisma:reverse

This generates prisma/schema.prisma with models matching your database tables.

Step 6: Correct Prisma Schema Format​

Format the Prisma schema for better coding convenience:

pnpm prisma:correct

This uses prisma-case-format to pluralize model names and normalize casing.

Step 7: Shorten Relation Names​

Prisma generates long relation names for foreign keys. Shorten them:

pnpm xond:shorten

This makes relation names more readable and manageable.

Step 8: Generate Prisma Client​

Generate the Prisma Client for TypeScript:

pnpm prisma:generate

Step 9: Generate API Code​

Generate REST endpoints, services, and frontend models:

pnpm xond:generate

This creates:

  • Backend: JSON service files in src/modules/json/services/generated/
  • Frontend: TypeScript models in ../your-ui-app/src/generated/models/
  • Schema: Type definitions in prisma/schema.ts

Step 10: Insert Reference Data​

Insert data from your Excel file:

pnpm xond:insert

This reads each worksheet and inserts rows into corresponding database tables.

Complete Workflow Script​

For convenience, you can run all steps in sequence:

pnpm regen:all

This executes:

  1. xond:check - Verify environment
  2. xond:create - Create database structure
  3. prisma:reverse - Pull schema
  4. prisma:correct - Format schema
  5. xond:shorten - Shorten relations
  6. prisma:generate - Generate Prisma client
  7. xond:generate - Generate API code
  8. xond:insert - Insert dummy data

Updating Existing Schema​

When you modify your database design:

  1. Update your SQL file with ALTER TABLE statements
  2. Run pnpm xond:update to apply changes
  3. Run pnpm prisma:reverse to refresh Prisma schema
  4. Run pnpm xond:generate to regenerate code

Common Workflows​

Regenerate Only Code (After Schema Changes)​

pnpm regen

This runs xond:generate to update generated files without touching the database.

Re-insert Data​

pnpm reinsert

This runs xond:insert to reload data from your Excel file.

Regenerate Prisma Client Only​

pnpm regen:prisma

Useful when Prisma schema changes but database structure remains the same.

Next Steps​