Configuration files

Project configuration lives in config/. To change site information, feature switches, products, payments, or third-party services, first find the relevant configuration file, then check the schema and calling code for field requirements.

Reading configuration

Files in config/ are ordinary TypeScript modules. The application imports configuration constants directly, without converting them to JSON. Most configuration objects end with as const satisfies ...Input:

• as const preserves literals such as product IDs and role names so that other code can infer precise union types from them.
• satisfies checks field names and input types while preserving the object's exact type.

import type { WebsiteDeployCfgInput } from '@/libs/config/schemas/deploy';

export const websiteDeployCfg = {
    // Configuration settings
} as const satisfies WebsiteDeployCfgInput;

The server reads the full configuration through:

getServerConfig(): AppConfig

On the first call, the application merges all configuration and validates it with AppConfigSchema. Once validation succeeds, the result is stored in the configuration registry, and subsequent calls read it directly. If validation fails, the application reports Configuration validation failed at startup and stops startup.

The browser reads public configuration through:

getClientConfig(): typeof _rawConfig

Client configuration currently includes only base, i18n, scopes, ads, and analytics. These values are bundled for the browser and are directly visible to visitors, so they must not contain sensitive information.

Types ending in ...Input are the input types used in configuration files, usually with satisfies. A type with the same name but without Input generally represents the result after Zod validation. The two types may differ when fields have defaults, preprocessing rules, or optional settings. Use the Input type when writing configuration. Business code reads the validated configuration through getServerConfig().

Shared types

Multiple configuration files use LocalizedText and DateIntervalType. Their fields and usage rules are described below.

LocalizedText

The LocalizedText type specifies localized text and is defined in src/libs/i18n/types.ts. It is an object with value and key fields, not a plain string.

Provide at least one of value or key. For multilingual text, you usually provide both: the page first looks up the current language's text using key, then displays value if no translation is found.

{
    value: 'Saavo Starter',
    key: 'website.title',
}

DateIntervalType

The DateIntervalType type represents a duration as a string. It is commonly used for session lifetimes, cache durations, rate-limit periods, and affiliate settlement periods. The format is a number followed by a time unit, with an optional space between them.

You can also write units as full English words such as seconds, minutes, and hours. A number without a unit is interpreted as milliseconds, which is easy to get wrong, so always specifying a unit is recommended. Note that m means minutes, while mo means months.

Changing configuration

Configuration file index

At startup, the application validates configuration with the Zod schemas in src/libs/config/schemas/. TypeScript type checking catches field name and type errors. Zod also checks email formats, numeric ranges, cross-file references, and other constraints.

General considerations

• Do not casually rename exported configuration variables. The src/libs/config/client.ts and src/libs/config/index.ts modules import them directly, so renaming them also requires updating the loading code.
• The base.ts, i18n.ts, scopes.ts, ads.ts, and analytics.ts files are included in client configuration. Treat every field as public information. Other configuration files are also committed to the repository and must not contain secrets either.
• Configuration files reference one another. Roles reference capabilities, products reference roles and entitlements, affiliate configuration references products and plans, and upgrade suggestions reference OAuth authorization scopes. Search the entire project before renaming or deleting definitions rather than changing only the definition itself.
• TypeScript and Zod cannot confirm that external resources exist. Check Stripe Price IDs, Cloudflare bindings, email domains, and third-party service accounts on their respective platforms.
• Do not hardcode environment differences in configuration files. Domains, secrets, and values that differ between development, preview, and production belong in environment variables, Cloudflare secrets, or the corresponding deployment configuration.
• Pay attention to order when changing default arrays or objects. Some pages display menus, products, and options in configuration order. Reordering them can change what users see even when there is no type error.