설치하기

create-sonamu 패키지로 새 Sonamu 프로젝트를 생성할 수 있습니다.

시스템 요구사항

Sonamu를 사용하기 위해서는 다음 환경이 필요합니다:

Node.js v22 이상
pnpm v10.23 이상
Docker (데이터베이스 실행용)

pnpm이 설치되지 않았다면 corepack enable 명령어로 활성화할 수 있습니다.

Node.js, pnpm, Docker 버전 확인 — 터미널에서 node --version, pnpm --version, docker --version 실행 결과

프로젝트 생성

터미널에서 다음 명령어를 실행하여 새 Sonamu 프로젝트를 생성합니다:

pnpm create sonamu

인라인 옵션

프로젝트명을 인자로 전달하거나, 옵션을 통해 대화형 프롬프트를 건너뛸 수 있습니다:

# 프로젝트명 직접 지정
pnpm create sonamu myapp

# 모든 옵션을 기본값으로 설정 (비대화형)
pnpm create sonamu myapp --yes

# pnpm/docker 설정 여부를 명시적으로 지정
pnpm create sonamu myapp --pnpm y --docker y

# pnpm만 자동 진행 (docker는 프롬프트로 물어봄)
pnpm create sonamu myapp --pnpm y

# docker만 자동 진행 (pnpm은 프롬프트로 물어봄, DB 옵션은 기본값)
pnpm create sonamu myapp --docker y

# 완전한 비대화형 모드 (모든 옵션 지정)
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

# DB 옵션만 지정 (pnpm/docker 설정은 프롬프트로 물어봄)
pnpm create sonamu myapp --db-name myapp --db-password secret123

옵션	설명	기본값
`--yes`, `-y`	모든 옵션을 기본값으로 설정	-
`--pnpm`	pnpm 설치 여부 (`y`/`n`)	(프롬프트로 질문)
`--docker`	Docker DB 설정 여부 (`y`/`n`)	(프롬프트로 질문)
`--skip-pnpm`	pnpm 설정 건너뛰기 (`--pnpm n`과 동일)	false
`--skip-docker`	Docker DB 설정 건너뛰기 (`--docker n`과 동일)	false
`--docker-project`, `--docker-pj-name`	Docker Compose 프로젝트명	-docker
`--db-user`	데이터베이스 사용자명	postgres
`--db-name`	데이터베이스 이름
`--db-password`	데이터베이스 비밀번호	1234
`--container-name`	Docker 컨테이너 이름	-container

--pnpm y, --docker y에서 y는 yes, true, 1로도 지정할 수 있습니다. 마찬가지로 n은 no, false, 0으로도 지정할 수 있습니다.

인라인 옵션 기본값으로 pnpm create sonamu 실행

대화형 프롬프트가 나타나면 프로젝트 정보를 입력합니다:

? 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: ****

프로젝트명 입력

생성할 프로젝트의 이름을 입력합니다. 이 이름으로 디렉토리가 생성됩니다.

프로젝트명에는 공백과 **하이픈(-)**을 사용할 수 없습니다. 언더스코어(_)를 사용하세요.

pnpm 설정

pnpm을 자동으로 설정할지 선택합니다. 권장 옵션입니다.

데이터베이스 설정

Docker를 사용한 PostgreSQL 데이터베이스를 설정할지 선택합니다. Yes를 선택하면:

Docker Compose 프로젝트명
데이터베이스 사용자명
컨테이너 이름
데이터베이스 이름
데이터베이스 비밀번호

를 입력받고, 이 정보로 packages/api/.env 파일이 자동 생성됩니다.

생성된 프로젝트 구조

create-sonamu는 다음과 같은 모노레포 구조를 생성합니다:

VS Code Explorer 사이드바 — VS Code에서 열린 프로젝트의 디렉토리 트리 구조

myapp

packages

api (백엔드 API 서버)

web (프론트엔드 웹 앱)

pnpm-workspace.yaml (워크스페이스 설정)

README.md

주요 설정 파일

pnpm 워크스페이스

루트의 pnpm-workspace.yaml에서 모노레포 패키지와 공통 의존성 버전을 관리합니다:

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
  # ... 기타 공통 의존성

API 서버 엔트리포인트

생성된 API 서버의 진입점은 다음과 같습니다:

VS Code에서 열린 packages/api/src/index.ts 파일

Sonamu 설정

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 },
    // ... 서버, 스토리지, 캐시 설정
    cache: {
      default: "main",
      stores: {
        main: store().useL1Layer(cacheDrivers.memory({ maxSize: "50mb" })),
      },
      ttl: "5m",
    },
  },
});

Docker Compose 설정

PostgreSQL 데이터베이스는 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"

프론트엔드 설정

Vite + React + TanStack Router + SSR 기반 애플리케이션이 생성됩니다:

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 설정 포함
}));

포트 구성

기본 포트는 다음과 같이 설정됩니다:

서비스	포트	설명
API 서버	34900	Fastify 기반 REST API
Sonamu UI	-	http://localhost:34900/sonamu-ui
Web 앱	5173	Vite 개발 서버 (Vite 기본값, SSR 지원)
PostgreSQL	5432	데이터베이스

Sonamu UI: 별도 포트가 아닌 API 서버의 /sonamu-ui 경로로 접근합니다. - API 서버 포트: packages/api/src/sonamu.config.ts에서 port 상수 수정 (이 경우 packages/web/.sonamu.env의 API_PORT도 함께 수정 필요) - Web 앱 포트: packages/web/vite.config.ts에서 server.port 수정

다음 단계

설치가 완료되었다면, 빠른 시작 가이드를 통해 첫 번째 엔티티를 생성하고 API를 만들어보세요.

시작하기

핵심 개념

데이터베이스

API 개발

프론트엔드 통합

테스팅

고급 기능

도구 & CLI

설정

API 레퍼런스

문제 해결

자주 묻는 질문

시스템 요구사항

프로젝트 생성

인라인 옵션

생성된 프로젝트 구조

주요 설정 파일

pnpm 워크스페이스

API 서버 엔트리포인트

Sonamu 설정

Docker Compose 설정

프론트엔드 설정

포트 구성

다음 단계

​시스템 요구사항

​프로젝트 생성

​인라인 옵션

​생성된 프로젝트 구조

​주요 설정 파일

​pnpm 워크스페이스

​API 서버 엔트리포인트

​Sonamu 설정

​Docker Compose 설정

​프론트엔드 설정

​포트 구성

​다음 단계

시스템 요구사항

프로젝트 생성

인라인 옵션

생성된 프로젝트 구조

주요 설정 파일

pnpm 워크스페이스

API 서버 엔트리포인트

Sonamu 설정

Docker Compose 설정

프론트엔드 설정

포트 구성

다음 단계