Application Configuration in the Tanstack Start Supabase SaaS Kit

Configure your app name, URL, theme colors, and locale settings in the Tanstack Start Supabase SaaS Kit using environment variables.

The application configuration at apps/web/config/app.config.ts defines your SaaS application's core settings: name, URL, theme, and locale. Configure these using environment variables rather than editing the file directly.

Configuration Approach

All configuration is driven by environment variables and validated with Zod at build time. Invalid configuration fails the build immediately, preventing deployment of broken settings.

Configuration Options

Variable	Required	Description
`VITE_PRODUCT_NAME`	Yes	Your product name (e.g., "Acme SaaS")
`VITE_SITE_TITLE`	Yes	Browser title tag and SEO title
`VITE_SITE_DESCRIPTION`	Yes	Meta description for SEO
`VITE_SITE_URL`	Yes	Full URL with protocol (e.g., `https://myapp.com`)
`VITE_DEFAULT_LOCALE`	No	Default language code (default: `en`)
`VITE_DEFAULT_THEME_MODE`	No	Theme: `light`, `dark`, or `system`
`VITE_THEME_COLOR`	Yes	Light theme color (hex, e.g., `#ffffff`)
`VITE_THEME_COLOR_DARK`	Yes	Dark theme color (hex, e.g., `#0a0a0a`)

Basic Setup

Add these to your .env file:

VITE_SITE_URL=https://myapp.com
VITE_PRODUCT_NAME="My SaaS App"
VITE_SITE_TITLE="My SaaS App - Build Faster"
VITE_SITE_DESCRIPTION="The easiest way to build your SaaS application"
VITE_DEFAULT_LOCALE=en
VITE_DEFAULT_THEME_MODE=light
VITE_THEME_COLOR="#ffffff"
VITE_THEME_COLOR_DARK="#0a0a0a"

How It Works

The configuration file parses environment variables through a Zod schema:

const appConfig = AppConfigSchema.parse({
  name: process.env.VITE_PRODUCT_NAME,
  title: process.env.VITE_SITE_TITLE,
  description: process.env.VITE_SITE_DESCRIPTION,
  url: process.env.VITE_SITE_URL,
  locale: process.env.VITE_DEFAULT_LOCALE,
  theme: process.env.VITE_DEFAULT_THEME_MODE,
  themeColor: process.env.VITE_THEME_COLOR,
  themeColorDark: process.env.VITE_THEME_COLOR_DARK,
  production,
});

Environment-Specific Configuration

Structure your environment files for different deployment stages:

File	Purpose
`.env`	Shared settings across all environments
`.env.development`	Local development overrides
`.env.production`	Production-specific settings
`.env.local`	Local secrets (git-ignored)

Example for development:

# .env.development
VITE_SITE_URL=http://localhost:3000

Example for production:

# .env.production (or CI/CD environment)
VITE_SITE_URL=https://myapp.com

Common Configuration Scenarios

B2C SaaS Application

VITE_PRODUCT_NAME="PhotoEdit Pro"
VITE_SITE_TITLE="PhotoEdit Pro - Edit Photos Online"
VITE_SITE_DESCRIPTION="Professional photo editing in your browser. No download required."
VITE_SITE_URL=https://photoedit.pro
VITE_DEFAULT_THEME_MODE=system

B2B SaaS Application

VITE_PRODUCT_NAME="TeamFlow"
VITE_SITE_TITLE="TeamFlow - Project Management for Teams"
VITE_SITE_DESCRIPTION="Streamline your team's workflow with powerful project management tools."
VITE_SITE_URL=https://teamflow.io
VITE_DEFAULT_THEME_MODE=light

Common Pitfalls

HTTP in production: The build fails if VITE_SITE_URL uses http:// in production. Always use https:// for production deployments.
Same theme colors: The build fails if VITE_THEME_COLOR equals VITE_THEME_COLOR_DARK. They must be different values.
Missing trailing slash: Don't include a trailing slash in VITE_SITE_URL. Use https://myapp.com not https://myapp.com/.
Forgetting to rebuild: Environment variable changes require a rebuild. Run pnpm build after changing production values.

Accessing Configuration in Code

Import the configuration anywhere in your application:

import appConfig from '#/config/app.config.ts';
// Access values
console.log(appConfig.name);        // "My SaaS App"
console.log(appConfig.url);         // "https://myapp.com"
console.log(appConfig.theme);       // "light"
console.log(appConfig.production);  // true/false

Environment Variables - Complete environment variable reference
Feature Flags - Enable or disable features
Going to Production - Production deployment checklist