Application Configuration

Configure and customize the Next.js Prisma SaaS Kit for your application's needs including branding, settings, and features.

Configure your MakerKit application through environment variables and TypeScript config files - no core code changes required.

MakerKit uses environment variables (.env files) for runtime settings like database URLs, API keys, and feature toggles. TypeScript config files in apps/web/config/ handle complex structures like navigation menus. Set NEXT_PUBLIC_* variables for client-accessible values; keep secrets in .env.local (git-ignored). Configuration sources cascade by priority: .env.local overrides .env.development, which overrides .env.

Configuration in MakerKit refers to the centralized settings that control your app's behavior, branding, features, and integrations. All configuration is type-safe (validated with Zod at build time).

Quick Start

Most configuration happens through environment variables in your .env files:

# Essential settings (apps/web/.env)
NEXT_PUBLIC_PRODUCT_NAME="Your SaaS"
NEXT_PUBLIC_SITE_URL="http://localhost:3000"
NEXT_PUBLIC_ACCOUNT_MODE="hybrid"
DATABASE_URL="postgresql://..."
BETTER_AUTH_SECRET="your-32-char-secret"

Use environment variables when: you need different values per environment (dev/staging/prod), the value contains secrets, or you want to change settings without redeploying.

Use config files when: you need complex objects, TypeScript validation, or the setting requires code (like React components in navigation).

If unsure: start with environment variables - you can always refactor later.

Configuration Architecture

Configuration Sources (Priority: High → Low)
├── .env.local              # Local secrets (git-ignored)
├── .env.development        # Dev defaults (committed)
├── .env                    # Shared defaults (committed)
├── apps/web/config/        # TypeScript configs
└── Package defaults        # Sensible fallbacks

Higher-priority sources override lower ones. For example, a value in .env.local overrides the same key in .env.

Configuration Areas

AreaFile/VariablePurpose
App SettingsNEXT_PUBLIC_* varsBranding, URLs, themes
Environment Variables.env filesAll runtime settings
Account ModesNEXT_PUBLIC_ACCOUNT_MODEB2B vs B2C vs hybrid
Feature Flagsfeature-flags.config.tsToggle functionality
Navigation*-navigation.config.tsxMenus and sidebars

Common Pitfalls

  • Forgetting to restart the dev server after changing .env files - Next.js only reads env vars at startup
  • Using NEXT_PUBLIC_ prefix for secrets - these are exposed to the browser; never prefix sensitive values
  • Trailing slashes in SITE_URL - causes broken OAuth redirects and canonical URLs; always omit the trailing slash
  • Mismatched env files across team members - use .env.example as a template and document required variables
  • Hardcoding values that should be configurable - if it might change per environment, use an env var

Principles

The configuration system follows these patterns:

  1. Convention over configuration: Sensible defaults work out of the box. Only change what you need.
  2. Environment-based: Development and production use different files. Secrets stay in .env.local.
  3. Type-safe: All config files use Zod schemas. Typos and invalid values fail at build time.
  4. Centralized: Config lives in apps/web/config/ and .env files. No hunting through the codebase.

Configuration Topics

Explore each area in detail:

  1. App Configuration: Product name, site URL, theme, locale settings
  2. Environment Variables: Complete reference for all variables
  3. Account Modes: Personal-only, organizations-only, or hybrid
  4. Feature Flags: Enable/disable features without code changes
  5. Navigation: Header, footer, and sidebar menu structure

Next: App Configuration →