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)
Variablen mit dem Präfix
NEXT_PUBLIC_ werden in das Client-JavaScript eingebettet und sind für jeden sichtbar, der deine Website untersucht. Lege niemals Geheimnisse, API-Schlüssel oder Passwörter in NEXT_PUBLIC_-Variablen ab.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_...
Du kannst diesen Schritt zunächst überspringen und
pnpm dev:no-clerk verwenden, um ohne Clerk zu entwickeln. Kit stellt ein Mock-Authentifizierungssystem für die Entwicklung bereit. Konfiguriere Clerk, wenn du bereit bist, echte Authentifizierungsabläufe zu testen.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',
},
}
Das Wechseln des Themes erfordert keine Code-Änderungen — aktualisiere einfach
COLOR_THEME in apps/boilerplate/.env.local und starte den Dev-Server neu. Das Theme-System verwendet CSS Custom Properties, sodass alle Komponenten die neuen Farben automatisch übernehmen.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:
| Anwendungsfall | RAG Chat | LLM Chat | Vision | Audio | Bildgenerierung | Content Gen | |
|---|---|---|---|---|---|---|---|
| Alle KI-Features | true | true | true | true | true | true | true |
| Nur RAG Chat | true | false | false | false | false | false | false |
| Nur LLM Chat | false | true | true | true | true | false | false |
| LLM Chat (nur Text) | false | true | false | false | false | false | false |
| Nur Generatoren | false | false | false | false | false | true | true |
| Keine KI-Features | false | false | false | false | false | false | false |
Vision Chat (
NEXT_PUBLIC_AI_VISION_ENABLED) erfordert, dass LLM Chat aktiviert ist. Wenn NEXT_PUBLIC_AI_LLM_CHAT_ENABLED auf false steht, hat das Vision-Flag keine Wirkung.Audio-Eingabe (
NEXT_PUBLIC_AI_AUDIO_INPUT_ENABLED) erfordert, dass LLM Chat aktiviert ist. Wenn NEXT_PUBLIC_AI_LLM_CHAT_ENABLED auf false steht, hat das Audio-Eingabe-Flag keine Wirkung.Bildgenerierung (
NEXT_PUBLIC_AI_IMAGE_GEN_ENABLED) ist ein eigenständiges Feature, das OPENAI_API_KEY erfordert — es verwendet OpenAIs GPT-Image-Modelle direkt, unabhängig vom konfigurierten AI_PROVIDER.Content Generator (
NEXT_PUBLIC_AI_CONTENT_GEN_ENABLED) ist ein eigenständiges Feature — es verwendet den aktiven KI-Provider für vorlagenbasierte Texterstellung (E-Mail, Produktbeschreibungen, Blog-Gliederungen, Social-Media-Posts, Marketingtexte).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.
| Dienst | Erforderliche Variablen | Dokumentation |
|---|---|---|
| Clerk (Auth) | NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY, CLERK_SECRET_KEY | Authentifizierung |
| Supabase (DB) | DATABASE_URL, DIRECT_URL | Datenbank |
| Lemon Squeezy (Zahlungen) | LEMONSQUEEZY_API_KEY, LEMONSQUEEZY_STORE_ID, LEMONSQUEEZY_WEBHOOK_SECRET | Zahlungen |
| Resend (E-Mail) | RESEND_API_KEY, RESEND_FROM_EMAIL | E-Mail-Service |
| Vercel Blob (Speicherung) | BLOB_READ_WRITE_TOKEN | Dateispeicherung |
| Upstash (Redis) | UPSTASH_REDIS_REST_URL, UPSTASH_REDIS_REST_TOKEN | Caching & Redis |
| KI-Provider | AI_API_KEY (universell) oder providerspezifisch: OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_AI_API_KEY, XAI_API_KEY | KI-Integration |
Für die Produktion müssen alle Dienste konfiguriert sein, die für deine Features als erforderlich markiert sind. In der Entwicklung behandelt Kit fehlende Zugangsdaten elegant, indem es die entsprechenden Features deaktiviert oder Mock-Daten verwendet. Alle Umgebungsvariablen gehören in
apps/boilerplate/.env.local.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_MODELauf 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.