Configuration

Platform~5 min

Centralized configuration for feature flags, app metadata, and environment variables.

Read this when you need to add a feature flag, change app settings, or understand how configuration works.
Useful for developers customizing Catalyst for their project.

Overview

All configuration lives in one place: lib/config.ts. This is the single source of truth for app settings, feature flags, and environment variables. Never hardcode values that might change — put them in config.

Environment variables are read once at build time and exposed through the typed config object. This gives you autocomplete and type safety throughout your app.

Quick Start

import { config } from "@/lib/config"

// App metadata
config.app.name           // "Catalyst"
config.app.description    // App description
config.app.url            // Base URL

// Feature flags
config.features.showDocsInProduction

// External links
config.links.repo         // Git repository URL

// Supabase settings
config.supabase.url       // Supabase project URL

// Storage settings
config.storage.bucket     // Default bucket name

Configuration Sections

The config object is organized into logical sections:

features

Feature flags control what's visible or enabled. Toggle docs visibility, dev tools, and AI features.

app

App metadata like name, description, and base URL. Used in layouts, SEO, and branding.

links

External links to repository, docs site, and support. Keeps URLs in one place.

devTools

Developer tools visibility settings. Show/hide dev cards in production or development only.

Feature Flags

Feature flags let you toggle functionality without code changes. Set them via environment variables or use the helper functions.

showDocsInProductionNEXT_PUBLIC_DOCS_ENABLED

Show documentation pages in production builds

Default: true

devTools.enabledNEXT_PUBLIC_DEV_TOOLS

Master switch for dev tools visibility

Default: true

devTools.devOnlyNEXT_PUBLIC_DEV_TOOLS_DEV_ONLY

Only show dev tools in development mode

Default: false

ai.enabledNEXT_PUBLIC_AI_ENABLED

Enable AI features and routes

Default: true

Helper Functions

import { isDocsEnabled, isDevToolsEnabled, isAIEnabled } from "@/lib/config"

// Check if feature is enabled
if (isDocsEnabled()) {
  // Show docs link
}

if (isDevToolsEnabled()) {
  // Show dev tools card
}

App Metadata

Basic app information used throughout the application.

app.name

Application name shown in headers, titles, and SEO

Default: "Catalyst"

app.description

App description for meta tags and marketing

Default: (see config.ts)

app.urlNEXT_PUBLIC_APP_URL

Base URL for the application

Default: http://localhost:3000

External Links

URLs for external resources. Set to null if not applicable for your project.

links.repo

Git repository URL (GitHub, GitLab, etc.)

Default: null or URL string

links.docs

External documentation site

Default: null

links.support

Support or contact link

Default: null

Environment Variables

Configuration is driven by environment variables. Copy .env.example to .env.local to get started.

Naming Convention

NEXT_PUBLIC_*

Safe for browser, bundled in client JS

No prefix

Server-only, safe for secrets

Never expose secrets to the browser. Only use NEXT_PUBLIC_ prefix for values that are safe to include in client-side JavaScript.

Adding New Configuration

When you need a new configurable value:

Add to config.ts

Add the new value to the appropriate section in lib/config.ts. Read from environment variable if it should be configurable per deployment.

Update .env.example

Add the environment variable to .env.example with a comment explaining what it does.

Use throughout app

Import from @/lib/config instead of reading process.env directly.

For AI Agents

Key rules:

Never hardcode app name, URLs, or feature flags
Always use config.* for configurable values
Add new env vars to .env.example
Use helper functions (isDocsEnabled()) for feature checks
Read lib/config.ts before adding new configuration