M0 – Setup und Orientierung

Willkommen im Tutorial. Dieses erste Modul ist kein klassischer "Hello World"-Einstieg — es geht darum, dein Rails-Denken mit der Next.js-Welt zu verknüpfen, bevor du eine einzige Zeile Code schreibst. Das Ziel: Du sollst dich im Projekt nicht verlaufen, sondern orientiert fühlen.

Was ist Next.js?

Next.js ist ein React-Framework für Fullstack-Webanwendungen. Das klingt unscheinbar, bedeutet aber: Routing, Datenbankzugriff, Authentifizierung, Caching, API-Endpunkte, Rendering-Strategien — das alles lebt in einem einzigen Projekt. Kein separates Backend, kein getrenntes API, kein fetch zum eigenen Server. Stattdessen gibt es Server Components, die direkt auf die Datenbank zugreifen, und Server Actions, die Formulare verarbeiten — beides ohne einen expliziten API-Layer dazwischen.

Rails und Next.js verfolgen ähnliche Ziele: Sie wollen, dass du produktiv bist, ohne Infrastruktur manuell zusammenzustecken. Der Unterschied liegt im Programmiermodell. Rails ist ein klassisches MVC-Framework — du hast Controller, die Requests entgegennehmen, Models, die mit der Datenbank sprechen, und Views, die HTML rendern. Diese drei Schichten sind klar getrennt und haben klar definierte Aufgaben.

Next.js denkt nicht in diesen Schichten. Es denkt in Komponenten und Rendering-Kontexten. Eine Server Component kann ein Datenbankquery direkt ausführen und das Ergebnis als HTML zurückgeben — das ist gleichzeitig Controller-Logik, Model-Zugriff und View-Rendering. Das klingt chaotisch, ist es aber nicht: Es gibt Konventionen, und diese Konventionen wirst du im Laufe des Tutorials kennenlernen.

Ein wichtiger Punkt vorab: Next.js ist kein reines Frontend-Framework. Wer mit React anfängt, denkt oft an Single-Page-Applications, bei denen alles im Browser läuft. Next.js geht weit darüber hinaus — mit dem App Router (eingeführt in Next.js 13, heute der Standard) wird serverseitiges Rendering zur Grundlage, und clientseitiger Code ist die bewusste Ausnahme.

Das mentale Modell

Bevor du in Dateien schaust, lohnt es sich, die konzeptuellen Entsprechungen zu kennen. Die folgende Tabelle ist eine Orientierungshilfe — keine 1:1-Übersetzung, denn die Abstraktionen sind verschieden. Aber sie zeigt, wo Next.js dieselben Probleme löst wie Rails, nur anders.

Diese Tabelle wird im Verlauf des Tutorials immer konkreter. Jetzt reicht es, sie einmal gelesen zu haben — du kannst sie jederzeit wieder aufrufen.

Projektstruktur

Das Capstone-Projekt dieses Tutorials heißt DevNotes: eine Notiz-App für Entwickler, mit Markdown-Editor, Tagging und Benutzeranmeldung. Das Projekt ist bereits im Repository enthalten. Wenn du dir die Verzeichnisstruktur ansiehst, wirst du folgendes finden:

next-tutorial/
├── app/                   # Alles, was Next.js direkt kennt
│   ├── layout.tsx         # Root-Layout (≈ application.html.erb)
│   ├── page.tsx           # Startseite unter /
│   ├── lernen/            # Dieses Tutorial
│   └── notes/             # Das Capstone DevNotes (ab M4)
├── components/            # Wiederverwendbare React-Komponenten
│   └── tutorial/          # Komponenten nur für das Tutorial
├── lib/                   # Hilfsfunktionen, DB-Client, Auth-Logik
├── prisma/
│   ├── schema.prisma      # Datenbankschema (≈ schema.rb)
│   └── seed.ts            # Testdaten (≈ db/seeds.rb)
├── public/                # Statische Dateien (Bilder, Fonts)
└── middleware.ts          # Läuft vor jeder Route (Auth-Checks etc.)

Das app/-Verzeichnis ist der Kern. In Rails liegt deine Routing-Konfiguration in einer einzigen Datei (routes.rb), und du verweist auf Controller-Actions. In Next.js ist die Verzeichnisstruktur das Routing. Eine Datei unter app/notes/page.tsx ist unter /notes erreichbar — ohne jede zusätzliche Konfiguration.

Das lib/-Verzeichnis ist das freiste — dort landet, was nirgendwo anders hingehört: der Prisma-Client, Utility-Funktionen, Authentifizierungslogik. Rails-Entwickler kennen das aus lib/ und den Concerns. Hier gilt dasselbe Prinzip.

Das components/-Verzeichnis enthält keine Routen, nur UI-Bausteine. Das entspricht am ehesten Partials in Rails Views — wiederverwendbare Schnipsel, die in Seiten eingebettet werden.

Spezialität: layout.tsx

Neben jeder page.tsx kann eine layout.tsx existieren. Dieses Layout umschließt alle Pages im gleichen Verzeichnis und allen Unterverzeichnissen. Das Root-Layout unter app/layout.tsx ist das Äquivalent zu app/views/layouts/application.html.erb: Es enthält das <html>- und <body>-Tag und alles, was auf jeder Seite erscheinen soll — Navigation, Footer, globale Styles.

Layouts können in Next.js verschachtelt werden. Das Root-Layout gilt überall; ein Layout unter app/notes/layout.tsx gilt nur für alle Notes-Seiten. Das ermöglicht feingranulare Kontrolle über das UI, ohne Vererbungshierarchien oder content_for-Blöcke.

Dev-Server

Next.js kommt seit Version 15 mit Turbopack als Standard-Bundler für den Entwicklungsmodus. Turbopack ist der Nachfolger von Webpack — erheblich schneller beim Start und beim Hot Reloading. Du musst dich um die Konfiguration nicht kümmern; npm run dev startet alles automatisch mit Turbopack.

Hot Module Replacement (HMR) bedeutet: Wenn du eine Datei speicherst, aktualisiert der Browser nur den Teil der Seite, der sich geändert hat — ohne einen vollständigen Reload. Der Zustand der Anwendung bleibt erhalten. Das kennst du vielleicht aus der Rails-Entwicklung mit guard-livereload oder ähnlichen Tools, aber HMR geht weiter: Es ersetzt einzelne Komponenten mitten in einer laufenden Seite.

Beim Start siehst du etwas wie:

▲ Next.js 15.x
- Local:        http://localhost:3000
- Environments: .env

✓ Starting...
✓ Ready in 1234ms

Der Server läuft auf Port 3000 — genau wie rails server. Beim ersten Aufruf einer Route kompiliert Turbopack die betroffenen Dateien. Danach sind Änderungen in Millisekunden sichtbar.

Ein wichtiger Unterschied zu Rails: In der Entwicklung gibt es keine "Schicht", die auf Dateiänderungen wartet und neu startet. Der Prozess läuft kontinuierlich; Turbopack beobachtet das Dateisystem und recompiliert inkrementell. Bei Server-Komponenten erscheint die Änderung nach einem Browser-Refresh sofort; bei Client-Komponenten ohne Refresh durch HMR.

# Terminal 1
rails server

# Browser aktualisieren,
# um Änderungen zu sehen
# (oder mit Gem: guard-livereload)

# Terminal 1
npm run dev

# Browser aktualisiert sich
# bei Änderungen automatisch
# dank HMR + Turbopack

Das erste Mal ändern

Öffne die Datei app/page.tsx — das ist die Startseite deines Projekts, die unter http://localhost:3000 erreichbar ist. Irgendwo darin findest du ein Heading, einen <h1>-Tag oder JSX-Code, der den Seitentitel rendert.

Ändere den Text. Speichere die Datei. Schau in den Browser.

Das ist HMR in Aktion: Die Änderung erscheint sofort, ohne Neuladen, ohne Neustart. Dieses Feedback-Loop ist schnell — und wenn du einmal daran gewöhnt bist, willst du es nicht mehr missen.

Was passiert dabei technisch? Turbopack erkennt die Dateiänderung, kompiliert ausschließlich das betroffene Modul neu, und schickt das Update per WebSocket an den Browser. Der Browser tauscht die betroffene Komponente im DOM aus. Der Rest der Seite — Scroll-Position, State, andere Komponenten — bleibt unberührt.

In Next.js-Projekten lebt fast alles in TypeScript (Dateiendung .tsx für Dateien mit JSX, .ts für reines TypeScript). Falls du dich mit TypeScript noch nicht auskennst: Modul M1 gibt dir den nötigen Crashkurs. Für jetzt reicht es zu wissen, dass TypeScript eine Obermenge von JavaScript ist — valides JavaScript ist also auch valides TypeScript.

Im Capstone: DevNotes

Das Capstone-Projekt DevNotes zieht sich durch alle Module. Es ist keine fertige App — du baust es Schritt für Schritt auf. Aber die Grundstruktur ist bereits vorhanden, und die Datenbank enthält nach dem Seeding Testdaten, mit denen du sofort experimentieren kannst.

Um die laufende Anwendung zu erkunden, führe zunächst das Seeding aus:

npm run db:seed

Danach navigiere in deinem Browser zu http://localhost:3000/notes. Dort siehst du eine Liste von Notizen. Noch ist die UI minimal — im Laufe des Tutorials wirst du Routing (M2), Server Components (M3), Datenbankzugriff mit Prisma (M5) und Authentifizierung (M9) hinzufügen, bis DevNotes eine vollständige Anwendung ist.

Für dieses Modul ist es ausreichend, die App zum Laufen zu bringen und die Verzeichnisstruktur zu erkunden. Schau dir app/notes/ an: Welche Dateien existieren dort bereits? Was fehlt noch? Du wirst diese Dateien in späteren Modulen selbst schreiben oder erweitern.

Das Ziel von M0 ist nicht Code — es ist Orientierung. Du weißt jetzt, wo was liegt, wie die Rails-Konzepte in Next.js heißen, und wie du Änderungen siehst, ohne den Server neu zu starten. Damit bist du bereit für M1.