Skip to main content

​
Getting Started

Create a new project with the following command:
pnpm create sonamu
Follow the interactive prompts to configure your project:
? Project name: my-app
? Would you like to set up pnpm? Yes
? Would you like to set up a database using Docker? Yes
? Enter the Docker project name: my-app-container
? Enter the database user: postgres
? Enter the container name: my-app-pg
? Enter the database name: my-app
? Enter the database password: ****
Run the project:
# 1. Start the database
cd my-app/api
pnpm db:up

# 2. Start the API server (includes Sonamu UI)
pnpm dev

# 3. In a new terminal, start the Web server
cd my-app/web
pnpm dev
Accessible URLs:
API: http://localhost:1028
Sonamu UI: http://localhost:1028/sonamu-ui
Web: http://localhost:3028
Requirements: Node.js >= 18, pnpm >= 10, Docker
Backend: TypeScript, Node.js, Fastify, Knex.js, PostgreSQL, Zod
Frontend: React, TanStack Query, Axios, Tailwind CSS
Development Tools: pnpm, Docker
Auto-generated: Migration files, TypeScript types, API endpoints, React hooks

​
Development Environment

  1. Instant TypeScript execution
    • Transforms TypeScript files at runtime with @sonamu-kit/ts-loader
    • Registered via Node.js --import flag
  2. Sonamu initialization (Sonamu.init)
    • Load DB configuration
    • Load Entity files
    • Create Syncer and auto-load Types/Models/APIs
    • Run initial sync (syncer.sync())
    • Start file watcher (startWatcher())
  3. Fastify server creation and configuration
    • Register plugins (formbody, multipart, session, etc.)
    • Auth setup (if needed)
    • Register methods with @api decorator as API endpoints
  4. Server starts listening
    • Fastify server starts on the configured port
  5. HMR enabled
    • Automatically regenerates types and reloads modules when files change
Method 1: Change the port
// api/src/sonamu.config.ts
export default {
  server: {
    listen: {
      port: 2028,  // Change to desired port
    }
  }
} satisfies SonamuConfig;
Method 2: Kill existing process (macOS/Linux)
lsof -ti:1028 | xargs kill -9

​
File Generation

Type files: {entity}.types.ts, sonamu.generated.ts
Migrations: migrations/{timestamp}_{entity}_create.ts
Model classes: {entity}.model.ts (Scaffolding)
Test files: {entity}.model.test.ts
View files: React components (list, detail, edit)
Client code: Axios client, TanStack Query hooks
1. Auto-generated (on Entity creation/modification)
  • {entity}.entity.json
    • Entity table structure, fields, relations, indexes, Subset definitions
    • Created: When Entity is created in Sonamu UI
  • {entity}.types.ts
    • Custom type definitions for the Entity
    • Created: When Entity is created (initial template only, modified by developer afterwards)
  • sonamu.generated.ts
    • Auto-generates all Entity BaseSchema, Enum, Subset types
    • Created: Auto-regenerated whenever Entity or type files change
  • sonamu.generated.sso.ts
    • Subset-specific query builders and server-only types
    • Created: Auto-regenerated whenever Entity changes
2. Manually generated (click Generate in Sonamu UI)
  • migrations/{timestamp}_{action}.ts
    • Migration files for database schema changes
    • Created: When clicking Generate in DB Migration tab
  • {entity}.model.ts
    • Entity business logic and API definitions with @api decorator
    • Created: When generating Model template in Scaffolding tab (once only)
  • {entity}.model.test.ts
    • Unit test files for Model methods
    • Created: When generating Test template in Scaffolding tab
  • *.view.tsx
    • React-based back-office UI components
    • Created: When generating View template in Scaffolding tab
3. Auto-generated (during API server runtime)
  • {entity}.service.ts
    • Frontend client code that calls backend APIs
    • Created: When Model file changes are detected
  • sonamu.generated.http
    • API test templates for VSCode REST Client
    • Created: When methods with @api decorator are added/changed
  • Frontend file copy
    • types.ts, generated.ts, etc. auto-copied to web/src/services/
    • Created: Auto-copied to paths defined in sync.targets when backend files change
  • sonamu.lock
    • Checksum file for tracking file changes
    • Created: Auto-updated for file change tracking
Always overwritten (overwrite: true)The following files are always overwritten on regeneration, so do not modify:
  • sonamu.generated.ts - Always regenerated on Entity changes
  • sonamu.generated.sso.ts - Always regenerated on Entity changes
  • {entity}.service.ts - Always regenerated on Model changes
  • sonamu.generated.http - Always regenerated on @api method changes
Protected on regeneration (overwrite: false, default)The following files are not overwritten on regeneration, so feel free to modify:
  • {entity}.types.ts - Can add custom types
  • {entity}.model.ts - Can add/modify business logic
  • {entity}.model.test.ts - Can add/modify test cases
  • *.view.tsx - Can customize UI
Best Practices:
  • Add custom types in {entity}.types.ts
  • Implement business logic in {entity}.model.ts
  • Use Sonamu UI for Entity definitions
Files that must be committed:
  • sonamu.lock - Entity schema change tracking, team synchronization
  • sonamu.generated.ts - Type synchronization, immediately usable by frontend
  • {entity}.types.ts - Custom type definitions
  • migrations/*.ts - DB schema change history
  • {entity}.model.ts - Business logic
Reasons:
  • Type synchronization allows frontend developers to use immediately
  • Reduces build time
  • Easier code review

​
Scaffolding

Scaffolding is a feature that auto-generates repetitive boilerplate code based on templates.What can be generated:
  • Model classes ({entity}.model.ts)
  • Test files ({entity}.model.test.ts)
  • View components (*.view.tsx)
How to run:
  1. Access Sonamu UI
  2. Go to Scaffolding tab
  3. Select Entity
  4. Select Template (model/model_test/view_list/view_form)
  5. Click Generate
Why you need it:
  • Saves development time by auto-generating repetitive CRUD code
  • Maintains consistent code structure
  • Prevents typos and omissions
  • Beginners can learn standard patterns
overwrite option:
  • overwrite: false (default): Does not generate if file already exists (model, test, view templates)
  • overwrite: true: Always overwrites even if file exists (generated, service templates)