Environment Variables

Kit verwendet 100+ Umgebungsvariablen, konfiguriert in apps/boilerplate/.env.local. Diese Seite ist eine vollständige Referenz, geordnet nach Service. Anleitungen zur Einrichtung findest du unter Konfiguration. Für das Deployment siehe Production Checklist.

Namenskonvention

Next.js erzwingt eine strikte Namensregel für die Sichtbarkeit von Umgebungsvariablen:

NEXT_PUBLIC_-Präfix — Dem Browser zugänglich (client-seitig). Wird beim Build-Prozess in JavaScript eingebettet.
Kein Präfix — Nur serverseitig. Verfügbar in API-Routen, Middleware und Server-Komponenten. Wird nie an den Browser gesendet.

API-Keys, Webhook-Secrets und Datenbank-URLs dürfen niemals das NEXT_PUBLIC_-Präfix verwenden. Falls ein Secret versehentlich client-seitig zugänglich ist, rotiere es sofort und deploye neu.

Tabellenspalten:

Name — Der Name der Umgebungsvariable
Geltungsbereich — Client (browserzugänglich) oder Server (nur serverseitig)
Pflicht — Ob die App diese Variable benötigt
Standard — Wert, der verwendet wird, wenn nicht gesetzt (leer = kein Standard, muss konfiguriert werden)
Beschreibung — Was die Variable steuert

Core-Anwendung

Name	Geltungsbereich	Pflicht	Standard	Beschreibung
`NEXT_PUBLIC_APP_URL`	Client	Ja	`http://localhost:3000`	Basis-URL der Anwendung für Links, Weiterleitungen und CORS
`NODE_ENV`	Server	Auto	—	Umgebung: `development`, `production`, `test`
`CRON_SECRET`	Server	Prod	—	Bearer-Token für die Authentifizierung von Vercel Cron-Jobs

Authentifizierung (Clerk)

Name	Geltungsbereich	Pflicht	Standard	Beschreibung
`NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY`	Client	Ja	—	Öffentlicher Clerk-Schlüssel für Frontend-Auth-Komponenten
`CLERK_SECRET_KEY`	Server	Ja	—	Geheimer Clerk-Schlüssel für serverseitige Auth-Operationen
`CLERK_WEBHOOK_SECRET`	Server	Ja	—	Svix-Signaturverifizierung für Clerk-Webhooks
`NEXT_PUBLIC_CLERK_SIGN_IN_URL`	Client	Nein	`/login`	Sign-In-Seiten-URL (Hash-Routing: `/login#`)
`NEXT_PUBLIC_CLERK_SIGN_UP_URL`	Client	Nein	`/register`	Sign-Up-Seiten-URL (Hash-Routing: `/register#`)
`NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL`	Client	Nein	`/dashboard`	Weiterleitungs-URL nach erfolgreicher Anmeldung
`NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL`	Client	Nein	`/dashboard`	Weiterleitungs-URL nach erfolgreicher Registrierung
`NEXT_PUBLIC_CLERK_ENABLED`	Client	Nein	`true`	Auf `false` setzen, um Clerk zu deaktivieren (Test-/Demo-Umgebungen)
`NEXT_PUBLIC_DEMO_MODE`	Client	Nein	`false`	Demo-Modus aktivieren — umgeht die Authentifizierung vollständig

NEXT_PUBLIC_DEMO_MODE=true deaktiviert die Clerk-Authentifizierung und verwendet einen Mock-Prisma-Client. Nützlich, um die UI zu präsentieren, ohne echte Zugangsdaten zu benötigen.

Datenbank (Supabase + Prisma)

Name	Geltungsbereich	Pflicht	Standard	Beschreibung
`DATABASE_URL`	Server	Ja	—	PostgreSQL-Verbindungs-URL mit PgBouncer-Pooling
`DIRECT_URL`	Server	Ja	—	Direkte PostgreSQL-URL für Prisma-Migrationen (ohne Pooling)
`NEXT_PUBLIC_SUPABASE_URL`	Client	Ja	—	Supabase-Projekt-URL
`NEXT_PUBLIC_SUPABASE_ANON_KEY`	Client	Ja	—	Supabase-Anonymous-Key (client-seitig, RLS-geschützt)
`SUPABASE_SERVICE_ROLE_KEY`	Server	Ja	—	Supabase-Service-Role-Key (umgeht RLS)

Für Supabase muss DATABASE_URL ?pgbouncer=true für Connection-Pooling enthalten. DIRECT_URL verbindet sich direkt mit PostgreSQL (Port 5432) und wird nur für prisma migrate und prisma db push verwendet.

Zahlungen (Lemon Squeezy)

Kernkonfiguration

Name	Geltungsbereich	Pflicht	Standard	Beschreibung
`LEMONSQUEEZY_API_KEY`	Server	Ja	—	Lemon Squeezy API-Key für Zahlungsoperationen
`LEMONSQUEEZY_STORE_ID`	Server	Ja	—	Deine Lemon Squeezy Store-ID
`LEMONSQUEEZY_WEBHOOK_SECRET`	Server	Ja	—	HMAC-Signaturverifizierung für Zahlungs-Webhooks
`LEMONSQUEEZY_TEST_MODE`	Server	Nein	`false`	Test-Modus für Zahlungstests aktivieren

Variant-IDs

Variant-IDs verknüpfen deine Lemon Squeezy-Produkte mit den Abonnement-Stufen der App. Die benötigten IDs hängen von deinem aktiven Preismodell ab.

Preismodell

Name	Geltungsbereich	Pflicht	Standard	Beschreibung
`NEXT_PUBLIC_PRICING_MODEL`	Client	Ja	`credit_based`	Aktives Preismodell: `credit_based` oder `classic_saas`
`CURRENCY`	Server	Nein	`EUR`	ISO 4217-Währungscode
`PRICING_TIERS`	Server	Nein	`basic,pro,enterprise`	Komma-getrennte Liste verfügbarer Stufen
`PRICING_FREE_TIER_ENABLED`	Server	Nein	`true`	Free-Tier für beide Modelle aktivieren
`PRICING_FREE_TIER_NAME`	Server	Nein	`Free Forever`	Anzeigename für den Free-Tier

Es kann nur ein Preismodell aktiv sein. NEXT_PUBLIC_PRICING_MODEL=credit_based aktiviert die Credit-basierte Preisgestaltung und deaktiviert Classic-SaaS-Variant-IDs — und umgekehrt. Das Mischen von Modellen verursacht Konfigurationsvalidierungsfehler.

E-Mail (Resend)

Name	Geltungsbereich	Pflicht	Standard	Beschreibung
`RESEND_API_KEY`	Server	Ja	—	Resend API-Key zum Versenden von E-Mails
`RESEND_FROM_EMAIL`	Server	Ja	—	Absender-E-Mail-Adresse (z.B. `noreply@yourdomain.com`)
`RESEND_WEBHOOK_SECRET`	Server	Ja	—	HMAC-Signaturverifizierung für Zustellungs-Webhooks
`NEXT_PUBLIC_CONTACT_EMAIL`	Client	Ja	—	Öffentliche Kontakt-E-Mail, die auf der Website angezeigt wird

Dateispeicherung (Vercel Blob)

Name	Geltungsbereich	Pflicht	Standard	Beschreibung
`BLOB_READ_WRITE_TOKEN`	Server	Ja	—	Vercel Blob-Token für Datei-Upload und -Download

KI-Integration

Provider-Konfiguration

Für KI-Features ist mindestens ein API-Key eines KI-Providers erforderlich. Das System erkennt verfügbare Provider automatisch anhand der gesetzten Keys.

Name	Geltungsbereich	Pflicht	Standard	Beschreibung
`AI_PROVIDER`	Server	Nein	Auto-Erkennung	Spezifischen Provider erzwingen: `openai`, `anthropic`, `google`, `xai`
`AI_MODEL`	Server	Nein	Provider-Standard	Standard-Modell für den ausgewählten Provider überschreiben
`OPENAI_API_KEY`	Server	Bedingt	—	API-Key für OpenAI (GPT-Modelle)
`ANTHROPIC_API_KEY`	Server	Bedingt	—	API-Key für Anthropic (Claude-Modelle)
`GOOGLE_AI_API_KEY`	Server	Bedingt	—	API-Key für Google (Gemini-Modelle)
`XAI_API_KEY`	Server	Bedingt	—	API-Key für xAI (Grok-Modelle)
`AI_API_KEY`	Server	Nein	—	Universeller Fallback-Key — wird verwendet, wenn kein provider-spezifischer Key für den aktiven `AI_PROVIDER` gesetzt ist, und als Embedding-Key-Fallback
`AI_EMBEDDING_MODEL`	Server	Nein	`text-embedding-3-small`	Embedding-Modell für RAG-Vektor-Generierung (muss OpenAI-kompatibel sein)

Setze mehrere Provider-Keys für automatischen Fallback. Wenn der primäre Provider ausfällt, versucht das System den nächsten verfügbaren Provider in dieser Reihenfolge: OpenAI, Anthropic, Google, xAI. Alternativ kannst du AI_API_KEY als einzigen Fallback-Key für den Provider angeben, der durch AI_PROVIDER festgelegt ist.

Provider-Overrides

Name	Geltungsbereich	Pflicht	Standard	Beschreibung
`OPENAI_BASE_URL`	Server	Nein	OpenAI-Standard	Benutzerdefinierte Basis-URL (für Proxies oder Azure OpenAI)
`OPENAI_ORG_ID`	Server	Nein	—	OpenAI-Organisations-ID
`ANTHROPIC_BASE_URL`	Server	Nein	Anthropic-Standard	Benutzerdefinierte Basis-URL für die Anthropic-API
`GOOGLE_AI_BASE_URL`	Server	Nein	Google-Standard	Benutzerdefinierte Basis-URL für die Google-AI-API
`XAI_BASE_URL`	Server	Nein	`https://api.x.ai/v1`	Benutzerdefinierte Basis-URL für die xAI-API

KI-Rate-Limiting

Name	Geltungsbereich	Pflicht	Standard	Beschreibung
`AI_FREE_TIER_REQUESTS`	Server	Nein	`20`	Monatliches Anfragelimit für Free-Tier
`AI_PRO_TIER_REQUESTS`	Server	Nein	`1000`	Monatliches Anfragelimit für Pro-Stufe
`AI_ENTERPRISE_TIER_REQUESTS`	Server	Nein	`10000`	Monatliches Anfragelimit für Enterprise-Stufe
`AI_RATE_LIMIT_WINDOW`	Server	Nein	`10`	Burst-Rate-Limit-Fenster in Sekunden
`AI_RATE_LIMIT_MAX_REQUESTS`	Server	Nein	`10`	Max. Anfragen pro Burst-Fenster
`AI_ANONYMOUS_MONTHLY_LIMIT`	Server	Nein	`5`	Max. Anfragen pro Monat für anonyme/nicht authentifizierte Nutzer

KI-Feature-Flags

Name	Geltungsbereich	Pflicht	Standard	Beschreibung
`AI_STREAMING_ENABLED`	Server	Nein	`true`	Streaming-KI-Antworten aktivieren
`AI_FUNCTIONS_ENABLED`	Server	Nein	`true`	Function-Calling aktivieren
`AI_VISION_ENABLED`	Server	Nein	`true`	Vision/Bildanalyse aktivieren

KI-Chat-Feature-Flags

Name	Geltungsbereich	Pflicht	Standard	Beschreibung
`NEXT_PUBLIC_AI_LLM_CHAT_ENABLED`	Client	Nein	`true`	LLM-Chat unter `/dashboard/chat-llm` aktivieren
`NEXT_PUBLIC_AI_RAG_CHAT_ENABLED`	Client	Nein	`true`	RAG-Chat unter `/dashboard/chat-rag` aktivieren
`NEXT_PUBLIC_AI_VISION_ENABLED`	Client	Nein	`true`	Bildanalyse im LLM-Chat aktivieren (Drag & Drop, Einfügen, Datei-Picker)
`NEXT_PUBLIC_AI_PDF_CHAT_ENABLED`	Client	Nein	`true`	PDF-Dokumentanalyse im LLM-Chat aktivieren (Drag & Drop, Datei-Picker)
`NEXT_PUBLIC_AI_AUDIO_INPUT_ENABLED`	Client	Nein	`false`	Audio-Eingabe (Sprache-zu-Text) im LLM-Chat aktivieren
`NEXT_PUBLIC_AI_IMAGE_GEN_ENABLED`	Client	Nein	`true`	Bildgenerierung unter `/dashboard/image-gen` aktivieren (eigenständig — erfordert keinen LLM-Chat)
`NEXT_PUBLIC_AI_CONTENT_GEN_ENABLED`	Client	Nein	`true`	Content-Generator unter `/dashboard/content` aktivieren (eigenständig — erfordert keinen LLM-Chat)

Vision-Chat (NEXT_PUBLIC_AI_VISION_ENABLED) erfordert, dass LLM-Chat (NEXT_PUBLIC_AI_LLM_CHAT_ENABLED) ebenfalls aktiviert ist. Beide müssen true sein, damit Bildanalysefunktionen aktiviert werden.

PDF-Chat (NEXT_PUBLIC_AI_PDF_CHAT_ENABLED) erfordert, dass LLM-Chat (NEXT_PUBLIC_AI_LLM_CHAT_ENABLED) ebenfalls aktiviert ist. Beide müssen true sein, damit PDF-Dokumentanalyse-Features aktiviert werden.

Audio-Eingabe (NEXT_PUBLIC_AI_AUDIO_INPUT_ENABLED) erfordert, dass LLM-Chat (NEXT_PUBLIC_AI_LLM_CHAT_ENABLED) ebenfalls aktiviert ist. Beide müssen true sein, damit die Sprache-zu-Text-Eingabe aktiviert wird.

Bildgenerierung (NEXT_PUBLIC_AI_IMAGE_GEN_ENABLED) ist ein eigenständiges Feature, das OPENAI_API_KEY erfordert — es verwendet OpenAIs GPT-Image-Modelle direkt.

Content-Generator (NEXT_PUBLIC_AI_CONTENT_GEN_ENABLED) ist ein eigenständiges Feature — es verwendet den aktiven KI-Provider für Template-basierte Textgenerierung.

Caching (Upstash Redis)

Name	Geltungsbereich	Pflicht	Standard	Beschreibung
`UPSTASH_REDIS_REST_URL`	Server	Prod	—	Upstash Redis REST-API-URL
`UPSTASH_REDIS_REST_TOKEN`	Server	Prod	—	Upstash Redis-Authentifizierungstoken

Redis ist in der Produktion für API-Rate-Limiting und KI-Rate-Limiting erforderlich. In der Entwicklung wird Rate-Limiting automatisch deaktiviert, wenn Redis nicht konfiguriert ist.

Sicherheit & CORS

Name	Geltungsbereich	Pflicht	Standard	Beschreibung
`ALLOWED_ORIGINS`	Server	Nein	`http://localhost:3000`	Komma-getrennte erlaubte Origins für CORS
`CSP_REPORT_URI`	Server	Nein	—	Endpunkt für Content-Security-Policy-Verletzungsberichte

Styling

Name	Geltungsbereich	Pflicht	Standard	Beschreibung
`COLOR_THEME`	Server	Nein	`default`	Aktives Farbthema: `default`, `ocean`, `forest`, `sunset`, `midnight`, `coral`, `slate`, `aurora`, `crimson`
`NEXT_PUBLIC_BREADCRUMB_ENABLED`	Client	Nein	`true`	Breadcrumb-Navigationsleiste unterhalb der Top-Bar im Dashboard anzeigen

Themenvorschauen und Anpassungsoptionen findest du unter Farbthemen.

Feature-Flags

Name	Geltungsbereich	Pflicht	Standard	Beschreibung
`ENABLE_CREDIT_SYSTEM_IN_TESTS`	Server	Nein	`false`	Credit-System in Unit-Tests aktivieren (nur Vitest)

Entwicklerwerkzeuge

Name	Geltungsbereich	Pflicht	Standard	Beschreibung
`NEXT_PUBLIC_DEVTOOLS_ENABLED`	Client	Nein	`true`	TanStack Query DevTools-Symbol anzeigen (unten rechts). Auf `false` setzen, um es in der Entwicklung auszublenden.