Der TypeScript-Stack ist in Layer-Plugins aufgeteilt

Im Oktober wurden die Java-Stacks in Layer-Plugins aufgeteilt. Jetzt folgt der TypeScript-Stack: Aus dem kombinierten Plugin aiup-nestjs-nextjs werden drei Layer-Plugins, aiup-drizzle, aiup-nestjs und aiup-nextjs. Sie brauchen aiup-core 3.14.0 oder neuer.

Warum der Stack aufgeteilt wird #

aiup-nestjs-nextjs hat ein NestJS-Backend mit Drizzle und ein Next.js-Frontend mit einem einzigen Befehl /implement gebaut. Das funktioniert, solange ein Projekt genau diese Kombination verwendet. Viele TypeScript-Projekte tun das aber nicht. Das eine ist ein NestJS-REST-API ohne UI. Das andere hat ein Next.js-Frontend auf einem bestehenden Spring-Boot-Backend.

Mit Layer-Plugins nimmt jedes Projekt nur die Schichten, die es hat. Und TypeScript-Projekte funktionieren jetzt gleich wie Java-Projekte: /stack, /use-case-implement, /use-case-test und /use-case-coverage.

Die drei Plugins #

• aiup-drizzle für die Migrations- und Persistenzschicht: /drizzle-schema schreibt das Drizzle-Schema aus dem Entitätsmodell und generiert die PostgreSQL-Migrationen, /drizzle-persistence schreibt die Repositories, und /drizzle-persistence-test testet sie gegen PostgreSQL in Testcontainers.
• aiup-nestjs für die Service- und API-Schicht: /nest-service setzt die Geschäftsregeln mit Domain-Fehlern um, /nest-rest schreibt die Controller mit validierten DTOs und Problem Details, und /nest-service-test und /nest-rest-test testen sie gegen eine echte Datenbank.
• aiup-nextjs für die UI-Schicht: /nextjs-ui baut die App-Router-Seiten und Komponenten auf dem REST-API auf, und /nextjs-ui-test schreibt Komponententests mit Vitest und React Testing Library.

Die End-to-End-Tests kommen wie bei jedem anderen Web-UI von aiup-playwright. Es startet jetzt Frontend und API zusammen.

Zwei Regeln, die man kennen sollte #

Migrationen werden generiert, nie von Hand geschrieben. /drizzle-schema ändert die Schema-Datei und führt drizzle-kit generate aus. Eine handgeschriebene Migration würde das Journal zerstören, aus dem Drizzle die nächste Migration berechnet. Deshalb steht der Marker einer Geschäftsregel in der Schema-Datei, nicht im SQL.

Next.js ist ein Client des API. In diesem Stack spricht Next.js nur über HTTP mit dem Backend. Auch Server Components und Server Actions gehen über das API, nie direkt auf die Datenbank. Ein Projekt mit aiup-nextjs hat deshalb immer eine API-Schicht, entweder /nest-rest oder /spring-rest. Die Vertragstypen werden Feld für Feld aus den DTOs dieser Schicht geschrieben, und der JSON-Vertrag zwischen beiden wird nach jeder Implementierung geprüft.

Kombinationen #

• REST-API mit NestJS und Drizzle: aiup-drizzle, aiup-nestjs
• Next.js, NestJS und Drizzle: aiup-drizzle, aiup-nestjs, aiup-nextjs, aiup-playwright
• Next.js auf Spring Boot mit JPA: aiup-flyway, aiup-jpa, aiup-spring-boot, aiup-nextjs, aiup-playwright

In allen drei Fällen wird ein Use Case einmal getestet, in der API-Schicht. /stack erkennt NestJS, Next.js und Drizzle aus package.json und dem Quellcode und hält die Kombination in docs/architecture/stack.md fest.

Umstellen #

aiup-nestjs-nextjs ist deprecated und wird mit aiup-core 4.0.0 entfernt, zusammen mit aiup-vaadin-jooq und aiup-angular-jpa. Code, Tests und alles unter docs/ bleiben, wie sie sind. So stellt man ein Projekt um:

• aiup-nestjs-nextjs deinstallieren und aiup-core 3.14.0 oder neuer mit aiup-drizzle, aiup-nestjs, aiup-nextjs und aiup-playwright installieren. Nie beide Formen im selben Projekt behalten.
• Einmal /stack ausführen, damit docs/architecture/stack.md entsteht.
• /use-case-implement statt /implement verwenden, und /use-case-test statt der einzelnen Testbefehle.
• Die Tests behalten die Use-Case-ID in describe('UC-XXX: …'). Dort ändert sich nichts.

Die Details stehen unter Bestehendes Projekt umstellen.

Danke an den Contributor, der das ursprüngliche Plugin aiup-nestjs-nextjs geschrieben hat. Die neuen Layer-Skills bauen auf dieser Arbeit auf. Feedback ist sehr willkommen: ein Issue im Marketplace-Repository eröffnen oder Kontakt aufnehmen.