.env Setup

Before importing sonamu.config.ts, Sonamu reads dotenv files from the API package root. Put shared defaults in .env, environment-specific values in .env.<environment>, and machine-local overrides in .env.local.

Never commit secret .env files. Commit only examples or templates that do not contain real credentials.

Loading Order

For the active NODE_ENV, Sonamu applies sources in this order:

.env
.env.${NODE_ENV}
.env.local
Exported process environment variables

Each source can override values loaded before it. If NODE_ENV is not set, Sonamu uses development. Allowed values are test, development, staging, and production.

File Layout

packages/api/.env
packages/api/.env.development
packages/api/.env.staging
packages/api/.env.production
packages/api/.env.test
packages/api/.env.local

The common .env file is optional when the current environment has its own file. One of .env or .env.${NODE_ENV} must exist.

Common Values

.env

# Shared defaults
PROJECT_NAME=MyProject
CONTAINER_NAME=myproject-postgres

# Database defaults. Environment files can override these values.
SONAMU_DB_HOST=127.0.0.1
SONAMU_DB_PORT=5432
SONAMU_DB_USER=postgres
SONAMU_DB_PASSWORD=your-db-password

# Secrets and external services
SESSION_SECRET=your-session-secret
SESSION_SALT=your-session-salt
OPENAI_API_KEY=your-openai-api-key

Environment Values

Development
Staging
Production
Test

.env.development

SONAMU_DB_HOST=127.0.0.1
SONAMU_DB_PORT=5432
SONAMU_DB_USER=postgres
SONAMU_DB_PASSWORD=your-dev-password
SONAMU_DB_NAME=myproject_development

.env.staging

SONAMU_DB_HOST=staging-db.example.com
SONAMU_DB_PORT=5432
SONAMU_DB_USER=myproject_staging
SONAMU_DB_PASSWORD=your-staging-password
SONAMU_DB_NAME=myproject_staging

.env.production

SONAMU_DB_HOST=prod-db.example.com
SONAMU_DB_PORT=5432
SONAMU_DB_USER=myproject_prod
SONAMU_DB_PASSWORD=your-production-password
SONAMU_DB_NAME=myproject_production

.env.test

SONAMU_DB_HOST=127.0.0.1
SONAMU_DB_PORT=5432
SONAMU_DB_USER=postgres
SONAMU_DB_PASSWORD=your-test-password
SONAMU_DB_NAME=myproject_test
SONAMU_DB_FIXTURE_NAME=myproject_fixture

sonamu.config.ts

sonamu.config.ts can read process.env directly. Sonamu loads the current environment before it imports the config file.

sonamu.config.ts

import { defineConfig } from "sonamu";

export default defineConfig({
  projectName: process.env.PROJECT_NAME ?? "MyProject",
  database: {
    database: "pg",
    defaultOptions: {
      pool: {
        min: 1,
        max: 10,
      },
    },
  },
});

Do not use the removed database.name or database.environments fields. Database names and environment-specific connections now come from SONAMU_DB_* variables and projectName.

Conversion Tips

Replace DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, and DATABASE_NAME with SONAMU_DB_HOST, SONAMU_DB_PORT, SONAMU_DB_USER, SONAMU_DB_PASSWORD, and SONAMU_DB_NAME.
Use SONAMU_DB_READONLY_* for read-only replicas. Any missing read-only field uses the current environment’s main DB value.
Use SONAMU_DB_FIXTURE_* only for the test fixture database.
Use .env.local for machine-local overrides that should apply after the shared and environment-specific files.

Get Started

Core Concepts

Database

API Development

Frontend Integration

Testing

Advanced Features

Tools & CLI

Configuration

API Reference

Troubleshooting

FAQ

Loading Order

File Layout

Common Values

Environment Values

sonamu.config.ts

Conversion Tips

​Loading Order

​File Layout

​Common Values

​Environment Values

​sonamu.config.ts

​Conversion Tips

Loading Order

File Layout

Common Values

Environment Values

sonamu.config.ts

Conversion Tips