Installation

Use the create-sonamu package to create a new Sonamu project.

System Requirements

The following environment is required to use Sonamu:

Node.js v22 or higher
pnpm v10.23 or higher
Docker (for running the database)

If pnpm is not installed, you can enable it with the corepack enable command.

Checking Node.js, pnpm, Docker versions — Running node --version, pnpm --version, docker --version in terminal

Creating a Project

Run the following command in your terminal to create a new Sonamu project:

pnpm create sonamu

Inline Options

You can pass the project name as an argument or use options to skip interactive prompts:

# Specify project name directly
pnpm create sonamu myapp

# Use all default options (non-interactive)
pnpm create sonamu myapp --yes

# Explicitly specify pnpm/docker setup
pnpm create sonamu myapp --pnpm y --docker y

# Auto-proceed with pnpm only (docker prompts will appear)
pnpm create sonamu myapp --pnpm y

# Auto-proceed with docker only (pnpm prompts will appear, DB options use defaults)
pnpm create sonamu myapp --docker y

# Fully non-interactive mode (all options specified)
pnpm create sonamu myapp \
  --pnpm y \
  --docker y \
  --db-user=postgres \
  --db-password=1234 \
  --db-name=myapp \
  --container-name=myapp-pg \
  --docker-project=myapp-docker

# Specify DB options only (pnpm/docker setup will prompt)
pnpm create sonamu myapp --db-name myapp --db-password secret123

Option	Description	Default
`--yes`, `-y`	Use all default options	-
`--pnpm`	pnpm installation (`y`/`n`)	(prompts)
`--docker`	Docker DB setup (`y`/`n`)	(prompts)
`--skip-pnpm`	Skip pnpm setup (same as `--pnpm n`)	false
`--skip-docker`	Skip Docker DB setup (same as `--docker n`)	false
`--docker-project`, `--docker-pj-name`	Docker Compose project name	-docker
`--db-user`	Database username	postgres
`--db-name`	Database name
`--db-password`	Database password	1234
`--container-name`	Docker container name	-container

In --pnpm y and --docker y, you can also use yes, true, or 1 instead of y. Similarly, n can be replaced with no, false, or 0.

Running pnpm create sonamu with inline options default values

When the interactive prompt appears, enter your project information:

? Project name: myapp
? Would you like to set up pnpm? Yes
? Would you like to set up a database using Docker? Yes
? Enter the Docker project name: myapp-docker
? Enter the database user: postgres
? Enter the container name: myapp-container
? Enter the database name: myapp
? Enter the database password: ****

Enter Project Name

Enter the name of the project to create. A directory will be created with this name.

Spaces and hyphens (-) cannot be used in the project name. Use underscores (_) instead.

pnpm Setup

Choose whether to automatically set up pnpm. This is the recommended option.

Database Setup

Choose whether to set up a PostgreSQL database using Docker. If you select Yes:

Docker Compose project name
Database username
Container name
Database name
Database password

will be requested, and the packages/api/.env file will be automatically generated with this information.

Project creation complete — Project creation completion message and generated directory structure

Generated Project Structure

create-sonamu creates the following monorepo structure:

VS Code Explorer sidebar — Directory tree structure of the project opened in VS Code

myapp

packages

api (Backend API server)

web (Frontend web app)

pnpm-workspace.yaml (Workspace configuration)

README.md

Key Configuration Files

pnpm Workspace

The root pnpm-workspace.yaml manages monorepo packages and common dependency versions:

pnpm-workspace.yaml

packages:
  - packages/api
  - packages/web

catalog:
  "@tanstack/react-query": ^5.90.12
  "@tanstack/react-router": 1.143.11
  react: ^19.2.3
  vite: 7.3.0
  vitest: 4.0.16
  # ... other common dependencies

API Server Entry Point

The entry point of the generated API server is as follows:

packages/api/src/index.ts file opened in VS Code

Sonamu Configuration

Manage your project’s main settings in sonamu.config.ts:

packages/api/src/sonamu.config.ts

import path from "node:path";
import { CachePresets, defineConfig } from "sonamu";
import { drivers as cacheDrivers, store } from "sonamu/cache";
import { drivers } from "sonamu/storage";

const host = "localhost";
const port = 34900;

export default defineConfig({
  projectName: process.env.PROJECT_NAME ?? "SonamuProject",
  api: {
    dir: "api",
    timezone: "Asia/Seoul",
    route: {
      prefix: "/api",
    },
  },
  i18n: {
    defaultLocale: "ko",
    supportedLocales: ["ko", "en"],
  },
  sync: {
    targets: ["web"],
  },
  database: {
    database: "pg",
    defaultOptions: {
      pool: {
        min: 1,
        max: 10,
      },
    },
  },
  server: {
    listen: { port, host },
    // ... server, storage, cache settings
    cache: {
      default: "main",
      stores: {
        main: store().useL1Layer(cacheDrivers.memory({ maxSize: "50mb" })),
      },
      ttl: "5m",
    },
  },
});

Docker Compose Configuration

PostgreSQL database is managed with Docker:

packages/api/database/docker-compose.yml

version: "3.8"
name: ${CONTAINER_NAME}
services:
  pg:
    platform: linux/arm64
    image: pgvector/pgvector:pg18
    container_name: ${CONTAINER_NAME}
    env_file:
      - ../.env
    volumes:
      - ./fixtures/init.sh:/docker-entrypoint-initdb.d/init.sh
    environment:
      PROJECT_NAME: ${PROJECT_NAME}
      SONAMU_DB_NAME: ${SONAMU_DB_NAME:-}
      SONAMU_DB_FIXTURE_NAME: ${SONAMU_DB_FIXTURE_NAME:-}
      POSTGRES_DB: template1
      POSTGRES_USER: ${SONAMU_DB_USER}
      POSTGRES_PASSWORD: ${SONAMU_DB_PASSWORD}
      TZ: Asia/Seoul
    ports:
      - "${SONAMU_DB_PORT}:5432"

Frontend Configuration

A Vite + React + TanStack Router + SSR based application is generated:

packages/web/vite.config.ts

import tailwindcss from "@tailwindcss/vite";
import { tanstackRouter } from "@tanstack/router-plugin/vite";
import react from "@vitejs/plugin-react";
import dotenv from "dotenv";
import path from "path";
import Icons from "unplugin-icons/vite";
import { defineConfig } from "vite";

dotenv.config({ path: ".sonamu.env" });

export default defineConfig(({ command, isSsrBuild }) => ({
  plugins: [
    react(),
    Icons({ compiler: "jsx", jsx: "react", autoInstall: true }),
    tailwindcss(),
    tanstackRouter(),
  ],
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
    },
  },
  server: {
    host: "0.0.0.0",
    proxy: {
      "/api": `http://${process.env.API_HOST}:${process.env.API_PORT}`,
    },
  },
  // SSR configuration included
}));

Port Configuration

Default ports are configured as follows:

Service	Port	Description
API Server	34900	Fastify-based REST API
Sonamu UI	-	http://localhost:34900/sonamu-ui
Web App	5173	Vite development server (Vite default, SSR support)
PostgreSQL	5432	Database

Sonamu UI: Access via the API server’s /sonamu-ui path, not a separate port. - API server port: Modify the port constant in packages/api/src/sonamu.config.ts (in this case, also modify API_PORT in packages/web/.sonamu.env) - Web app port: Modify server.port in packages/web/vite.config.ts

Next Steps

Once installation is complete, follow the Quick Start guide to create your first entity and build an API.

Get Started

Core Concepts

Database

API Development

Frontend Integration

Testing

Advanced Features

Tools & CLI

Configuration

API Reference

Troubleshooting

FAQ

System Requirements

Creating a Project

Inline Options

Generated Project Structure

Key Configuration Files

pnpm Workspace

API Server Entry Point

Sonamu Configuration

Docker Compose Configuration

Frontend Configuration

Port Configuration

Next Steps

​System Requirements

​Creating a Project

​Inline Options

​Generated Project Structure

​Key Configuration Files

​pnpm Workspace

​API Server Entry Point

​Sonamu Configuration

​Docker Compose Configuration

​Frontend Configuration

​Port Configuration

​Next Steps

System Requirements

Creating a Project

Inline Options

Generated Project Structure

Key Configuration Files

pnpm Workspace

API Server Entry Point

Sonamu Configuration

Docker Compose Configuration

Frontend Configuration

Port Configuration

Next Steps