App Configuration Settings

Set your product name, site URL, theme, and locale through environment variables in apps/web/.env. These values flow throughout the application - page titles, email templates, OAuth redirects, and more.

App configuration refers to the core branding and behavior settings that define your application's identity and default user experience. Unlike feature flags, these settings are typically set once and rarely change.

This page is part of the Configuration documentation.

Essential Settings

# apps/web/.env
NEXT_PUBLIC_PRODUCT_NAME="Your SaaS"
NEXT_PUBLIC_SITE_URL="http://localhost:3000"
NEXT_PUBLIC_DEFAULT_LOCALE="en"
NEXT_PUBLIC_DEFAULT_THEME_MODE="light"
NEXT_PUBLIC_APP_HOME_PATH=/dashboard

Use app configuration for: branding that appears across the entire application, URLs that other systems depend on (OAuth, emails), and defaults that affect all users.

Avoid changing frequently: these values often require cache invalidation or affect external integrations.

If unsure about a value: use the defaults until you have a reason to change them.

Product Name

Your application name appears in:

• Browser tab titles
• Navigation headers
• Transactional emails
• Meta tags and social previews

NEXT_PUBLIC_PRODUCT_NAME="Your SaaS Name"

Access it programmatically:

import { appConfig } from '@config/app.config';
console.log(appConfig.name); // "Your SaaS Name"

Site URL

The canonical base URL for your application:

# Development
NEXT_PUBLIC_SITE_URL="http://localhost:3000"
# Production
NEXT_PUBLIC_SITE_URL="https://yourdomain.com"

Used for:

• OAuth callback URLs (must match provider configuration)
• Email links (password reset, invitations)
• Open Graph and social previews
• Canonical URL tags for SEO
• Absolute URL generation in APIs

Theme Settings

Default Theme Mode

NEXT_PUBLIC_DEFAULT_THEME_MODE="light"

Users can override this in their account settings. The setting persists in local storage.

Locking Users to a Single Theme

If you want to prevent theme switching entirely, combine the theme mode with the feature flag:

NEXT_PUBLIC_DEFAULT_THEME_MODE="dark"
NEXT_PUBLIC_ENABLE_THEME_TOGGLE=false

Locale Settings

NEXT_PUBLIC_DEFAULT_LOCALE="en"

This sets the default language for new users. Supported values must be defined in your i18n configuration at lib/i18n/i18n.settings.ts. See the internationalization documentation for adding new languages.

App Home Path

The authenticated user's landing page after login:

NEXT_PUBLIC_APP_HOME_PATH=/dashboard

Change this if your main app entry point is different - for example, /home, /app, or /projects. This path is referenced in redirects, navigation, and middleware.

Email Sender

EMAIL_SENDER="Your App <noreply@yourdomain.com>"

Format: Display Name <email@domain.com>

Best practices:

• Verify your sending domain with your email provider (prevents spam filtering)
• Use noreply@ for automated transactional emails
• Use a monitored address for emails that might get replies

See the email configuration documentation for SMTP and provider setup.

Per-Page Metadata

Override global metadata for specific pages using the Next.js Metadata API:

// apps/web/app/[locale]/about/page.tsx
import type { Metadata } from 'next';
export const metadata: Metadata = {
  title: 'About Us',
  description: 'Learn more about our company and mission.',
  openGraph: {
    title: 'About Us - Your SaaS',
    description: 'Learn more about our company.',
    url: '/about',
  },
};
export default function AboutPage() {
  return <AboutContent />;
}

The title automatically appends your product name via the template defined in the root layout.

Common Pitfalls

• Trailing slash in SITE_URL: Causes double-slash URLs and broken OAuth redirects. Always omit it: https://example.com not https://example.com/
• Mismatched OAuth URLs: Your SITE_URL must exactly match what you configured in Google/GitHub OAuth settings. Localhost vs 127.0.0.1 matters.
• Changing APP_HOME_PATH after launch: Existing bookmarks and links will break. Set up redirects if you change this.
• Unverified email domain: Emails land in spam. Verify your domain with your email provider before going to production.
• Forgetting to update production .env: Development defaults don't transfer automatically. Set all production values in your hosting platform.

Configuration Reference

Next: Environment Variables →