sonamu.config.ts의 기본 프로젝트 설정을 다룹니다. 프로젝트 이름, API 경로, 시간대, 다국어 지원 등을 설정할 수 있습니다.
기본 구조
import { defineConfig } from "sonamu";
export default defineConfig({
projectName: "MyProject",
api: {
dir: "api",
route: {
prefix: "/api",
},
timezone: "Asia/Seoul",
},
i18n: {
defaultLocale: "ko",
supportedLocales: ["ko", "en"],
},
// ... 다른 설정
});
projectName
프로젝트의 이름을 정의합니다. 로그, 오류 메시지, Sonamu UI 등에서 표시됩니다.
타입: string (선택적)
기본값: 설정하지 않으면 SonamuProject
사용 예시
export default defineConfig({
projectName: "Ecommerce",
// ...
});
export default defineConfig({
projectName: process.env.PROJECT_NAME ?? "MyProject",
// ...
});
환경별로 다른 프로젝트 이름을 사용하려면 환경 변수를 활용하세요. (e.g., MyProject-Dev, MyProject-Prod)
api 설정
API 관련 기본 설정을 정의합니다.
api.dir
API 코드가 위치한 디렉토리 이름입니다.
타입: string
기본값: "api"
export default defineConfig({
api: {
dir: "api", // src/application 폴더가 있는 디렉토리
// ...
},
});
대부분의 프로젝트에서 "api" 그대로 사용합니다. 특별한 이유가 없다면 기본값을 유지하세요.
api.route.prefix
모든 API 엔드포인트의 공통 접두사를 설정합니다.
타입: string
기본값: "/api"
export default defineConfig({
api: {
dir: "api",
route: {
prefix: "/api", // 모든 API가 /api/* 경로로 시작
},
},
});
prefix: "/api"로 설정하면:
UserModel.list → GET /api/user/listPostModel.detail → GET /api/post/detailOrderModel.create → POST /api/order/create
prefix를 변경하면 프론트엔드에서 생성된 Service 코드도 함께 업데이트됩니다. 따라서 프로젝트 초기에만 변경하는 것을 권장합니다.
export default defineConfig({
api: {
route: {
prefix: "/v1", // GET /v1/user/list
},
},
});
export default defineConfig({
api: {
route: {
prefix: "/graphql", // 다른 라우팅 전략
},
},
});
api.timezone
서버의 기본 시간대를 설정합니다. 날짜/시간 관련 처리에 영향을 줍니다.
타입: string (선택적)
기본값: 시스템 기본값
export default defineConfig({
api: {
dir: "api",
route: { prefix: "/api" },
timezone: "Asia/Seoul", // 한국 시간
},
});
"Asia/Seoul" - 한국"America/New_York" - 미국 동부"Europe/London" - 영국"Asia/Tokyo" - 일본"UTC" - 협정 세계시
글로벌 서비스라면 "UTC"를 사용하고, 클라이언트에서 사용자 시간대로 변환하는 것을 권장합니다.
i18n 설정
다국어 지원을 위한 국제화(i18n) 설정입니다.
타입: SonamuI18nOptions (선택적)
export type SonamuI18nOptions = {
/** 기본 locale (키 정의 기준 + 런타임 기본값) */
defaultLocale: string;
/** 지원하는 locale 목록 */
supportedLocales: string[];
};
기본 설정
export default defineConfig({
i18n: {
defaultLocale: "ko",
supportedLocales: ["ko", "en"],
},
// ...
});
defaultLocale
기본 언어를 설정합니다. 다음 두 가지 역할을 합니다:
- 키 정의 기준: Entity의
label, enumLabel 등을 작성할 때 기준이 되는 언어
- 런타임 기본값: 사용자가 locale을 지정하지 않았을 때 사용할 언어
export default defineConfig({
i18n: {
defaultLocale: "ko", // 한국어를 기본으로
supportedLocales: ["ko", "en", "ja"],
},
});
supportedLocales
지원할 모든 언어의 목록입니다. defaultLocale도 반드시 포함되어야 합니다.
export default defineConfig({
i18n: {
defaultLocale: "ko",
supportedLocales: ["ko", "en", "ja", "zh"], // 4개국 언어 지원
},
});
defaultLocale이 supportedLocales에 포함되어 있지 않으면 오류가 발생합니다.
i18n 비활성화
다국어 지원이 필요 없다면 i18n 설정을 생략하면 됩니다:
export default defineConfig({
projectName: "MyProject",
api: { /* ... */ },
// i18n: undefined ← 생략
// ...
});
실전 예시
기본 프로젝트 설정
import { defineConfig } from "sonamu";
export default defineConfig({
projectName: "MyEcommerce",
api: {
dir: "api",
route: {
prefix: "/api",
},
timezone: "Asia/Seoul",
},
i18n: {
defaultLocale: "ko",
supportedLocales: ["ko", "en"],
},
// ... database, server 등 다른 설정
});
환경 변수 활용
import { defineConfig } from "sonamu";
const isDev = process.env.NODE_ENV === "development";
export default defineConfig({
projectName: process.env.PROJECT_NAME ?? "MyProject",
api: {
dir: "api",
route: {
prefix: process.env.API_PREFIX ?? "/api",
},
timezone: process.env.TIMEZONE ?? "Asia/Seoul",
},
i18n: {
defaultLocale: "ko",
supportedLocales: ["ko", "en", "ja"],
},
// ...
});
글로벌 서비스
import { defineConfig } from "sonamu";
export default defineConfig({
projectName: "GlobalService",
api: {
dir: "api",
route: {
prefix: "/api/v1", // 버저닝 포함
},
timezone: "UTC", // 글로벌 서비스는 UTC 권장
},
i18n: {
defaultLocale: "en",
supportedLocales: ["en", "ko", "ja", "zh", "es", "fr"],
},
// ...
});
다음 단계
프로젝트 기본 설정을 완료했다면, 다음 설정들을 진행하세요: