๋ฉ”์ธ ์ฝ˜ํ…์ธ ๋กœ ๊ฑด๋„ˆ๋›ฐ๊ธฐ
Sonamu๋Š” create-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 ์‹คํ–‰๋ถ€ํ„ฐ ๋ชจ๋“  ํ”„๋กฌํ”„ํŠธ ์ž…๋ ฅ ์™„๋ฃŒ๊นŒ์ง€ ์ „์ฒด ๊ณผ์ •

๋Œ€ํ™”ํ˜• ํ”„๋กฌํ”„ํŠธ๊ฐ€ ๋‚˜ํƒ€๋‚˜๋ฉด ํ”„๋กœ์ ํŠธ ์ •๋ณด๋ฅผ ์ž…๋ ฅํ•ฉ๋‹ˆ๋‹ค:
? 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: ****
1

ํ”„๋กœ์ ํŠธ๋ช… ์ž…๋ ฅ

์ƒ์„ฑํ•  ํ”„๋กœ์ ํŠธ์˜ ์ด๋ฆ„์„ ์ž…๋ ฅํ•ฉ๋‹ˆ๋‹ค. ์ด ์ด๋ฆ„์œผ๋กœ ๋””๋ ‰ํ† ๋ฆฌ๊ฐ€ ์ƒ์„ฑ๋ฉ๋‹ˆ๋‹ค.
ํ”„๋กœ์ ํŠธ๋ช…์—๋Š” ๊ณต๋ฐฑ๊ณผ **ํ•˜์ดํ”ˆ(-)**์„ ์‚ฌ์šฉํ•  ์ˆ˜ ์—†์Šต๋‹ˆ๋‹ค. ์–ธ๋”์Šค์ฝ”์–ด(_)๋ฅผ ์‚ฌ์šฉํ•˜์„ธ์š”.
2

pnpm ์„ค์ •

pnpm์„ ์ž๋™์œผ๋กœ ์„ค์ •ํ• ์ง€ ์„ ํƒํ•ฉ๋‹ˆ๋‹ค. ๊ถŒ์žฅ ์˜ต์…˜์ž…๋‹ˆ๋‹ค.
3

๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ์„ค์ •

Docker๋ฅผ ์‚ฌ์šฉํ•œ PostgreSQL ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค๋ฅผ ์„ค์ •ํ• ์ง€ ์„ ํƒํ•ฉ๋‹ˆ๋‹ค. Yes๋ฅผ ์„ ํƒํ•˜๋ฉด:
  • Docker Compose ํ”„๋กœ์ ํŠธ๋ช…
  • ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ์‚ฌ์šฉ์ž๋ช…
  • ์ปจํ…Œ์ด๋„ˆ ์ด๋ฆ„
  • ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ์ด๋ฆ„
  • ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ๋น„๋ฐ€๋ฒˆํ˜ธ
๋ฅผ ์ž…๋ ฅ๋ฐ›๊ณ , ์ด ์ •๋ณด๋กœ api/.env ํŒŒ์ผ์ด ์ž๋™ ์ƒ์„ฑ๋ฉ๋‹ˆ๋‹ค.
ํ”„๋กœ์ ํŠธ ์ƒ์„ฑ ์™„๋ฃŒ

ํ”„๋กœ์ ํŠธ ์ƒ์„ฑ ์™„๋ฃŒ ๋ฉ”์‹œ์ง€ ๋ฐ ์ƒ์„ฑ๋œ ๋””๋ ‰ํ† ๋ฆฌ ๊ตฌ์กฐ

์ƒ์„ฑ๋œ ํ”„๋กœ์ ํŠธ ๊ตฌ์กฐ

create-sonamu๋Š” ๋‹ค์Œ๊ณผ ๊ฐ™์€ ๋ชจ๋…ธ๋ ˆํฌ ๊ตฌ์กฐ๋ฅผ ์ƒ์„ฑํ•ฉ๋‹ˆ๋‹ค:
VS Code Explorer ์‚ฌ์ด๋“œ๋ฐ”

VS Code์—์„œ ์—ด๋ฆฐ ํ”„๋กœ์ ํŠธ์˜ ๋””๋ ‰ํ† ๋ฆฌ ํŠธ๋ฆฌ ๊ตฌ์กฐ

my_app
README.md

์ฃผ์š” ์„ค์ • ํŒŒ์ผ

API ์„œ๋ฒ„ ์—”ํŠธ๋ฆฌํฌ์ธํŠธ

์ƒ์„ฑ๋œ API ์„œ๋ฒ„์˜ ์ง„์ž…์ ์€ ๋‹ค์Œ๊ณผ ๊ฐ™์Šต๋‹ˆ๋‹ค:
api/src/index.ts ํŒŒ์ผ

VS Code์—์„œ ์—ด๋ฆฐ api/src/index.ts ํŒŒ์ผ

Sonamu ์„ค์ •

sonamu.config.ts์—์„œ ํ”„๋กœ์ ํŠธ์˜ ์ฃผ์š” ์„ค์ •์„ ๊ด€๋ฆฌํ•ฉ๋‹ˆ๋‹ค:
api/src/sonamu.config.ts
import path from "node:path";
import { defineConfig } from "sonamu";
import { drivers } from "sonamu/storage";

const host = "localhost";
const port = 1028;

export default defineConfig({
  projectName: process.env.PROJECT_NAME ?? "SonamuProject",
  api: {
    dir: "api",
    timezone: "Asia/Seoul",
    route: {
      prefix: "/api",
    },
  },
  sync: {
    targets: ["web"],
  },
  database: {
    database: "pg",
    name: process.env.DATABASE_NAME ?? "database_name",
    defaultOptions: {
      connection: {
        host: process.env.DB_HOST || "0.0.0.0",
        port: Number(process.env.DB_PORT) || 5432,
        user: process.env.DB_USER || "postgres",
        password: process.env.DB_PASSWORD,
      },
    },
  },
  server: {
    listen: { port, host },
    // ... ์ถ”๊ฐ€ ์„œ๋ฒ„ ์„ค์ •
  },
});

Docker Compose ์„ค์ •

PostgreSQL ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค๋Š” Docker๋กœ ๊ด€๋ฆฌ๋ฉ๋‹ˆ๋‹ค:
api/database/docker-compose.yml
version: "3.8"
name: ${CONTAINER_NAME}
services:
  pg:
    platform: linux/arm64
    image: pgvector/pgvector:pg18
    container_name: ${CONTAINER_NAME}
    volumes:
      - ./fixtures/init.sql:/docker-entrypoint-initdb.d/init.sql
    environment:
      POSTGRES_DB: template1
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      TZ: Asia/Seoul
    ports:
      - "${DB_PORT}:5432"

ํ”„๋ก ํŠธ์—”๋“œ ์„ค์ •

Vite ๊ธฐ๋ฐ˜ React ์• ํ”Œ๋ฆฌ์ผ€์ด์…˜์ด ์ƒ์„ฑ๋ฉ๋‹ˆ๋‹ค:
web/vite.config.ts
import react from "@vitejs/plugin-react-swc";
import dotenv from "dotenv";
import path from "path";
import { defineConfig } from "vite";

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

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
    },
  },
  server: {
    host: "0.0.0.0",
    port: 3028,
    proxy: {
      "/api": `http://${process.env.API_HOST}:${process.env.API_PORT}`,
    },
  },
});

ํฌํŠธ ๊ตฌ์„ฑ

๊ธฐ๋ณธ ํฌํŠธ๋Š” ๋‹ค์Œ๊ณผ ๊ฐ™์ด ์„ค์ •๋ฉ๋‹ˆ๋‹ค:
์„œ๋น„์ŠคํฌํŠธ์„ค๋ช…
API ์„œ๋ฒ„1028Fastify ๊ธฐ๋ฐ˜ REST API
Sonamu UI2028์—”ํ‹ฐํ‹ฐ ๊ด€๋ฆฌ ์ธํ„ฐํŽ˜์ด์Šค
Web ์•ฑ3028Vite ๊ฐœ๋ฐœ ์„œ๋ฒ„
PostgreSQL5432๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค
  • API ์„œ๋ฒ„ ํฌํŠธ: api/src/sonamu.config.ts์—์„œ port ์ƒ์ˆ˜ ์ˆ˜์ • (์ด ๊ฒฝ์šฐ web/.sonamu.env์˜ API_PORT๋„ ํ•จ๊ป˜ ์ˆ˜์ • ํ•„์š”)
  • Web ์•ฑ ํฌํŠธ: web/vite.config.ts์—์„œ server.port ์ˆ˜์ •
  • ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ํฌํŠธ: api/src/sonamu.config.ts์˜ database.defaultOptions.connection.port์—์„œ ํ™˜๊ฒฝ๋ณ€์ˆ˜ ์„ค์ • (์˜ˆ: MIOMOCK_DB_PORT)

๋‹ค์Œ ๋‹จ๊ณ„

์„ค์น˜๊ฐ€ ์™„๋ฃŒ๋˜์—ˆ๋‹ค๋ฉด, ๋น ๋ฅธ ์‹œ์ž‘ ๊ฐ€์ด๋“œ๋ฅผ ํ†ตํ•ด ์ฒซ ๋ฒˆ์งธ ์—”ํ‹ฐํ‹ฐ๋ฅผ ์ƒ์„ฑํ•˜๊ณ  API๋ฅผ ๋งŒ๋“ค์–ด๋ณด์„ธ์š”.