Lektionen aus dem Versand eines Next.js SaaS-Produkts und dem Aufbau einer Scaffolding-CLI

Beim Veröffentlichen eines echten SaaS-Produkts mit React und Next.js geht es weniger darum, eine modische Bibliothek auszuwählen, sondern vielmehr darum, Dutzende kleiner, unscheinbarer Entscheidungen richtig zu treffen, bevor man überhaupt einen Dashboard berührt. Derselbe Disziplinanspruch, der dafür sorgt, dass eine Produktarchitektur auch unter echten Kunden Bestand hält, zeigt sich bereits bei einer so alltäglichen Aufgabe wie dem Aufbau eines neuen Next.js-Projekts – weshalb ein selbst entwickeltes CLI-Tool zur Erstellung von Vorlagen letztendlich dieselbe Lektion vermittelt wie der Aufbau des SaaS-Produkts selbst: Die langweilige Einrichtungsarbeit ist der entscheidende Faktor dafür, ob Projekte erfolgreich sind oder scheitern.

Die Wahl einer Technologiestack, die einen nicht verlangsamt

Nach dem Veröffentlichen mehrerer SaaS-Produkte neigt sich eine Technologiestack in der Regel zu einer vorhersehbaren Struktur entwickelt:

1. Next.js als einheitliches Framework für Routing, Server-Side-Rendering und API-Routen, sodass man nicht mit separaten Tools für jede Aufgabe hantieren muss.

TypeScript – unbedingt, insbesondere dort, wo die Abrechnungslogik liegt; das sind keine Fehler, die man zum Laufzeitpunkt haben möchte.

Tailwind CSS zum Styling, hauptsächlich weil es den ständigen Kampf mit der CSS-Spezifität umgeht.

Redux Toolkit oder Zustand – ausschließlich für Zustände, die tatsächlich global geteilt werden müssen.

Niemand dieser Entscheidungen wird aus Neugier getroffen. Gemeinsam ermöglichen sie einem kleinen Team, schnell voranzukommen, ohne heimlich technischen Schulden aufzubauen, die es niemals schaffen wird, zurückzuzahlen.

Bauen Sie zuerst die unauffälligen Grundlagen

Förderer neigen dazu, direkt mit dem Aufbau von Dashboards zu beginnen. Widerstehen Sie diesem Drang. Bevor etwas für die Benutzer bereitsteht, müssen diese drei Dinge bereits vorhanden sein:

1. Authentifizierung – wird mit echten Sitzungen umgesetzt, nicht nur mit Tokens, die in localStorage abgelegt werden.
2. Mehrfachnutzung – selbst wenn Sie heute nur einen Kunden haben, planen Sie von Anfang an für mehrere Kunden.
3. Buchungshooks – frühzeitige Einrichtung von Stripe-Webhooks vermeidet eine mühsame Neuimplementierung, sobald das Produkt tatsächlich veröffentlicht wird.

Hier ist ein Muster, das es wert ist, übernommen zu werden, um API-Aufrufe im Rahmen verschiedener Kunden ohne Wiederholungen durchzuführen:

// hooks/useTenantFetch.ts
import { useCallback } from "react";
import { useSession } from "next-auth/react";

export function useTenantFetch() {
  const { data: session } = useSession();

  const fetchScoped = useCallback(
    async (endpoint: string, options: RequestInit = {}) => {
      if (!session?.tenantId) throw new Error("No active tenant");

      const res = await fetch(`/api/${session.tenantId}${endpoint}`, {
        ...options,
        headers: {
          ...options.headers,
          "Content-Type": "application/json",
        },
      });

      if (!res.ok) throw new Error(`Request failed: ${res.status}`);
      return res.json();
    },
    [session]
  );

  return { fetchScoped };
}

Es handelt sich um eine kleine Hilfsfunktion, doch sie erspart Ihnen später das Aufteilen von Überprüfungen der Kunden-ID auf Dutzende von Komponenten.

Wissen, was in den globalen Zustand gehört

Nicht jeder Datensatz verdient einen Platz in Redux. Ein Ingenieur, der bei einem von Y Combinator unterstützten Startup arbeitet, drückte es gut aus: Der globale Zustand ist eine Schuld, die im Laufe der Zeit Zinsen anhäuft. Reservieren Sie Redux (oder Ihren gewählten globalen Store) ausschließlich für Dinge, die tatsächlich auf der gesamten Benutzeroberfläche relevant sind – Modale, Feature-Flags, Benutzerpräferenzen – und überlassen Sie React Query oder SWR alles andere, was im Grunde nur versteckte Serverdaten sind.

Mehrere Schlussfolgerungen fassen die Aspekte des SaaS-Entwickelns zusammen:

• Sorgen Sie zuerst für funktionierende Authentifizierung und Abrechnung, bevor Sie in eine ansprechende Benutzeroberfläche investieren.
• TypeScript ist ab dem Moment, in dem Geld im Spiel ist, keine Option mehr.
• Wehren Sie sich dagegen, den Zustand übermäßig zu zentralisieren; die meisten Funktionen gehören zu Tools für Serverzustand, nicht zu einem globalen Store.

Alles das resultiert nicht aus dem Streben nach der neuesten Bibliothek. Es geht um die Grundlagen: Authentifizierung, Nutzungsverträge und Abrechnung müssen frühzeitig geklärt werden, sodass alles Weitere – Wachstum, neue Funktionen, Skalierung – viel einfacher darauf aufgebaut werden kann.

Wenn die Einrichtung selbst zum Engpass wird

Derselbe Instinkt, wiederholende und fehleranfällige Einrichtungsarbeiten zu beseitigen, führt letztendlich dazu, dass auch die Standardschritte automatisiert werden. Jeder Frontend-Entwickler kennt diese Routine: Zuerst wird ein neues Projekt mit create-next-app erstellt, danach beginnt die eigentliche Monotonie. Man erstellt eine components-Ordnerstruktur, trennt ui von features, richtet hooks ein, verbindet gemeinsame types, schreibt Hilfsfunktionen, konfiguriert Pfade und ordnet die Ordnerhierarchie – und schon kann eine Stunde vergehen, ohne dass man auch nur eine einzige Zeile echter Geschäftslogik geschrieben hat.

Nachdem dieses Ritual zu oft durchgeführt wurde, war der natürliche nächste Schritt, es zu automatisieren – was zur Veröffentlichung des ersten Open-Source-npm-Pakets führte: nexarch-cli.

Das zugrundeliegende Problem

Standardmäßige Next.js-Startervorlagen bieten lediglich ein leeres Blatt Papier, keine für die Produktion bereite Architektur. Moderne Anwendungen benötigen in der Regel:

• eine klare Trennung zwischen Präsentationslogik und Geschäftslogik
• eine modulare Gliederung nach Funktionen
• skalierbare Typdefinitionen sowie Hilfsfunktionen
• konsistente Konventionen, denen ein ganzes Team folgen kann

Alles dies von Hand für jedes Prototypprojekt oder Kundenprojekt neu zu erstellen, ist langsam, inhomogen und anfällig für Fehler.

Was nexarch-cli tatsächlich tut

nexarch-cli ist ein interaktives Kommandozeilenwerkzeug, das dazu dient, innerhalb von Sekunden eine saubere, modulare Next.js-Architektur aufzubauen. Anstatt manuell verschachtelte Ordner und Platzhalterdateien erstellen zu müssen, beantworten Sie einige Anfragen in Ihrer Terminalkonsole, und das Werkzeug erstellt für Sie die Grundstruktur.

Zu seinen Hauptfunktionen gehören:

• Interaktives Scaffolden durch einfache Terminalanfragen, die genau auf Ihre Bedürfnisse zugeschnitten sind.
• Modulare Architektur mit vorkonfigurierten Konventionen, die sich mit dem Wachstum der Anwendung skalieren lassen.
• Keine globale Installation erforderlich – es wird auf Anfrage über npx ausgeführt.
• Übereinstimmung mit den aktuellen Next.js- und React-Konventionen, wodurch die Verzeichnisstrukturen mit modernen Praktiken übereinstimmen.

Ausführen

Es ist nicht notwendig, etwas global zu installieren. Sie können es direkt ausführen:

npx nexarch-cli

Sobald Sie die Anfragen beantwortet haben, wird Ihre Projektstruktur erstellt und ist für die eigentliche Entwicklung bereit.

Lektionen aus der Erstellung einer ersten CLI

Die Entwicklung und Veröffentlichung dieses Tools als erstes Entwicklerwerkzeug erforderte eine steile Lernkurve. Einige der wichtigsten Erkenntnisse:

• Die Benutzeroberfläche im Terminal ist genauso wichtig wie der zugrunde liegende Code. Die saubere Handhabung von Prozessbeendigungen, die Darstellung verständlicher Anfragen sowie die Anzeige klarer Fehlermeldungen sind genauso wichtig wie die Logik, die die Dateien erstellt.
• Dateisystemoperationen verbergen viele Randfälle. Die Erstellung rekursiver Verzeichniscreator sowie von Dateivorlagen, die auf verschiedenen Betriebssystemen einheitlich funktionieren, erfordert sorgfältige und wiederholte Tests.

Die Verpackung für npm erfordert eine eigene Lernkurve. Die korrekte Konfiguration der package.json-Binärdateien (bin), die Handhabung von Dateirechten mit chmod sowie das Halten des Abhängigkeitsaufwands nahe bei Null zeigen alle, wie Node-basierte CLI-Tools im Hintergrund funktionieren.

Der aktuelle Stand des Projekts

Das Tool ist weiterhin ein frühes Open-Source-Projekt und profitiert von externen Einflüssen, während es noch weiterentwickelt wird. Der Code befindet sich unter github.com/CaffeineLogs/nexarch-cli, und das veröffentlichte Paket ist im npm-Registry unter dem Namen nexarch-cli zu finden.

Jeder, der eine andere bevorzugte Projektstruktur hat oder auf einen Fall stößt, den das Scaffold derzeit noch nicht gut handhaben kann, ist herzlich eingeladen, dies als Issue im Repository zu melden. Vorschläge für zukünftige Erweiterungen – wie beispielsweise vorgefertigte Styling-Einstellungen oder fertige State-Management-Presets – sind genauso willkommen als Diskussionspunkte oder Kommentare.

Egal, ob Sie entscheiden, was in Redux untergebracht werden soll, oder wie eine neue Next.js-Projektstruktur aussehen sollte: Die Lektion bleibt dieselbe – die teuersten Aspekte eines Projekts wie Authentifizierung, Mietmodell, Abrechnung und Ordnerstruktur sind genau die Bereiche, die zuerst richtig umgesetzt und oft automatisiert werden sollten.