Konfiguration

Umgebungsvariablen, Feature Flags, Themes und Branding in nextsaas.ai Kit konfigurieren

Die gesamte Kit-Konfiguration erfolgt über eine einzige apps/boilerplate/.env.local-Datei und eine Branding-Konfigurationsdatei. Diese Seite behandelt die wesentlichen Einstellungen, die du kennen solltest. Eine vollständige Referenz aller Umgebungsvariablen findest du unter Umgebungsvariablen.

Überblick Umgebungsvariablen

Kit verwendet eine .env.local-Datei im Boilerplate-App-Verzeichnis für die gesamte Konfiguration. Diese Datei wird während der Installation durch Kopieren von .env.example erstellt.
bash
cp apps/boilerplate/.env.example apps/boilerplate/.env.local
Variablen folgen der Next.js-Konvention:
  • Nur-Server-Variablen — Nur in API-Routen und Server Components verfügbar (z. B. DATABASE_URL, CLERK_SECRET_KEY)
  • Client-Variablen — Mit NEXT_PUBLIC_ präfixiert, sowohl server- als auch clientseitig verfügbar (z. B. NEXT_PUBLIC_APP_URL)

Grundlegende Konfiguration

Das sind die Einstellungen, die du zuerst konfigurieren solltest, um eine funktionierende Entwicklungsumgebung zu erhalten.
1

App-URL

Setze die URL deiner Anwendung. In der Entwicklung ist das typischerweise localhost:3000:
bash
NEXT_PUBLIC_APP_URL=http://localhost:3000
In der Produktion setze hier deine eigentliche Domain:
bash
NEXT_PUBLIC_APP_URL=https://your-app.com
Diese URL wird für Metadaten, OAuth-Callbacks und Webhook-URLs verwendet.
2

Datenbank

Konfiguriere deine Datenbankverbindung. Wähle die Option, die zu deiner Einrichtung aus der Installation passt.
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/nextjs_dev
DIRECT_URL=postgresql://postgres:postgres@localhost:5432/nextjs_dev
.env.example
# Database Configuration
# ============================================
# You have TWO options for database setup:
#
# Option 1: Docker Compose (Recommended for Local Development)
#   - Run: docker-compose up -d
#   - Use URLs below (localhost)
#   - No external setup needed
#
# Option 2: Supabase (Recommended for Production)
#   - Managed PostgreSQL with built-in features
#   - Use pooled connection URL (port 6543)
#   - Example: postgresql://postgres.[project]:[password]@aws-1-eu-central-1.pooler.supabase.com:6543/postgres?pgbouncer=true&connection_limit=1

# Option 1: Docker Compose URLs (local development)
# Uncomment these when using docker-compose up -d:
# DATABASE_URL=postgresql://postgres:postgres@localhost:5432/nextjs_dev
# DIRECT_URL=postgresql://postgres:postgres@localhost:5432/nextjs_dev

# Option 2: Supabase URLs (production)
# Use the pooled connection URL with pgbouncer parameters
DATABASE_URL=

# Direct connection URL for migrations only - no pooling
# Example: postgresql://postgres.[project]:[password]@aws-1-eu-central-1.pooler.supabase.com:5432/postgres
DIRECT_URL=
3

Authentifizierung

Clerk übernimmt die gesamte Authentifizierung. Du benötigst einen Publishable Key und einen Secret Key aus dem Clerk Dashboard.
bash
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...
Die übrigen Clerk-Variablen haben sinnvolle Standardwerte:
bash
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/login
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/register
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=/dashboard
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=/dashboard
4

Preismodell

Kit unterstützt zwei Preismodelle. Wähle das Modell, das zu deinem Geschäft passt:
.env.example
# ============================================
# PRICING MODEL SELECTION (REQUIRED)
# ============================================
# Choose ONE model for your application
# IMPORTANT: Only ONE can be active at a time!
#
# Options:
#   - credit_based: AI/API-heavy apps with variable costs
#   - classic_saas: Standard SaaS with fixed costs per user
NEXT_PUBLIC_PRICING_MODEL=credit_based
  • credit_based — Für KI- und API-intensive Apps mit variablem Nutzungsverhalten. Nutzer kaufen Credits und verbrauchen sie pro Aktion.
  • classic_saas — Traditionelles Abonnement-Pricing mit monatlichen/jährlichen Plänen und festen Feature-Sets.
Es kann immer nur eines aktiv sein. Die App validiert dies beim Start und zeigt einen Fehler an, wenn die Konfiguration ungültig ist.

Farbthemen

Kit enthält 9 Farbthemen. Ändere das Erscheinungsbild deiner gesamten Anwendung mit einer einzigen Umgebungsvariable:
bash
COLOR_THEME=default
Verfügbare Themes:
.env.example
# COLOR THEME CONFIGURATION
# ============================================
# Choose your application's color scheme
# Available themes:
#   - default   : Classic blue (professional and trustworthy)
#   - ocean     : Deep blue and teal (maritime and tech startups)
#   - forest    : Emerald green (sustainable and eco-friendly SaaS)
#   - sunset    : Warm orange and pink (creative design tools)
#   - midnight  : Deep purple and blue (premium enterprise look)
#   - coral     : Vibrant pink and coral (modern consumer apps)
#   - slate     : Neutral gray with blue accents (professional business tools)
#   - aurora    : Bright cyan and turquoise (cutting-edge tech platforms)
#   - crimson   : Bold red and violet (performance and analytics)
#
# To add a custom theme:
# 1. Create a new CSS file in src/styles/themes/your-theme.css
# 2. Import it in src/app/globals.css
# 3. Add theme name to AVAILABLE_THEMES in src/styles/themes/themes.ts
COLOR_THEME=default
# Dashboard breadcrumb navigation: true | false (default: true)
NEXT_PUBLIC_BREADCRUMB_ENABLED=true
Jedes Theme bietet sowohl helle als auch dunkle Varianten:
src/styles/themes/themes.ts
export const THEME_METADATA: Record<ThemeName, ThemeMetadata> = {
  default: {
    name: 'default',
    displayName: 'Default Blue',
    description: 'Classic blue theme - professional and trustworthy',
    primaryColor: '#3b82f6',
    category: 'blue',
  },
  ocean: {
    name: 'ocean',
    displayName: 'Ocean',
    description: 'Deep blue and teal - perfect for maritime and tech startups',
    primaryColor: '#0891b2',
    category: 'teal',
  },
  forest: {
    name: 'forest',
    displayName: 'Forest',
    description: 'Emerald green - ideal for sustainable and eco-friendly SaaS',
    primaryColor: '#10b981',
    category: 'green',
  },
  sunset: {
    name: 'sunset',
    displayName: 'Sunset',
    description: 'Warm orange and pink - creative and energetic design tools',
    primaryColor: '#f97316',
    category: 'warm',
  },
  midnight: {
    name: 'midnight',
    displayName: 'Midnight',
    description: 'Deep purple and blue - premium enterprise look',
    primaryColor: '#6366f1',
    category: 'purple',
  },
  coral: {
    name: 'coral',
    displayName: 'Coral',
    description: 'Vibrant pink and coral - modern consumer applications',
    primaryColor: '#ec4899',
    category: 'pink',
  },
  slate: {
    name: 'slate',
    displayName: 'Slate',
    description: 'Neutral gray with blue accents - professional business tools',
    primaryColor: '#64748b',
    category: 'neutral',
  },
  aurora: {
    name: 'aurora',
    displayName: 'Aurora',
    description: 'Bright cyan and turquoise - cutting-edge tech platforms',
    primaryColor: '#06b6d4',
    category: 'teal',
  },
  crimson: {
    name: 'crimson',
    displayName: 'Crimson',
    description: 'Bold red and violet - performance and analytics platforms',
    primaryColor: '#dc2626',
    category: 'red',
  },
}
Informationen zum Erstellen eigener Themes findest du unter Farbthemen & Dark Mode.

Feature Flags

Kit verwendet Umgebungsvariablen als Feature Flags, um Funktionen zu aktivieren oder zu deaktivieren.

KI-Features

Steuere, welche KI-Features in deiner Anwendung verfügbar sind:
.env.example
# ============================================
# AI CHAT BOT FEATURE FLAGS
# ============================================
# Two separate AI chat systems exist.
# Each system can be independently enabled/disabled.
# All features default to 'true' for backwards compatibility.
# Set to 'false' to disable specific features.

# ============================================
# AI CHAT FEATURES
# ============================================

# RAG Chat
# Dashboard route: /dashboard/chat-rag
# API routes: /api/ai/rag/*
# Features: Claude-style UI, Knowledge Base integration, Source Attribution
# Requires: pgvector database with FAQ chunks
NEXT_PUBLIC_AI_RAG_CHAT_ENABLED=true

# LLM Chat (Direct Chat)
# Dashboard route: /dashboard/chat-llm
# API routes: /api/ai/chat, /api/ai/stream
# Features: Clean Chat UI, Direct LLM conversation, Streaming
# Does NOT require FAQ (Rag Chat) database setup
NEXT_PUBLIC_AI_LLM_CHAT_ENABLED=true

# Vision Chat (Image Analysis in LLM Chat)
# Extends LLM Chat with image upload and analysis capabilities.
# Requires LLM Chat to be enabled. Only active when BOTH flags are true.
# Features: Drag & Drop, Paste, File picker for image analysis
NEXT_PUBLIC_AI_VISION_ENABLED=true

# PDF Chat (Document Analysis in LLM Chat)
# Extends LLM Chat with PDF upload and text extraction capabilities.
# Requires LLM Chat to be enabled. Only active when BOTH flags are true.
# Features: Drag & Drop, File picker, server-side text extraction, all providers
NEXT_PUBLIC_AI_PDF_CHAT_ENABLED=true

# Audio Input (Speech-to-Text in LLM Chat)
# Adds a microphone button for voice input via OpenAI Whisper.
# Requires LLM Chat to be enabled. Only active when BOTH flags are true.
# Features: Browser-native recording, real-time audio levels, auto-transcription
NEXT_PUBLIC_AI_AUDIO_INPUT_ENABLED=true

# Image Generation (Text-to-Image)
# Dashboard route: /dashboard/image-gen
# API route: /api/ai/image-gen
# Features: GPT Image models, multiple sizes/qualities/formats, transparent backgrounds
# Standalone feature — does NOT require LLM Chat to be enabled.
# Requires: OPENAI_API_KEY
NEXT_PUBLIC_AI_IMAGE_GEN_ENABLED=true

# Content Generator — Template-based text generation
# Dashboard route: /dashboard/content
# API route: /api/ai/generate-content
# Features: 5 templates (Email, Product, Blog, Social, Marketing), SSE streaming, tone/language/length options
# Standalone feature — does NOT require LLM Chat to be enabled.
NEXT_PUBLIC_AI_CONTENT_GEN_ENABLED=true

# ============================================
# COMMON CONFIGURATIONS
# ============================================
# Use these combinations based on your needs:
#
# 1. Full AI Features (Default):
#    NEXT_PUBLIC_AI_RAG_CHAT_ENABLED=true
#    NEXT_PUBLIC_AI_LLM_CHAT_ENABLED=true
#
# 2. RAG Chat Only:
#    NEXT_PUBLIC_AI_RAG_CHAT_ENABLED=true
#    NEXT_PUBLIC_AI_LLM_CHAT_ENABLED=false
#
# 3. LLM Chat Only:
#    NEXT_PUBLIC_AI_RAG_CHAT_ENABLED=false
#    NEXT_PUBLIC_AI_LLM_CHAT_ENABLED=true
#
# 4. No AI Features (Disable All):
#    NEXT_PUBLIC_AI_RAG_CHAT_ENABLED=false
#    NEXT_PUBLIC_AI_LLM_CHAT_ENABLED=false
Häufige Konfigurationen:
AnwendungsfallRAG ChatLLM ChatVisionAudioPDFBildgenerierungContent Gen
Alle KI-Featurestruetruetruetruetruetruetrue
Nur RAG Chattruefalsefalsefalsefalsefalsefalse
Nur LLM Chatfalsetruetruetruetruefalsefalse
LLM Chat (nur Text)falsetruefalsefalsefalsefalsefalse
Nur Generatorenfalsefalsefalsefalsefalsetruetrue
Keine KI-Featuresfalsefalsefalsefalsefalsefalsefalse

Demo-Modus

Der Demo-Modus bietet eine voll funktionsfähige Demo ohne echte API-Schlüssel:
bash
NEXT_PUBLIC_DEMO_MODE=true
Wenn aktiviert, verwendet Kit Mock-Daten für alle externen Dienste (Auth, Zahlungen, KI). Das ist nützlich, um das Produkt vorzuführen, ohne sich mit Live-Diensten zu verbinden. Details findest du im Abschnitt zum Demo-Modus in der Authentifizierungsübersicht.

Service-Konfiguration

Jeder integrierte Dienst benötigt seine eigenen Umgebungsvariablen. Konfiguriere sie, wenn du den jeweiligen Dienst benötigst.
DienstErforderliche VariablenDokumentation
Clerk (Auth)NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY, CLERK_SECRET_KEYAuthentifizierung
Supabase (DB)DATABASE_URL, DIRECT_URLDatenbank
Lemon Squeezy (Zahlungen)LEMONSQUEEZY_API_KEY, LEMONSQUEEZY_STORE_ID, LEMONSQUEEZY_WEBHOOK_SECRETZahlungen
Resend (E-Mail)RESEND_API_KEY, RESEND_FROM_EMAILE-Mail-Service
Vercel Blob (Speicherung)BLOB_READ_WRITE_TOKENDateispeicherung
Upstash (Redis)UPSTASH_REDIS_REST_URL, UPSTASH_REDIS_REST_TOKENCaching & Redis
KI-ProviderAI_API_KEY (universell) oder providerspezifisch: OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_AI_API_KEY, XAI_API_KEYKI-Integration

Branding

App-Name, Slogan und Metadaten werden in einer einzigen Datei konfiguriert:
src/config/site.ts
export const siteConfig = {
  /** Your brand/product name */
  name: 'nextsaas.ai Kit',

  /** Short description for the homepage title tag */
  tagline: 'AI-Native Next.js SaaS Boilerplate',

  /** Name used for blog article title tags */
  blogName: 'nextsaas.ai Blog',

  /** Separator between page name and brand (En-dash is professional standard) */
  separator: '–',

  /** Base URL for metadata */
  url: process.env.NEXT_PUBLIC_APP_URL || 'http://localhost:3000',

  /** Default description for pages without custom description */
  description:
    'Production-ready Next.js boilerplate with authentication, database, and modern UI components.',

  /** Author information */
  author: {
    name: 'Jon Doe',
    twitter: '@jondoe',
  },
} as const

export type SiteConfig = typeof siteConfig
Passe diese Werte an dein Produkt an:
typescript
export const siteConfig = {
  name: 'YourProduct',
  tagline: 'Your Value Proposition Here',
  blogName: 'YourProduct Blog',
  // ...
}
Diese Konfiguration wird in der gesamten Anwendung verwendet für:
  • Seitentitel und SEO-Metadaten
  • Open Graph und Twitter Card Metadaten
  • Footer- und Navigations-Branding
  • E-Mail-Templates

Sicherheitskonfiguration

Kit enthält mehrere sicherheitsrelevante Umgebungsvariablen:
bash
# CORS: Kommagetrennte Liste erlaubter Origins
ALLOWED_ORIGINS=http://localhost:3000

# CSP: Optionaler Reporting-Endpunkt für Content Security Policy-Verletzungen
CSP_REPORT_URI=

# Cron: Geheimnis zur Authentifizierung von geplanten Jobs
CRON_SECRET=
Setze in der Produktion ALLOWED_ORIGINS auf deine Domain(s) und generiere ein starkes CRON_SECRET:
bash
# Einen sicheren Zufalls-String generieren
openssl rand -base64 32
Eine vollständige Anleitung zur Konfiguration von Rate Limiting, Security Headers und Eingabevalidierung findest du in der Sicherheitsübersicht.

Konfigurationsvalidierung

Kit validiert die kritische Konfiguration beim Start. Konkret wird die Preismodell-Konfiguration beim Rendern des Root-Layouts geprüft:
  • Wenn NEXT_PUBLIC_PRICING_MODEL auf einen ungültigen Wert gesetzt ist, zeigt die App eine klare Fehlermeldung
  • Wenn für das gewählte Preismodell erforderliche Variant-IDs fehlen, erscheint eine Warnung in der Konsole
Diese Validierung erfolgt automatisch — du musst keine Befehle ausführen.