> ## Documentation Index > Fetch the complete documentation index at: https://sonamu.cartanova.ai/llms.txt > Use this file to discover all available pages before exploring further. # General Questions > General questions about using Sonamu ## Getting Started Create a new project with the following command: ```bash theme={null} pnpm create sonamu ``` Follow the interactive prompts to configure your project: ```bash theme={null} ? 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: ```bash theme={null} # 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:34900 Sonamu UI: http://localhost:34900/sonamu-ui Web: http://localhost:5173 ``` 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** ```typescript theme={null} // api/src/sonamu.config.ts export default { server: { listen: { port: 2028, // Change to desired port }, }, } satisfies SonamuConfig; ``` **Method 2: Kill existing process (macOS/Linux)** ```bash theme={null} lsof -ti:34900 | 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) *** ## Related Documentation * [Getting Started](/en/getting-started/quick-start) * [Defining Entities](/en/core-concepts/entities/defining-entities) * [Using Scaffolding](/en/tools-and-cli/scaffolding) * [Managing Migrations](/en/database/migrations/migration-basics)