Quick Start

​

Prerequisites

​

Running the Development Environment

• PostgreSQL - Database
• API Server - Backend REST API (includes Sonamu UI)
• Web Server - Frontend application

1

Start Database

Navigate to your project’s api directory and start the PostgreSQL container:

cd myapp/packages/api
pnpm docker:up

This command uses Docker Compose to run the PostgreSQL database in the background.

To verify the database is running correctly, you can check the container status with the docker ps command.

2

Run API Server

In the same api directory, start the development server:

pnpm dev

When the server starts successfully, you’ll see the following message:

🌲 Sonamu v1.x.x

✓ Config loaded (...)
✓ DB
  ▸ development @ localhost:5432/myapp_development
✓ Sonamu ready (...)

This single command runs everything:

• Web App: http://localhost:34900
• API Endpoints: http://localhost:34900/api
• Sonamu UI: http://localhost:34900/sonamu-ui

The API server supports Hot Module Replacement (HMR), so it automatically restarts when code changes.

In the local development environment, the API server integrates and serves the Web app. It connects the Web directory’s Vite Dev Server as middleware to the API server, allowing everything to run on a single port.

Keep this terminal window open. It maintains the running API server.

3

Run Web Server (Optional)

If you want to focus on Web development or utilize Vite’s full features, open a new terminal window and start the development server separately in the web directory:

cd myapp/packages/web
pnpm dev

When the Vite development server starts, you’ll see the following message:

  VITE v5.x.x  ready in xxx ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: http://192.168.x.x:5173/

If you run the Web server separately, you can access the frontend at http://localhost:5173. The Web server automatically proxies /api/* path requests to the API server (localhost:34900).

Two Development Modes

• Integrated mode (recommended): Run only API server → Access everything at localhost:34900
• Separated mode: Run API + Web separately → API at localhost:34900, Web at localhost:5173

The integrated mode is sufficient for most cases. Use separated mode only when focusing on Web development.

​

Verify Access

​

Integrated Mode (API server only)

​

Separated Mode (Both API + Web servers running)

​

Sonamu UI Features

• Create and edit entities
• Manage database migrations
• View API endpoints
• Visualize database schema

​

Stopping Servers

1. API Server (and Web server if running): Press Ctrl + C in each terminal to stop.
2. Database: Run the following command in the api directory:

pnpm docker:down

​

Next Steps