Agent-almanac scaffold-nextjs-app

install

source · Clone the upstream repo

git clone https://github.com/pjt222/agent-almanac

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/pjt222/agent-almanac "$T" && mkdir -p ~/.claude/skills && cp -r "$T/i18n/de/skills/scaffold-nextjs-app" ~/.claude/skills/pjt222-agent-almanac-scaffold-nextjs-app-d503bc && rm -rf "$T"

manifest: i18n/de/skills/scaffold-nextjs-app/SKILL.md

source content

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.