What's New

Erweiterung der Komponentenbibliothek

Die gemeinsame Komponentenbibliothek in packages/ui/ wurde von 22 auf 50 vorkonfigurierte shadcn/ui-Komponenten ausgebaut. Neu hinzugekommen sind Accordion, Avatar, Calendar, Carousel, Checkbox, Collapsible, Command, Drawer, Input OTP, Menubar, Pagination, Radio Group, Resizable, Scroll Area, Separator, Slider, Switch, Table, Tabs, Toggle, Toggle Group sowie Typography – allesamt mit konsistentem Spacing, Border Radius und Color Tokens.

Das Dashboard verfügt jetzt über eine automatische Breadcrumb-Navigationsleiste, die die aktuelle Routenhierarchie widerspiegelt.

Extrahierte gemeinsame Komponenten

Sieben Komponenten wurden aus wiederkehrenden Mustern im Dashboard in eigenständige, wiederverwendbare Module ausgelagert.

Drei Layout-Wrapper reduzieren den Boilerplate-Code für häufige Seitenmuster: LegalPage umschließt die Datenschutz-, AGB- und Impressumsseiten mit einer einheitlichen Struktur. DashboardFeaturePage kombiniert Feature-Gate-Prüfung, Suspense-Boundaries und LoadingSpinner in einem einzigen Wrapper, der von den vier KI-Feature-Seiten genutzt wird. CenteredPage stellt das zentrierte Layout bereit, das von Fehler-, Not-Found- und Logout-Seiten gemeinsam verwendet wird. CollapsibleSection fügt einen Toggle mit Anzahl der Einträge und einer Aktion zum Leeren hinzu – extrahiert aus den Verlaufskomponenten für Content- und Bildgenerierung.

Neue Hilfskomponenten

Sechs neue Komponenten erweitern das UI-Toolkit um gängige Interaktionsmuster. CopyButton rendert einen Copy-to-Clipboard-Button, der nach dem Klick für zwei Sekunden ein Check-Icon anzeigt. StatusBadge zeigt semantische Statusindikatoren mit fünf Varianten an (success, warning, error, info, neutral). StatCard ist eine KPI-Anzeigecard, die ein Icon, ein optionales Badge, einen formatierten Wert und untergeordnete Inhalte akzeptiert.

ConfirmDialog hüllt den shadcn/ui AlertDialog mit Variantenunterstützung für destruktive und warnende Bestätigungsabläufe inklusive Ladezustand ein. LoadingButton erweitert den shadcn/ui Button um einen integrierten Ladespinner, der während asynchroner Operationen automatisch deaktiviert wird. CreditCost rendert ein eingebettetes Coins-Icon mit Kostentext zur Anzeige der Credit-Kosten für KI-Features.

Dashboard-Struktur

Der Showcase-Bereich wurde aus dem Dashboard entfernt. Sidebar-Navigation, Quick-Actions-Leiste, Account-Dropdown und Credit-Badge wurden aktualisiert, um die vereinfachte Struktur widerzuspiegeln. Die Dashboard-Startseite zeigt jetzt produktrelevante Quick-Action-Karten für AI Suite, Credits & Usage, Subscription Plan und Quick Start.

Credits-Seite neu gestaltet

Die Credit-Übersichtskomponente wurde vollständig überarbeitet. Stat-Cards verwenden ein responsives Grid, das sich vom gestapelten Mobile-Layout zu einer vierspaltigen Desktop-Ansicht anpasst. Der Bereich für Bonus-Pakete wechselt zwischen horizontalem Scroll auf Mobilgeräten und einem festen Grid auf größeren Bildschirmen. Die Transaktionshistorie-Tabelle nutzt jetzt eine gemeinsame Grid-Spalten-Konstante über Header, Datenzeilen und Skeleton-Platzhalter hinweg, um vertikale Ausrichtung zu gewährleisten. Die Datumsformatierung wurde auf einen kompakten MAR 09 | 11:00-Stil umgestellt, und die Spaltenreihenfolge wurde zu Datum, Beschreibung, Betrag, Typ und Saldo verfeinert.

Paket-Architektur

Das Blog- und Changelog-System wird als @nextsaasai/blog-Paket mit einer dualen Export-Struktur ausgeliefert. Server-seitige Operationen — Dateisystem-Lesezugriffe, MDX-Kompilierung, Frontmatter-Parsing — werden aus @nextsaasai/blog exportiert. Client-seitige React-Komponenten — Timeline-Layouts, Suche, Inhaltsverzeichnis — werden aus @nextsaasai/blog/client exportiert. Diese Trennung hält server-exklusive Abhängigkeiten (Node.js fs, MDX-Compiler) vollständig aus den Client-Bundles heraus.

Content-Dateien nutzen MDX mit YAML-Frontmatter, das zur Build-Zeit durch Zod-Schemas validiert wird. Ungültige oder fehlende Felder erzeugen klare Fehlermeldungen statt stiller Rendering-Fehler. Syntax-Highlighting läuft über Shiki mit Dual-Theme-Unterstützung — separate Themes für Light- und Dark-Mode, ohne Laufzeit-Overhead durch Theme-Wechsel.

Blog-Features

Blog-Posts sind über Dateisystem-Verzeichnisse organisiert, die direkt auf Navigations-Kategorien abgebildet werden. Jede Kategorie erhält eine eigene gefilterte Ansicht und einen RSS-2.0-Feed. Detailseiten enthalten ein Social-Sharing-Dropdown mit Unterstützung für X/Twitter, LinkedIn, Facebook, WhatsApp, E-Mail und Clipboard-Kopieren — plus native Share-API-Integration auf unterstützten Geräten.

Changelog-Features

Der Changelog verwendet ein vertikales Timeline-Layout. Einträge rendern ihren vollständigen Inhalt direkt auf der Listenansicht — kein Klick erforderlich, um ein Update zu lesen. Jeder Eintrag trägt eine Versionsnummer und ein Datum. Eine quick-Variante existiert für kleinere Updates, die nur einen Absatz oder zwei benötigen, während die full-Variante Überschriften, Code-Blöcke und einklappbare <Details>-Sektionen für längere Release Notes unterstützt. Contributor-Avatare erscheinen bei jedem Eintrag und verknüpfen Updates mit den Team-Mitgliedern, die sie umgesetzt haben.

Dokumentationsarchitektur

Das Dokumentationssystem ist als eigenständiges @nextsaasai/docs-Paket aufgebaut und nutzt Markdoc für die Inhaltserstellung. Markdoc wurde für die Dokumentation gegenüber MDX bevorzugt, weil es eine strenge Schema-Validierung für benutzerdefinierte Komponenten bietet und Content-Dateien frei von ausführbarem Code hält. Die Dokumentationsseiten werden auf der Marketing-Website gehostet, dokumentieren aber das Boilerplate-Produkt — du erreichst sie unter /docs neben den Marketing-Seiten.

Inhaltsabdeckung

Jedes wichtige Feature des Boilerplates hat einen entsprechenden Dokumentationsbereich: Authentifizierungs-Setup und -Konfiguration, Payment-Integration mit Lemon Squeezy, AI-Provider-Konfiguration, Security Hardening, Datenbankschema-Verwaltung und Deployment-Workflows. API-Referenzen werden automatisch aus dem Codebase generiert, um mit der Implementierung synchron zu bleiben.

Benutzerdefinierte Markdoc-Komponenten übernehmen wiederkehrende Dokumentationsmuster — Callouts für Warnungen und Tipps, Tab-Bereiche für Anleitungen in verschiedenen Umgebungen und Code-Gruppen zum Anzeigen verwandter Dateien nebeneinander. Diese Komponenten werden als React-Elemente gerendert, aber in reiner Markdoc-Syntax verfasst, sodass die Inhalte auch für Nicht-Entwickler zugänglich bleiben.

Warum ein dediziertes Refactor-Release

Mit dem Wachstum der Boilerplate durch neue Features überschritten mehrere Dateien die 150-Zeilen-Grenze und häuften gemischte Verantwortlichkeiten an. Dieses Release ist ein reiner Architektur-Pass ohne neue Features: Überdimensionierte Module werden in fokussierte Einheiten aufgeteilt, Barrel Exports sorgen für sauberere Import-Pfade, und eine konsistente Trennung der Zuständigkeiten wird im gesamten Codebase durchgesetzt. Der Minor-Version-Bump spiegelt den Umfang wider — nahezu jedes Verzeichnis wurde angefasst.

Was sich geändert hat

Dateien sind jetzt nach Verantwortlichkeit organisiert: Components, Hooks, Utilities und Types leben jeweils in eigenen Dateien, anstatt gemeinsam in monolithischen Modulen zu wohnen. Barrel Exports (index.ts) stellen stabile öffentliche APIs für jedes Verzeichnis bereit, sodass interne Umstrukturierungen keine nachgelagerten Imports brechen. Die Einhaltung des TypeScript Strict Mode wurde verschärft — verbleibende any-Typen wurden durch korrekte Generics oder eingeschränkte Union Types ersetzt.

Die Import-Reihenfolge folgt einer einheitlichen Konvention im gesamten Projekt: zuerst React-Imports, dann Next.js, Drittanbieter-Bibliotheken, @/-Alias-Pfade und schließlich relative Imports. Diese Reihenfolge wird durch ESLint erzwungen und gilt für jede Datei im Projekt.

Der Content Generator stellt strukturierte Templates für häufige Schreibaufgaben bereit — Blog-Posts, Marketing-Texte, Produktbeschreibungen und mehr. Jedes Template definiert einen System-Prompt und ein erwartetes Ausgabeformat, sodass du konsistente Ergebnisse erhältst, ohne selbst Prompt Engineering betreiben zu müssen. Die Ausgabe wird über Server-Sent Events an den Client gestreamt und rendert den Text in Echtzeit, während das Modell ihn generiert.

Credits werden pro Generierung basierend auf der Template-Kategorie abgezogen. Der Provider, der jede Generierung verarbeitet, ist auf Anwendungsebene konfigurierbar — so können Betreiber Anfragen je nach Kosten- und Qualitätsanforderungen an OpenAI, Anthropic, Google oder xAI weiterleiten.

Die Bildgenerierung integriert OpenAIs GPT Image API als vollwertige Funktion. Drei Modellvarianten stehen zur Verfügung — Standard (gpt-image-1), Premium (gpt-image-1.5 mit schnellerer Generierung und besserem Text-Rendering) und Budget (gpt-image-1-mini). Du wählst ein Modell, eine Größe und eine Qualitätsstufe, gibst einen Prompt ein und erhältst innerhalb von Sekunden ein generiertes Bild. Jede Generierung zieht Kredite entsprechend der gewählten Konfiguration ab, wobei höhere Auflösungen und Qualitätsstufen proportional mehr kosten.

Generierte Bilder werden automatisch in Vercel Blob Storage hochgeladen und bleiben so über die Generierungssitzung hinaus erhalten und können später wieder abgerufen werden. Der gesamte Ablauf — Prompt-Übermittlung, API-Aufruf, Speicherung und Kreditabzug — läuft als einzelne Server Action mit ordnungsgemäßer Fehlerbehandlung in jedem Schritt.

Streaming mit einem eigenen SSE-Parser

Chat-Antworten werden über Server-Sent Events gestreamt – mit einem eigens entwickelten Parser, der reale Netzwerkbedingungen berücksichtigt. Eine dedizierte SSEStreamError-Klasse unterscheidet Server-Fehler von JSON-Parse-Fehlern und verhindert das Catch-all-Anti-Pattern, bei dem legitime Fehlerantworten stillschweigend verschluckt werden. Die SSELineBuffer-Klasse behandelt TCP-Paketgrenzentrennung – wenn eine einzelne SSE-Zeile über mehrere reader.read()-Aufrufe hinweg ankommt, setzt der Buffer sie vor dem Parsing wieder zusammen.

Im SSE-Stream eingebettete Server-Fehler (z. B. {"error": "rate limit exceeded"}) erscheinen sofort in der UI, anstatt leere Chat-Bubbles zu erzeugen. Sowohl String- als auch Object-Fehlerformate werden unterstützt.

Zweiphasiges Laden

Der Ladeindikator arbeitet in zwei klar getrennten Phasen. Phase A überbrückt die Zeitspanne zwischen dem Absenden durch den User und dem Anlegen der Assistant-Nachricht durch den Server – unterhalb der User-Nachricht erscheint ein eigenständiger Ladeblock. Phase B beginnt, sobald die Assistant-Nachricht existiert und das Streaming startet: Der Indikator wechselt in einen Inline-Streaming-Indikator innerhalb der Nachrichtenblase. Das verhindert den störenden Aufblitz einer leeren Bubble, den einfache Lader ohne Phasentrennung verursachen.

Audio-Eingabe

Die Sprache-zu-Text-Eingabe nutzt die MediaRecorder API, um Audio direkt im Browser aufzuzeichnen. Aufnahmen werden serverseitig transkribiert und in das Chat-Eingabefeld eingefügt. Die Implementierung verwendet einen Session-Counter (monotoner useRef-Integer) statt einer Boolean-Ref für das asynchrone Abbrechen – das verhindert Race Conditions, wenn sich Aufnahme-Sessions überschneiden und ein veraltetes Promise aus Session N fälschlicherweise in Session N+1 weiterläuft.

Umgebungsbasiertes Umschalten

Der Demo Mode wird über eine einzige Umgebungsvariable aktiviert. Ist er eingeschaltet, ersetzt die Anwendung alle Aufrufe externer Services durch lokale Simulationen — keine Clerk-Keys, keine Datenbankverbindung, kein Payment-Provider nötig. Das gesamte Produkt lässt sich direkt aus einem frischen Clone heraus erkunden.

Die Authentifizierung wird mit einer simulierten Benutzersitzung umgesetzt, die das echte Clerk-User-Objekt widerspiegelt. Geschützte Routen, Rollenprüfungen und Session Guards funktionieren dabei identisch wie in der Produktion. Nutzer sehen realistische Daten für Abonnements, Guthaben, Datei-Uploads und KI-Antworten — ganz ohne Backend-Infrastruktur.

API-Mocking mit MSW

Alle API-Aufrufe im Demo Mode werden von MSW (Mock Service Worker) Handlern im Browser abgefangen. Die Handler decken die gesamte API-Oberfläche ab — Subscription-Status, Credit-Operationen, Datei-Speicherung und gestreamte KI-Antworten. Da das Mocking auf Netzwerkebene stattfindet, verhalten sich Komponenten und Hooks exakt so, als würden sie gegen echte Endpunkte arbeiten.

Das macht den Demo Mode über Sales-Präsentationen hinaus nützlich. Während der lokalen Entwicklung können Mitwirkende an UI-Features arbeiten, ohne externe Services konfigurieren zu müssen. Das Onboarding eines neuen Teammitglieds dauert so Minuten statt Stunden.

Vision-Funktionen

Nutzer können Bilder direkt in den Chat hochladen und erhalten eine Analyse von multimodalen Modellen. Das Bild wird als Base64-kodierter Payload zusammen mit dem Text-Prompt übermittelt, sodass das Modell visuellen Inhalt auswerten kann – Diagramme, Screenshots, Charts, handschriftliche Notizen. Eine separate Vision-API oder eine vorgelagerte Verarbeitungspipeline ist nicht erforderlich.

PDF-Dokumenten-Chat

Der PDF-Chat folgt einer dreistufigen Pipeline: Hochladen, Parsen und Konversation. Dokumente werden serverseitig mit pdf-parse geparst und anschließend in Chunks aufgeteilt, die auf das Kontextfenster des Modells abgestimmt sind. Der aufgeteilte Inhalt wird als Kontext für nachfolgende Chat-Nachrichten eingefügt, sodass Nutzer Fragen zu bestimmten Abschnitten stellen können, ohne die Datei erneut hochzuladen.

Credits werden nach dem Pre-Processing (Parsen und Chunking), aber vor Beginn des Streamings abgezogen. So wird sichergestellt, dass Nutzer nur für erfolgreich verarbeitete Dokumente belastet werden, während Missbrauch durch wiederholte Upload-Versuche verhindert wird.

Turbopack-Kompatibilität

Die pdf-parse-Bibliothek hängt von pdfjs-dist ab, das dynamische Worker-Imports verwendet, die Turbopack's statische Analyse zum Absturz bringen. Ein createRequire-Loader-Modul-Pattern kapselt den nativen require()-Aufruf in einer separaten Datei, die Turbopack ignoriert – so werden Laufzeitfehler vermieden, ohne auf Webpack zurückfallen zu müssen.

Provider-Abstraktion

Die AI-Schicht basiert auf dem Vercel AI SDK v4.3 und kapselt Provider-Unterschiede hinter einer einheitlichen Schnittstelle. Der Wechsel zwischen OpenAI, Anthropic, Google und xAI erfordert nur das Ändern einer einzigen Umgebungsvariable — der Rest der Anwendung bleibt unberührt.

# Switch providers without code changes
AI_PROVIDER=openai    # GPT-5, GPT-4.1, o3, o4-mini
AI_PROVIDER=anthropic # Claude Opus 4.5, Claude Sonnet 4.5, Claude Haiku 4.5
AI_PROVIDER=google    # Gemini 2.5 Pro, Gemini 2.5 Flash, Gemini 3 Flash Preview
AI_PROVIDER=xai       # Grok 4.1 Fast Reasoning

Unterstützung für Reasoning-Modelle

Reasoning-Modelle wie GPT-5 und die o-Serie benötigen eine andere Parameterbehandlung als Standardmodelle. Das System erkennt Reasoning-Modelle automatisch und passt sich entsprechend an — temperature wird übersprungen (diese Modelle ignorieren es) und maxTokens wird auf 16384 erhöht, um sowohl internes Reasoning als auch sichtbare Ausgabe zu ermöglichen. Ohne diese Anpassung verbrauchen Reasoning-Tokens das gesamte Budget und die Antwort kommt leer zurück.

Feature-Flags

Jede AI-Funktion — LLM-Chat, RAG-Chat, Vision, PDF-Analyse — wird durch ein unabhängiges Feature-Flag gesteuert. Das ermöglicht schrittweise Rollouts, A/B-Tests oder das Deaktivieren einzelner Funktionen, ohne andere zu beeinträchtigen. Flags werden sowohl auf UI- als auch auf API-Ebene geprüft, um unautorisierten Zugriff auf deaktivierte Funktionen zu verhindern.

Subscription-Lifecycle via Webhooks

Zahlungen laufen über Lemon Squeezy. Checkout-Sessions werden serverseitig erstellt und leiten Nutzer auf eine gehostete Zahlungsseite weiter. Nach dem Kauf erfolgt die gesamte Subscription-Verwaltung über das Lemon Squeezy Customer Portal — signierte URLs werden bei Bedarf generiert und sind 24 Stunden gültig. Keine eigene Billing-UI, die gepflegt werden muss.

Zehn Webhook-Events decken den vollständigen Subscription-Lifecycle ab. Jeder eingehende Webhook wird vor der Verarbeitung mit SVIX Signaturprüfung verifiziert. Die Events laufen durch einen einzigen Endpoint, der jeden Event-Typ dem entsprechenden Datenbank-Update zuordnet — so bleibt der Subscription-Status konsistent, ohne Polling.

const WEBHOOK_EVENTS = [
  'subscription_created',
  'subscription_updated',
  'subscription_cancelled',
  'subscription_resumed',
  'subscription_expired',
  'subscription_paused',
  'subscription_unpaused',
  'subscription_payment_failed',
  'subscription_payment_success',
  'subscription_payment_recovered',
] as const

Tier-basiertes Pricing

Drei Tiers — Basic, Pro und Enterprise — jeweils mit monatlicher und jährlicher Abrechnungsoption. Die Tier-Konfiguration ordnet Lemon Squeezy Variant-IDs internen Plan-Bezeichnern zu, sodass sich Preisänderungen im Lemon Squeezy Dashboard ohne Code-Anpassungen übertragen.

Das Projekt wurde von einer einzelnen Next.js-Anwendung in ein Turborepo Monorepo mit pnpm Workspaces umstrukturiert. Vor der Migration wurde geteilte Logik (Utilities, UI-Komponenten, E-Mail-Templates) zwischen den Anwendungen per Copy-Paste übertragen. Änderungen mussten manuell dupliziert werden, und Versionsabweichungen waren unvermeidlich.

Nach der Migration lebt geteilter Code in dedizierten Packages mit scoped Exports. Eine Utility-Funktion wird einmal geschrieben und konsistent über alle Anwendungen hinweg importiert:

// Vorher: per Copy-Paste in jede App
import { cn } from '@/lib/utils'

// Nachher: Single Source of Truth
import { cn } from '@nextsaasai/utils'

Das Build-System nutzt Turborepos Task-Graph, um Builds zu parallelisieren und Ergebnisse zu cachen. Geteilte Packages werden zuerst gebaut, anschließend binden die Anwendungen sie als Workspace-Dependencies ein. Die Kundenauslieferung bewahrt die vollständige Monorepo-Struktur – Kunden erhalten dasselbe Workspace-Layout, das auch in der Entwicklung verwendet wird.

Dies ist ein Minor-Version-Bump auf 0.3.0, da die Migration die grundlegende Struktur des Projekts, die Import-Pfade und die Build Pipeline verändert.

Das Boilerplate wird mit neun eingebauten Farbthemen ausgeliefert: default, ocean, forest, sunset, midnight, coral, slate, aurora und crimson. Um das Theme zu wechseln, genügt es, die Umgebungsvariable COLOR_THEME zu setzen – keine Code-Änderungen, kein Rebuild der Komponenten-Dateien.

Jedes Theme definiert seine Farbpalette als CSS Custom Properties, und alle Komponenten verwenden semantische Tailwind-Klassen (bg-primary, text-muted-foreground) statt hartcodierter Farbwerte. Der Dark Mode wird automatisch gehandhabt: Jedes Theme enthält sowohl eine helle als auch eine dunkle Variante, die über die prefers-color-scheme-Media-Query und Tailwinds dark:-Präfix angewendet werden.

Das Boilerplate enthält jetzt eine umfassende Sicherheitsschicht, die jede API-Route schützt. Das Rate Limiting wird über Upstash Redis mit kategoriebasierten Limits gesteuert – Endpunkte mit hohem Upload-Aufkommen haben dabei engere Schwellenwerte als allgemeine API-Aufrufe. Jede Kategorie trackt Anfragen unabhängig über Sliding-Window-Zähler.

Der CORS-Schutz verwendet umgebungsabhängige Origin-Allowlists. In der Entwicklung sind localhost-Origins erlaubt. In der Produktion wird ausschließlich die konfigurierte Domain akzeptiert – keine Wildcards. Alle API-Eingaben durchlaufen eine serverseitige Sanitisierungsschicht, die potenzielle XSS-Payloads mittels Regex-Erkennung herausfiltert, bevor die Daten die Datenbank erreichen oder in Antworten gerendert werden.

Security-Header werden global über die Next.js Middleware angewendet. Das Header-Set umfasst Content-Security-Policy, Strict-Transport-Security, X-Frame-Options, X-Content-Type-Options und Referrer-Policy. Alle API-Route-Eingaben werden vor der Verarbeitung mit Zod-Schemas validiert – das sorgt für Typsicherheit zur Laufzeit an der Grenze zwischen Client und Server.

Jede KI-Operation kostet ab sofort eine definierte Anzahl an Credits. Die Credits werden vor Beginn der Streaming-Antwort abgebucht, sodass Nutzer ihr Kontingent nicht mitten in einer Anfrage überschreiten können. Fehlen ausreichend Credits, wird die Anfrage mit einer klaren Fehlermeldung abgelehnt – noch bevor ein Provider-Aufruf stattfindet.

Jedes Abonnement-Tier erhält ein monatliches Credit-Kontingent, das mit dem Abrechnungszyklus zurückgesetzt wird. Nicht verbrauchte Credits verfallen. Das Kontingent skaliert mit dem Tier und passt sich den erwarteten Nutzungsmustern an – von der leichtgewichtigen Erkundung im Free-Plan bis hin zu hochvolumigen Produktions-Workloads im Enterprise-Bereich.

Die Credit-Kosten pro Operation variieren je nach Modell und Funktion. RAG-Abfragen kosten mehr als einfache Chat-Completions, da sie neben dem LLM-Aufruf auch Embedding-Generierung und Vector-Retrieval beinhalten.

Das Boilerplate wird jetzt mit einer vollständig integrierten RAG-Pipeline ausgeliefert. Du kannst PDF- und Plaintext-Dokumente hochladen, die automatisch in Chunks aufgeteilt, eingebettet und in Pinecone gespeichert werden. Wenn du eine Frage im AI-Chat stellst, führt das System eine semantische Suche im Vector-Index durch, ruft die relevantesten Dokumentenfragmente ab und injiziert sie als Kontext in den LLM-Prompt, bevor eine Antwort generiert wird.

Die Dokumentenverarbeitung verwendet eine Sliding-Window-Chunking-Strategie mit konfigurierbarem Overlap, um den Kontext über Chunk-Grenzen hinweg zu erhalten. Jeder Chunk wird über den konfigurierten Provider eingebettet und zusammen mit Metadaten (Quelldateiname, Seitenzahl, Chunk-Index) gespeichert, sodass Antworten ihre Herkunft zitieren können. Der Retrieval-Schritt bewertet Ergebnisse nach Cosinus-Ähnlichkeit und wendet einen Relevanzschwellenwert an, um das Einschleusen von Rauschen zu vermeiden.

Dies ist ein Minor-Version-Bump, da RAG eine bedeutende neue Funktionsoberfläche darstellt. Es berührt die Upload-API, die Hintergrundverarbeitung, den Vector-Speicher und die Chat-Completion-Pipeline. Die Architektur ist provider-agnostisch: Um Pinecone gegen einen anderen Vector-Store auszutauschen, muss lediglich ein einzelner Adapter geändert werden.

File Uploads werden über Vercel Blob abgewickelt, das edge-verteilten Objektspeicher mit einer unkomplizierten API bereitstellt. Der Upload-Endpunkt validiert MIME-Typen anhand einer Allowlist und prüft Dateigrößenlimits, bevor Dateien in den Storage geschrieben werden. Rate Limiting via Upstash Redis verhindert Missbrauch.

Vercel Blob unterstützt die Konfiguration für EU-Datenhaltung und hält hochgeladene Dateien innerhalb europäischer Infrastruktur, wenn Compliance-Anforderungen dies erfordern. Gespeicherte Dateien werden über Vercels CDN mit automatischen Cache-Headern ausgeliefert, sodass wiederholte Zugriffe nicht den Origin-Server erreichen.

Der E-Mail-Versand nutzt Resend als Transaktions-Provider. Templates werden mit React Email erstellt, was bedeutet, dass das E-Mail-Markup als React-Komponenten mit vollständiger TypeScript-Unterstützung geschrieben wird – keine separate Template-Sprache oder HTML-String-Konkatenation.

Der Zustellungsstatus wird über Resend-Webhooks nachverfolgt und bietet Einblick in Bounces, Beschwerden und erfolgreiche Zustellungen. Eine lokale Vorschau-Route rendert E-Mail-Templates während der Entwicklung im Browser, sodass Layout und Inhalt iteriert werden können, ohne echte Nachrichten zu versenden.

Die Datenbankschicht kombiniert Supabase-verwaltetes PostgreSQL mit Prisma ORM. Prisma generiert TypeScript-Typen direkt aus der Schema-Datei, sodass jede Query zur Compile-Zeit typgeprüft wird. Keine manuellen Typdefinitionen für Datenbankentitäten — das Schema ist die einzige Source of Truth.

Die Entwicklung folgt einem Schema-First-Workflow: Modelle in schema.prisma definieren, Migrations ausführen, und der generierte Client aktualisiert sich automatisch. Server Components fragen die Datenbank direkt ab, ohne eine zwischengeschaltete API-Schicht — das reduziert die Latenz und eliminiert redundante Fetch-Aufrufe. Das Connection Pooling wird von Supabase übernommen, wodurch die Anwendung zustandslos bleibt.

Clerk v6 Integration

Die Authentifizierung verwendet Clerk v6 mit hash-basiertem Routing für Login und Registrierung (/login#, /register#). Dieser Ansatz vermeidet dedizierte Route-Segmente für Auth-Seiten und hält die URL-Struktur sauber. Die Clerk Middleware läuft bei jeder Anfrage und verwendet auth.protect(), um geschützte Routen abzusichern, bevor sie den Handler erreichen.

Routen werden über den Middleware-Matcher in öffentliche und geschützte Segmente aufgeteilt. API-Routen unter /(api|trpc)(.*) sind automatisch geschützt — unauthentifizierte Anfragen erhalten eine 404-Antwort (Clerks Rewrite-Verhalten, nicht der Route Handler). Dashboard-Routen erfordern eine gültige Session. Öffentliche Routen wie Marketing-Seiten und rechtliche Seiten werden ohne Prüfung durchgelassen.

Umgebungsabhängiges Switching

Die Authentifizierungsschicht wechselt basierend auf Umgebungsvariablen zwischen echtem und Test-Modus. In der Entwicklung stellt ein Demo-Modus vorkonfigurierte Test-Zugangsdaten bereit, sodass lokale Iterationen keine aktive Clerk-Instanz erfordern. In der Produktion laufen alle Auth-Flows über Clerks gehostete Komponenten mit Multi-Provider-Unterstützung, MFA und Session-Management.

Warum noch ein Boilerplate

Jedes SaaS-Boilerplate auf dem Markt behauptet, „AI-kompatibel" zu sein. Das Problem: Jede Codebasis ist technisch gesehen AI-kompatibel — diese Hürde ist bedeutungslos. Was keines davon bot, war das Ökosystem: Token-Tracking, kreditbasierte Abrechnung für KI-Operationen, Multi-Provider-Integration mit automatischem Fallback, Dokumentenverarbeitungs-Pipelines oder ein Preismodell, das variable KI-Kosten berücksichtigt.

nextsaas.ai wurde entwickelt, um beide Seiten der KI-Gleichung zu lösen. Erstens ist das Boilerplate selbst darauf ausgelegt, mit KI-Coding-Tools wie Claude Code entwickelt zu werden — mit versionsfixierten Abhängigkeiten, umfassender Dokumentation als KI-Kontext sowie spezialisierten Commands und Agents für die SaaS-Entwicklung. Zweitens liefert es eine vollständige KI-Infrastruktur für Endnutzer: Multi-Provider-Unterstützung, RAG, kreditbasierte Abrechnung und alles, was nötig ist, um KI-Features im Produktionsbetrieb zu betreiben.

Versionsfixierungs-Strategie

Die Stack-Entscheidungen sind bewusst getroffen. Next.js 14 statt 15. Tailwind CSS 3 statt 4. ESLint 8 statt 9. Das ist kein Konservatismus — es ist eine KI-Entwicklungsstrategie. KI-Coding-Tools liefern die besten Ergebnisse, wenn sie umfangreiche Trainingsdaten für die verwendeten Frameworks besitzen. Stabile, gut dokumentierte Versionen mit großer Community-Adoption erzeugen besseren KI-assistierten Code als Bleeding-Edge-Releases mit spärlicher Dokumentation.

Jede Abhängigkeit musste zwei Tests bestehen: Würdest du heute ein zahlungspflichtiges Produkt darauf setzen, und kennt dein KI-Coding-Tool es gut genug, um damit produktionsreifen Code zu schreiben?

Initialer Stack

Next.js 14 mit dem App Router stellt die Routing- und Rendering-Schicht bereit. TypeScript läuft im Strict Mode. Tailwind CSS übernimmt das Styling ohne Laufzeit-Overhead. Prisma in Kombination mit Supabase PostgreSQL ermöglicht typsicheren Datenbankzugriff mit verwalteter Infrastruktur. Clerk übernimmt die Authentifizierung. pnpm hält die Abhängigkeitsinstallation schnell und speichereffizient.