Next.js Einsteiger: Vom leeren Ordner zur Live‑App – mit pnpm, App Router, API und Vercel

Du willst mit React endlich produktiv werden – fragst dich aber: Womit starte ich, ohne mich in Konfigurationsdetails zu verlieren? Warum schwärmen so viele Devs von Frameworks, die Server und Client elegant verbinden? Und wie kommst du von „npm init“ zu einer live erreichbaren App, die schnell lädt und sauber strukturiert ist? Gute Nachrichten: Genau das bekommst du hier – Schritt für Schritt, ohne Schnörkel.

In diesem Guide zeige ich dir den Weg vom leeren Ordner zur ersten Seite, einer kleinen API‑Route und einem Deployment – mit pnpm, dem App Router und ein paar Best Practices, die dir später viel Zeit sparen. Wenn du dich als Next.js Einsteiger wiedererkennst, wirst du nach dieser Lektüre wissen, wie du ein Projekt sauber aufsetzt, den Dev‑Server startest, Daten vom Server holst und deine App mit wenigen klaren Schritten auf Vercel bereitstellst. Kein Overengineering. Keine Abkürzungen, die später wehtun. Nur ein robuster Start, auf dem du aufbauen kannst.

Einführung: Was du als Next.js Einsteiger lernst

Du bekommst einen roten Faden: vom Setup bis zum ersten Deployment. Wir konzentrieren uns auf den App Router (Next.js 13+), eine moderne Projektstruktur, serverseitiges Rendering und eine kleine API‑Route, die du direkt im UI abrufst. Dazu nutzen wir pnpm für schnelle, platzsparende Installationen und arbeiten mit TypeScript – pragmatisch und ohne Ballast. Einmal verstanden, fühlt sich Full‑Stack‑React plötzlich leicht an. Kurz gesagt: Wir zünden dein Next.js‑Mindset.

Ziel und Ergebnis

Ziel ist eine kleine, aber vollständige App: eine Startseite mit eigener Metadata, eine simple GET‑API unter /api/hello und ein Client‑Fetch, der diese Daten anzeigt. Du lernst Hot Reloading kennen, das dich im Flow hält, und bereitest die App so vor, dass das Deployment glatt läuft. Am Ende hast du ein Repo, das du jederzeit erweitern kannst – ob du eine Blogseite, ein kleines Dashboard oder einen Shop‑Prototypen draus machst. Der Clou: Du siehst, wie Server und Client nativ zusammenspielen – ohne zusätzliche Tools.

Was wir benutzen (Node, pnpm, Editor)

Du brauchst Node.js in einer aktuellen LTS‑Version (18+ empfohlen), pnpm als Paketmanager und einen Editor wie VS Code. pnpm punktet mit Geschwindigkeit und effizientem Speichergebrauch. VS Code bietet dir erstklassige TypeScript‑Unterstützung, Formatierung mit Prettier und eine schnelle Terminal‑Integration. Optional: Git für das Repo und ein Vercel‑Account für das Deployment. Mehr brauchst du nicht, um sauber loszulegen.

Voraussetzungen und Projektanlage mit pnpm dlx create-next-app

Bevor du mit dem Coden startest, prüfen wir dein System und legen das Projekt strukturiert an. Ziel: ein frisches Setup in wenigen Befehlen, klare Ordnerstruktur und ein lauffähiger Dev‑Server. Wir nutzen den offiziellen Scaffold‑Befehl, damit alles korrekt verkabelt ist – vom TypeScript‑Support über ESLint bis zu den Standard‑Skripten in der package.json. Das erspart dir später das berühmte „Warum kompiliert das jetzt nicht?“

System-Check: Node.js, pnpm, Editor

Prüfe zuerst deine Versionen: node -v sollte 18 oder höher zeigen. Wenn pnpm noch fehlt, installierst du es mit npm install -g pnpm. Ein flotter Test mit pnpm -v gibt dir die Versionsnummer aus. Öffne danach deinen Editor und stelle sicher, dass die TypeScript‑Erweiterungen aktiv sind. Tipp: Aktiviere Format on Save in VS Code, um saubere Commits zu fördern. Für Einsteiger lohnt außerdem die Installation der offiziellen ESLint‑ und Prettier‑Extensions.

Weitere Infos findest du in der Next.js‑Dokumentation (nextjs.org), bei pnpm (pnpm.io) und natürlich bei Node.js (nodejs.org).

Schritt-für-Schritt: create-next-app mit pnpm

So legst du dein Projekt an – knapp, nachvollziehbar und wiederholbar:

• Wechsle in deinen Arbeitsordner und starte: pnpm dlx create-next-app@latest
• Wähle einen Projektnamen, aktiviere TypeScript und App Router und lass ESLint aktiv.
• Entscheide dich für eine Styling‑Option (z. B. CSS Modules); Tailwind kannst du später hinzufügen.
• Wechsle ins Projektverzeichnis, installiere Abhängigkeiten mit pnpm install und teste pnpm dev.
• Öffne http://localhost:3000 im Browser – die Startseite sollte laufen, Hot Reload inklusive.

Pro‑Tipp: Committe direkt die frische Basis (git init, erster Commit). So kannst du jeden Schritt versionieren und bei Bedarf zurückspringen. Sauberer Start, sauberes Wachstum.

Next.js Projektstruktur einfach erklärt (App Router)

Die Projektstruktur entscheidet, wie verständlich und wartbar dein Code ist. Der App Router in Next.js 13+ strukturiert Seiten, Layouts und Routen durch Ordner – klar, konsistent, skalierbar. Du arbeitest vor allem im app/‑Verzeichnis, in dem jede Ordner‑Ebene eine Route repräsentiert. Das nimmt dir Router‑Boilerplate ab und lässt dich featureorientiert denken: Ordner sind Features, nicht nur „Views“.

App Router vs Pages Router (kurz)

Der klassische Pages Router (pages/) basiert auf Dateien wie pages/index.tsx. Der App Router (app/) erlaubt pro Route eigene Layouts, Server Components als Standard und moderne Daten‑Fetching‑Muster. Ergebnis: weniger Client‑JavaScript und bessere Performance out of the box. Wenn du neu startest, nimm den App Router – er ist die offizielle Empfehlung und die Zukunft von Next.js. Detailwissen kannst du später vertiefen; wichtig ist: app/ ist dein Dreh‑ und Angelpunkt. Die offizielle Einführung erklärt die Konzepte präzise und aktuell (Next.js Docs).

Ordner & Dateien im Überblick

Ein typisches App‑Router‑Projekt wirkt anfangs ungewohnt. Diese Übersicht hilft dir, die wichtigsten Elemente zu verorten:

Zur Visualisierung kann ein einfaches Strukturdiagramm helfen – du musst es nicht auswendig lernen, aber einmal „gesehen“ prägt es sich besser ein.

Merke: Jede Ordner‑Ebene unter app/ wird zur Route; page.tsx rendert Inhalt, layout.tsx definiert das Umfeld. API‑Routen leben ebenfalls unter app/api – konsistent, nah am Feature. Klarheit ist ein Performance‑Feature.

Einstieg in Next.js: erste Seite und API-Route

Jetzt wird’s konkret: Wir schreiben eine Startseite, ergänzen Metadata und bauen eine kleine API‑Route. Danach holen wir die Daten in einer Client‑Komponente ab. So durchschaust du den kompletten Weg – von Server bis UI – anhand eines greifbaren Beispiels. Kleine Schritte, große Wirkung.

Hello-World: Inhalt und Metadata

Öffne app/page.tsx und ersetze den Inhalt durch eine minimalistische Server Component:

// app/page.tsx
export const metadata = {
  title: "Hello Next.js",
  description: "Erste Seite mit App Router",
};
 
export default function Home() {
  return (
    <main style={{ padding: 24 }}>
      <h1>Hallo Next.js</h1>
      <p>Willkommen in deinem neuen Projekt – schnell, modern, typisiert.</p>
    </main>
  );
}

Metadata steuert den deiner Seite – Titel, Description und mehr. Im App Router definierst du das pro Route oder global im Layout. Für Styles kannst du wahlweise CSS Modules nutzen, z. B. styles/Home.module.css, und in deiner Komponente importieren. Für einen schlanken Start reicht Inline‑Styling völlig aus; später lagerst du es aus.

API-Route & Client-Fetch

So erstellst du die API und bringst die Daten ins UI:

• Lege app/api/hello/route.ts an und definiere eine GET‑Funktion.
• Erzeuge eine Client‑Komponente, die die API aufruft.
• Nutze fetch in useEffect oder React Query – fürs Beispiel reicht fetch.
• Baue Loading‑ und Error‑Zustände ein, damit das UI robust bleibt.
• Rendere das Ergebnis auf der Startseite.

Code für die API:

// app/api/hello/route.ts
import { NextResponse } from 'next/server';
 
export async function GET() {
  return NextResponse.json({ message: 'Hello from the API', time: Date.now() });
}

Client‑Komponente (z. B. app/components/HelloClient.tsx):

'use client';
import { useEffect, useState } from 'react';
 
export default function HelloClient() {
  const [data, setData] = useState<{ message: string; time: number } | null>(null);
  const [error, setError] = useState<string | null>(null);
 
  useEffect(() => {
    fetch('/api/hello')
      .then((r) => r.json())
      .then(setData)
      .catch(() => setError('Konnte Daten nicht laden'));
  }, []);
 
  if (error) return <p style={{ color: 'crimson' }}>{error}</p>;
  if (!data) return <p>Lade Daten…</p>;
  return <p>{data.message} – {new Date(data.time).toLocaleTimeString()}</p>;
}

Und in app/page.tsx einbinden:

import HelloClient from './components/HelloClient';
 
export default function Home() {
  return (
    <main style={{ padding: 24 }}>
      <h1>Hallo Next.js</h1>
      <HelloClient />
    </main>
  );
}

Mit diesem Muster hast du „Full Stack in klein“ – und genau das beschleunigt deinen Start als Next.js Einsteiger enorm.

Next.js Dev-Server starten, lokal testen und auf Vercel deployen

Lokales Iterieren und schnelles Deployment sind dein Turbo. Du startest den Dev‑Server, testest Hot Reload und bringst dein Projekt anschließend nahtlos auf Vercel. So entsteht ein Flow: bauen, prüfen, veröffentlichen. Kein Kontextwechsel, keine Reibung.

pnpm dev: Start, URLs und Hot Reload

Starte den Server mit pnpm dev. Standardmäßig läuft deine App unter http://localhost:3000. Ändere eine Zeile in page.tsx und beobachte, wie das UI ohne manuellen Reload aktualisiert. Fehler bekommst du mit hilfreichen Stacktraces direkt im Terminal oder im Browser‑Overlay – das hilft beim schnellen Fixen.

Tipp: Wenn Hot Reload hakt, lösche den .next/‑Ordner und starte neu. Oft reicht auch ein pnpm install nach Paketänderungen.

Kleine Fallstricke: Achte auf korrekte Dateinamen (route.ts statt routes.ts) und prüfe, ob deine Client‑Komponenten mit ‘use client’ beginnen, wenn sie Browser‑APIs nutzen. Missverständnisse bei Server vs. Client führen häufig zu Fehlermeldungen – aber genau diese klare Trennung macht Next.js so effizient.

Deploy auf Vercel: Repo, Env, Domains

Für das Deployment verbindest du dein Git‑Repo mit Vercel. Ein Push in den main‑Branch löst automatisch einen Build aus; Previews bekommst du pro Pull Request. Für Umgebungsvariablen nutzt du das Vercel‑Dashboard, das die Variablen pro Umgebung (Development/Preview/Production) verwaltet. Domains kannst du direkt zuweisen oder eigene konfigurieren. Die Plattform ist eng mit Next.js verzahnt – Image Optimization, Edge‑Funktionen und ISR funktionieren ohne Extra‑Setup. Eine schnelle Übersicht bietet die Vercel‑Dokumentation (vercel.com).

Mini‑Case: Eine Lerngruppe hat das obige Setup an einem Abend umgesetzt. Ergebnis: In 35 Minuten stand die Startseite, nach 15 weiteren Minuten lief die API‑Route, und eine Stunde später war die App online. Besonders angenehm: Jeder Commit erzeugte automatisch eine Vorschau‑URL – Review wurde vom „lästig“ zum „klick und check“. Kurze Feedback‑Loops, schnelle Fortschritte. Oder anders: Geschwindigkeit ist das neue UX – auch im Team.

Mit diesem Ende‑zu‑Ende‑Pfad hast du alles: Setup, Struktur, Seite, API, lokales Testen und das Live‑Deployment. Jetzt darfst du wachsen – Feature für Feature, Route für Route. Und du weißt: Du baust auf einer stabilen Basis.

Karwl

Hey, ich bin Karwl und das ist mein Blog. Ich liebe alles zu den Themen 🌱 Garten & Pflanzen, 🤖 KI & Tech, 🌐 Web & Coding und würde mich freuen, wenn du hier öfters mal vorbei schaust.