scaffold-nextjs-app

pjt222

Aktualisiert 2 days ago

5 Ansichten

Designai

Über

Diese Fähigkeit erstellt ein neues Next.js-Anwendungsgerüst unter Verwendung des App-Routers mit TypeScript, ESLint und optional Tailwind CSS. Sie richtet die Projektstruktur, Routing-Konventionen, Umgebungsvariablen ein und überprüft die lokale Entwicklungsumgebung. Nutzen Sie sie, um ein modernes Next.js-Projekt zu starten oder eine bestehende Pages-Router-App zum App-Router zu migrieren.

Schnellinstallation

Claude Code

Dokumentation

name: scaffold-nextjs-app description: > Next.js-Anwendung mit App Router, TypeScript, ESLint und optionalem Tailwind CSS erstellen. Behandelt Projektstruktur, Routing-Konventionen, Umgebungsvariablen und lokale Entwicklungsverifikation. Verwenden, wenn ein neues Next.js-Projekt mit modernen Konventionen gestartet wird oder eine bestehende Pages-Router-App auf App Router migriert werden soll. license: MIT locale: de source_locale: en source_commit: 6f65f316 translator: claude-opus-4-6 translation_date: 2026-03-16 allowed-tools: Read Write Edit Bash Grep Glob metadata: author: Philipp Thoss version: "1.0" domain: web-dev complexity: basic language: TypeScript tags: nextjs, react, typescript, app-router, web-dev

Next.js-App scaffolden

Eine neue Next.js-Anwendung mit App Router, TypeScript und modernen Konventionen scaffolden, bereit für die Entwicklung.

Wann verwenden

Start eines neuen Next.js-Projekts mit modernen Konventionen
Migration einer bestehenden Pages-Router-App auf App Router
Einrichten eines standardisierten Next.js-Projekts für ein Team
Schnelles Prototypen einer React-Web-App

Eingaben

Erforderlich: Projektname (z. B. my-app)
Optional: Paketmanager (npm, yarn, pnpm — Standard: npm)
Optional: Ob Tailwind CSS eingebunden werden soll (Standard: ja)
Optional: Quellverzeichnis (src/-Layout — Standard: ja)

Vorgehensweise

Schritt 1: Next.js-Projekt erstellen

Das offizielle Create-Next-App-Tool ausführen.

npx create-next-app@latest my-app \
  --typescript \
  --eslint \
  --tailwind \
  --src-dir \
  --app \
  --import-alias "@/*"

Wenn interaktive Prompts erscheinen:

TypeScript: Yes
ESLint: Yes
Tailwind CSS: Yes (wenn gewünscht)
src/-Verzeichnis: Yes
App Router: Yes
Import-Alias: @/* (Standard)

Erwartet: Projektverzeichnis my-app/ mit vollständiger Struktur erstellt. Keine Fehler während der Installation.

Bei Fehler: Wenn npx nicht verfügbar ist, Node.js (>= 18) installieren. Wenn Netzwerkfehler auftreten, erneut versuchen oder --use-npm explizit angeben.

Schritt 2: Projektstruktur überprüfen

Sicherstellen, dass das Scaffold die erwartete App-Router-Struktur erzeugt hat.

my-app/
├── src/
│   └── app/
│       ├── layout.tsx       # Root-Layout (erforderlich)
│       ├── page.tsx         # Startseite (/)
│       ├── globals.css      # Globale Stile
│       └── favicon.ico
├── public/                  # Statische Assets
├── next.config.js           # Next.js-Konfiguration
├── tailwind.config.ts       # Tailwind-Konfiguration (wenn aktiviert)
├── tsconfig.json            # TypeScript-Konfiguration
├── package.json
└── .eslintrc.json

Erwartet: Alle aufgelisteten Dateien vorhanden. src/app/layout.tsx enthält Root-RootLayout-Komponente mit HTML- und Body-Tags.

Bei Fehler: Wenn das src/-Verzeichnis fehlt, wurde --src-dir möglicherweise nicht gesetzt. Manuell src/app/ erstellen und Dateien dorthin verschieben.

Schritt 3: Root-Layout und Metadaten konfigurieren

src/app/layout.tsx mit geeignetem Titel und Metadaten aktualisieren.

// src/app/layout.tsx
import type { Metadata } from 'next'
import { Inter } from 'next/font/google'
import './globals.css'

const inter = Inter({ subsets: ['latin'] })

export const metadata: Metadata = {
  title: 'My App',
  description: 'Generated by create next app',
}

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body className={inter.className}>{children}</body>
    </html>
  )
}

Erwartet: Layout kompiliert ohne TypeScript-Fehler. Metadaten-Objekt hat title und description.

Bei Fehler: Wenn Font-Imports fehlschlagen, die Font-Importe entfernen und zu Standard-System-Fonts wechseln: <body className="font-sans">.

Schritt 4: Startseite einrichten

src/app/page.tsx durch eine saubere Startseite ersetzen.

// src/app/page.tsx
export default function Home() {
  return (
    <main className="flex min-h-screen flex-col items-center justify-center p-24">
      <h1 className="text-4xl font-bold">Welcome to My App</h1>
      <p className="mt-4 text-lg text-gray-600">
        Get started by editing{' '}
        <code className="font-mono text-blue-600">src/app/page.tsx</code>
      </p>
    </main>
  )
}

Erwartet: Seite rendert ohne Fehler. Tailwind-Klassen werden angewendet (wenn Tailwind aktiviert ist).

Bei Fehler: Wenn Tailwind-Klassen nicht angewendet werden, tailwind.config.ts überprüfen — content-Array muss ./src/**/*.{ts,tsx} enthalten.

Schritt 5: Umgebungsvariablen konfigurieren

Umgebungsvariablen-Dateien für verschiedene Umgebungen erstellen.

# .env.local — lokale Entwicklung (git-ignoriert)
NEXT_PUBLIC_API_URL=http://localhost:3001

# .env.example — Template (ins Repository einchecken)
NEXT_PUBLIC_API_URL=https://api.example.com

.gitignore aktualisieren:

# Umgebungsvariablen
.env.local
.env.*.local

Next.js-Konventionen für Umgebungsvariablen:

NEXT_PUBLIC_* — im Browser zugänglich
Kein Präfix — nur serverseitig

Erwartet: .env.local existiert (git-ignoriert). .env.example ist eingecheckt als Dokumentation.

Bei Fehler: Wenn Variablen im Browser undefiniert sind, sicherstellen, dass sie mit NEXT_PUBLIC_ beginnen und der Entwicklungsserver neu gestartet wurde.

Schritt 6: Entwicklungsserver verifizieren

Den Entwicklungsserver starten und prüfen, ob er läuft.

cd my-app
npm run dev

Erwartete Ausgabe:

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

✓ Ready in Xms

# In einem separaten Terminal verifizieren
curl -s -o /dev/null -w "%{http_code}" http://localhost:3000
# Erwartet: 200

Erwartet: Server startet auf Port 3000. HTTP 200 auf Startseite. Keine Kompilierungsfehler.

Bei Fehler: Wenn Port 3000 belegt ist, mit npm run dev -- --port 3001 starten. Wenn TypeScript-Fehler auftreten, tsconfig.json überprüfen — strict: true erfordert explizite Typen überall.

Schritt 7: Seitenrouting testen

Zusätzliche Routen erstellen, um das App-Router-System zu verifizieren.

// src/app/about/page.tsx
export default function About() {
  return (
    <main className="p-24">
      <h1 className="text-4xl font-bold">About</h1>
      <p className="mt-4">About page content here.</p>
    </main>
  )
}

curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/about
# Erwartet: 200

Erwartet: /about-Route gibt HTTP 200 zurück und rendert Seiteninhalt.

Bei Fehler: Wenn 404 erscheint, sicherstellen, dass die Datei unter src/app/about/page.tsx (nicht src/app/about.tsx) liegt — App Router erfordert page.tsx in Verzeichnissen.

Validierung

Projektverzeichnis mit vollständiger App-Router-Struktur existiert
src/app/layout.tsx mit Root-Layout-Komponente vorhanden
src/app/page.tsx ohne TypeScript-Fehler
Entwicklungsserver startet und gibt HTTP 200 zurück
Tailwind CSS-Klassen werden angewendet (wenn aktiviert)
Umgebungsvariablen-Template (.env.example) ins Repository eingecheckt
Zusätzliche Routen als Verzeichnisse mit page.tsx funktionieren

Haeufige Stolperfallen

Pages Router vs App Router: App Router verwendet Verzeichnisse mit page.tsx; Pages Router verwendet pages/-Verzeichnis direkt. Nicht mischen.
Client vs Server Components: Standardmäßig sind alle Komponenten Server Components. Für Hooks (useState, useEffect) 'use client' am Anfang der Datei hinzufügen.
NEXT_PUBLIC_-Präfix: Ohne dieses Präfix sind Umgebungsvariablen auf dem Server undefiniert, wenn clientseitig zugegriffen wird.
Import-Alias: @/* wird auf src/ aufgelöst. @/components/Button importiert aus src/components/Button.tsx.
Großschreibung von Routennamen: Next.js-Routen spiegeln die Verzeichnisstruktur wider (lowercase wird empfohlen). /About und /about sind identisch in production, aber nicht in development auf case-sensitiven Dateisystemen.
Font-Optimierung: next/font optimiert automatisch Fonts. Direkte <link>-Tags für Google Fonts vermeiden.

GitHub Repository

pjt222/agent-almanac

Pfad: i18n/de/skills/scaffold-nextjs-app

agentsagentskillsai-assisted-developmentclaude-codeskillsteams