Project Settings

This covers basic project settings in sonamu.config.ts. You can configure project name, API paths, timezone, internationalization support, and more.

Basic Structure

import { defineConfig } from "sonamu";

export default defineConfig({
  projectName: "MyProject",

  api: {
    dir: "api",
    route: {
      prefix: "/api",
    },
    timezone: "Asia/Seoul",
  },

  i18n: {
    defaultLocale: "ko",
    supportedLocales: ["ko", "en"],
  },

  // ... other settings
});

projectName

Defines the name of the project. Displayed in logs, error messages, Sonamu UI, etc. Type: string (optional) Default: SonamuProject if not set

Usage Example

export default defineConfig({
  projectName: "Ecommerce",
  // ...
});

Setting via environment variable:

export default defineConfig({
  projectName: process.env.PROJECT_NAME ?? "MyProject",
  // ...
});

Use environment variables to have different project names per environment (e.g., MyProject-Dev, MyProject-Prod).

api Settings

Defines basic API-related settings.

api.dir

The directory name where API code is located. Type: string Default: "api"

export default defineConfig({
  api: {
    dir: "api", // Directory containing src/application folder
    // ...
  },
});

Most projects use "api" as is. Keep the default unless there’s a specific reason to change it.

api.route.prefix

Sets the common prefix for all API endpoints. Type: string Default: "/api"

export default defineConfig({
  api: {
    dir: "api",
    route: {
      prefix: "/api", // All APIs start with /api/* path
    },
  },
});

Example: With prefix: "/api":

UserModel.list → GET /api/user/list
PostModel.detail → GET /api/post/detail
OrderModel.create → POST /api/order/create

Changing the prefix will also update the generated Service code on the frontend. Therefore, it’s recommended to only change this early in the project.

Other prefix examples:

export default defineConfig({
  api: {
    route: {
      prefix: "/v1", // GET /v1/user/list
    },
  },
});

export default defineConfig({
  api: {
    route: {
      prefix: "/graphql", // Different routing strategy
    },
  },
});

api.timezone

Sets the server’s default timezone. Affects date/time processing. Type: string (optional) Default: System default

export default defineConfig({
  api: {
    dir: "api",
    route: { prefix: "/api" },
    timezone: "Asia/Seoul", // Korea time
  },
});

Supported timezone format: IANA Time Zone Database Common timezone examples:

"Asia/Seoul" - Korea
"America/New_York" - US Eastern
"Europe/London" - UK
"Asia/Tokyo" - Japan
"UTC" - Coordinated Universal Time

For global services, it’s recommended to use "UTC" and convert to user timezone on the client.

i18n Settings

Internationalization (i18n) settings for multilingual support. Type: SonamuI18nOptions (optional)

export type SonamuI18nOptions = {
  /** Default locale (key definition basis + runtime default) */
  defaultLocale: string;
  /** List of supported locales */
  supportedLocales: string[];
};

Basic Configuration

export default defineConfig({
  i18n: {
    defaultLocale: "ko",
    supportedLocales: ["ko", "en"],
  },
  // ...
});

defaultLocale

Sets the default language. Serves two roles:

Key definition basis: The language used as the standard when writing Entity’s label, enumLabel, etc.
Runtime default: The language to use when the user doesn’t specify a locale

export default defineConfig({
  i18n: {
    defaultLocale: "ko", // Korean as default
    supportedLocales: ["ko", "en", "ja"],
  },
});

supportedLocales

List of all languages to support. Must include defaultLocale.

export default defineConfig({
  i18n: {
    defaultLocale: "ko",
    supportedLocales: ["ko", "en", "ja", "zh"], // Support 4 languages
  },
});

An error will occur if defaultLocale is not included in supportedLocales.

Disabling i18n

If you don’t need multilingual support, simply omit the i18n setting:

export default defineConfig({
  projectName: "MyProject",
  api: {
    /* ... */
  },
  // i18n: undefined  ← Omit
  // ...
});

Practical Examples

Basic Project Configuration

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 and other settings
});

Using Environment Variables

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"],
  },

  // ...
});

Global Service

import { defineConfig } from "sonamu";

export default defineConfig({
  projectName: "GlobalService",

  api: {
    dir: "api",
    route: {
      prefix: "/api/v1", // Including versioning
    },
    timezone: "UTC", // UTC recommended for global services
  },

  i18n: {
    defaultLocale: "en",
    supportedLocales: ["en", "ko", "ja", "zh", "es", "fr"],
  },

  // ...
});

Next Steps

After completing basic project settings, proceed with these configurations:

database - Database connection settings
server - Server options and plugin settings
sync-targets - Frontend synchronization target settings

Get Started

Core Concepts

Database

API Development

Frontend Integration

Testing

Advanced Features

Tools & CLI

Configuration

API Reference

Troubleshooting

FAQ

Basic Structure

projectName

Usage Example

api Settings

api.dir

api.route.prefix

api.timezone

i18n Settings

Basic Configuration

defaultLocale

supportedLocales

Disabling i18n

Practical Examples

Basic Project Configuration

Using Environment Variables

Global Service

Next Steps

​Basic Structure

​projectName

​Usage Example

​api Settings

​api.dir

​api.route.prefix

​api.timezone

​i18n Settings

​Basic Configuration

​defaultLocale

​supportedLocales

​Disabling i18n

​Practical Examples

​Basic Project Configuration

​Using Environment Variables

​Global Service

​Next Steps

Basic Structure

projectName

Usage Example

api Settings

api.dir

api.route.prefix

api.timezone

i18n Settings

Basic Configuration

defaultLocale

supportedLocales

Disabling i18n

Practical Examples

Basic Project Configuration

Using Environment Variables

Global Service

Next Steps