Next.js Engineering-Setup: ESLint + Prettier + Husky in einem Rutsch

Der Albtraum am Freitagabend

Erinnern Sie sich noch an letzten Freitagabend? Ich wollte gerade den Rechner zuklappen und nach Hause – dann pingte Slack: Der Tech Lead schrieb, mein PR habe zu viele Formatprobleme, ich solle erst aufräumen und erneut einreichen. Auf GitHub: rote Diffs überall, mal doppelte Anführungszeichen, mal uneinheitliche Einrückung.

Ehrlich gesagt fühlte sich das ziemlich hilflos an. Ich war sicher, vor dem Push npm run lint gelaufen zu sein – warum trotzdem Ärger? Peinlicher: Ein Kollege hatte dasselbe. Seine Logik war in Ordnung, nur das Format wich von meinem ab – beim Merge gab es einen Haufen sinnloser Konflikte.

Kennen Sie das? Der Code ist gut, aber in der PR-Review dreht sich alles um Format – Zeitverschwendung für alle. Damals dachte ich: Gibt es eine dauerhafte Lösung, die die Routine der Maschine übernimmt?

Ja: die Kombination ESLint + Prettier + Husky.

Warum brauchen Sie diese drei Tools?

Am Anfang klangen mir die drei Namen auch nach viel Aufwand. Nach ein paar Wochen will ich sie nicht mehr missen. Kurz, was jedes Tool bringt.

ESLint: Wächter der Codequalität

Viele halten ESLint nur für Format-Checks. Wichtiger ist: potenzielle Probleme früh erkennen.

Beispiel: Next.js empfiehlt <Image> statt HTML-<img> wegen automatischer Optimierung. Schreiben Sie versehentlich <img>, meldet ESLint sofort:

Error: Do not use <img>. Use Image from 'next/image' instead.

So vermeiden Sie Performance-Fallen schon in der Entwicklung – effizienter als nach dem Go-Live Bilder nachzubessern.

Next.js 15 aktiviert ESLint standardmäßig; mit der richtigen Konfiguration nutzen Sie es voll aus.

Prettier: Die Format-Lösung

ESLint kümmert sich um Logik und Qualität, Prettier um einheitliches Layout. Die Rollen sollten Sie nicht vermischen.

Früher stritten wir im Team über Einzelheiten: einfache vs. doppelte Anführungszeichen, 2 vs. 4 Leerzeichen Einrückung. In jedem Code Review ging es um Nebensächliches.

Mit Prettier ist das vorbei. Einmal Regeln festlegen (z. B. einfache Anführungszeichen, 2 Leerzeichen) – danach formatiert Prettier alles automatisch. Einmal konfigurieren, dauerhaft profitieren.

Husky: Der Automatisierungs-Hebel

Die besten Tools nützen wenig, wenn niemand sie vor dem Commit ausführt.

Mir ist das mehrfach passiert: lokal kein npm run lint, Push, CI rot – Deployment für das ganze Team blockiert. Das möchte ich nicht noch einmal erleben.

Husky führt Checks vor jedem Commit aus. Im Git-pre-commit-Hook laufen ESLint und Prettier; nur bei konformem Code geht der Commit durch.

Mit lint-staged prüft Husky nur geänderte Dateien, keinen Full-Scan – schnell genug für den Alltag. Der Hook bremst die Entwicklung normalerweise nicht aus.

Zusammenspiel der drei Tools

Typischer Ablauf:

1. ESLint – Qualitätsregeln (z. B. kein var, nur const/let)
2. Prettier – einheitliches Format (z. B. einfache Anführungszeichen überall)
3. Husky – vor dem Commit automatisch beides ausführen

Für das Team:

• PR-Reviews fokussieren auf Logik, nicht auf Anführungszeichen
• weniger Merge-Konflikte durch einheitliches Format
• weniger CI-Fails, weil lokal schon geprüft wurde

Kompletter Konfigurationsablauf

Jetzt die Praxis – Schritt für Schritt, mit typischen Stolpersteinen.

Schritt 1: Next.js-Projekt initialisieren

Bestehendes Projekt? Überspringen. Neu:

npx create-next-app@latest my-app
cd my-app

Beim Erzeugen TypeScript und ESLint wählen. Next.js 15 schaltet ESLint standardmäßig ein – das spart Arbeit.

Schritt 2: Abhängigkeiten installieren

pnpm add -D eslint eslint-config-next prettier eslint-config-prettier husky lint-staged

(pnpm hier; npm oder yarn geht ebenso.)

Kurz die Pakete:

• eslint – ESLint-Kern
• eslint-config-next – offizielle Next.js-Regeln
• prettier – Prettier-Kern
• eslint-config-prettier – schaltet ESLint-Formatregeln ab, die mit Prettier kollidieren
• husky – Git-Hooks
• lint-staged – nur gestagte Dateien

Hinweis: eslint-plugin-prettier weglassen. Viele Tutorials empfehlen es, aber Prettier als ESLint-Regel kostet Performance. ESLint und Prettier getrennt ausführen ist der richtige Weg.

Schritt 3: ESLint konfigurieren

Hier passieren die meisten Fehler – besonders nach dem Upgrade auf Next.js 15 und ESLint 9 mit neuem Config-Format.

ESLint 9 Flat Config (empfohlen)

Im Projektroot eslint.config.mjs:

// eslint.config.mjs
import { FlatCompat } from '@eslint/eslintrc';
import nextPlugin from '@next/eslint-plugin-next';

const compat = new FlatCompat();

export default [
  ...compat.extends('next/core-web-vitals'),
  {
    plugins: {
      '@next/next': nextPlugin,
    },
    rules: {
      '@next/next/no-img-element': 'error',
      'react/no-unescaped-entities': 'off',
      // Hier eigene Regeln ergänzen
    },
  },
  {
    ignores: ['.next/', 'node_modules/', 'out/'],
  },
];

Wichtig:

• ESLint 9 nutzt kein .eslintrc.json mehr, sondern Flat Config (eslint.config.mjs)
• Fehler „The Next.js plugin was not detected“ nach Next.js 15? Meist falsches Format
• Next.js 16 entfernt next lint – früh auf Flat Config umstellen lohnt sich

Fallback bei Kompatibilitätsproblemen

Vorübergehend ESLint-8-Format:

ESLINT_USE_FLAT_CONFIG=false

Dann weiter .eslintrc.json:

{
  "extends": ["next/core-web-vitals", "prettier"],
  "rules": {
    "@next/next/no-img-element": "error"
  }
}

Langfristig trotzdem auf Flat Config migrieren.

Schritt 4: Prettier konfigurieren

.prettierrc.json im Root:

{
  "semi": true,
  "singleQuote": true,
  "trailingComma": "es5",
  "tabWidth": 2,
  "printWidth": 80,
  "arrowParens": "avoid"
}

Anpassbar nach Teamgeschmack:

• singleQuote: true – kompakter Look
• printWidth: 80 – gut für nebeneinander liegende Editor-Fenster
• trailingComma: 'es5' – sauberere Git-Diffs bei letzten Einträgen

.prettierignore:

.next
out
node_modules
public
*.lock

VSCode-Integration (optional, empfohlen)

.vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode"
}

Bei Ctrl + S formatiert Prettier automatisch – sehr angenehm im Alltag.

Schritt 5: Husky + lint-staged

Der Kern für Team-Effizienz.

Husky initialisieren

pnpm dlx husky init

Erzeugt .husky/ und trägt in package.json ein:

{
  "scripts": {
    "prepare": "husky install"
  }
}

prepare läuft bei pnpm install – neue Kolleginnen und Kollegen bekommen Hooks ohne Extra-Schritte nach dem Klonen.

pre-commit-Hook

.husky/pre-commit:

pnpm lint-staged

Bei jedem git commit zuerst pnpm lint-staged.

lint-staged

.lintstagedrc.mjs im Root:

export default {
  '*.{js,jsx,ts,tsx}': [
    'eslint --fix',
    'prettier --write',
  ],
  '*.{json,md,css}': [
    'prettier --write',
  ],
};

Bedeutung:

• JS/TS: zuerst eslint --fix, dann prettier --write
• JSON/MD/CSS: nur Prettier

Performance:

1. Nur gestagte Dateien – lint-staged filtert automatisch
2. Kein pnpm lint im pre-commit (Full-Projekt-Scan ist langsam)
3. Schwere Tests in die CI, nicht in den Hook
4. Notfall: git commit --no-verify

Typische Probleme

Husky unter Windows inaktiv

Git Bash statt CMD/PowerShell. Ausführungsrecht für .husky/pre-commit:

chmod +x .husky/pre-commit

Hook zu langsam

Über 10 Sekunden? Kein Full-Projekt-Check in lint-staged. Wenige Dateien: normalerweise 2–3 Sekunden.

Konfiguration prüfen

Test

1. Datei ändern, absichtlich Format kaputt machen (z. B. doppelte Anführungszeichen, Semikolons weg)
2. git add .
3. git commit -m "test"
4. Terminal-Ausgabe beobachten

Erfolg

Etwa:

✔ Preparing lint-staged...
✔ Running tasks for staged files...
✔ Applying modifications from tasks...
✔ Cleaning up temporary files...

Die Datei sollte automatisch korrigiert sein.

Bei Fehlschlag

• .husky/pre-commit vorhanden und korrekt?
• .lintstagedrc.mjs im Root?
• Manuell pnpm lint-staged – Fehlermeldung lesen

Erweiterte Konfiguration

commitlint (Commit-Messages)

Neben Format auch einheitliche Commit-Texte (z. B. Conventional Commits):

pnpm add -D @commitlint/cli @commitlint/config-conventional

commitlint.config.mjs:

export default {
  extends: ['@commitlint/config-conventional'],
};

commit-msg-Hook:

echo "pnpm commitlint --edit \$1" > .husky/commit-msg

git commit -m "fix bug" statt git commit -m "fix: bug" wird abgelehnt.

TypeScript-Typcheck im Hook

.lintstagedrc.mjs erweitern:

export default {
  '*.{ts,tsx}': [
    () => 'tsc --noEmit', // Typcheck
    'eslint --fix',
    'prettier --write',
  ],
  '*.{js,jsx}': [
    'eslint --fix',
    'prettier --write',
  ],
  '*.{json,md,css}': [
    'prettier --write',
  ],
};

Hinweis: tsc --noEmit prüft oft das ganze Projekt und kann langsam sein. Bei großen Repos Typcheck in die CI legen; pre-commit nur Format und Basis-Lint.

Monorepo

• Husky und lint-staged im Root
• pro Package eigene .lintstagedrc.mjs
• keine Regeln, die in andere Packages „auslaufen“

Details: lint-staged-Dokumentation.

FAQ: Häufige Probleme

Q1: ESLint und Prettier widersprechen sich?

Symptom: ESLint meckert über Format, Prettier formatiert zurück.

Lösung: eslint-config-prettier installieren und in ESLint zuletzt prettier extenden:

export default [
  ...compat.extends('next/core-web-vitals'),
  ...compat.extends('prettier'), // zuletzt
];

Prettier formatiert, ESLint prüft Qualität – ohne Doppelarbeit.

Q2: Nach Next.js 15 „plugin not detected“?

Symptom:

Error: The Next.js plugin was not detected in your ESLint configuration.

Lösung: Flat Config prüfen, @next/eslint-plugin-next korrekt:

import nextPlugin from '@next/eslint-plugin-next';

export default [
  {
    plugins: {
      '@next/next': nextPlugin,
    },
  },
];

Notfall: ESLINT_USE_FLAT_CONFIG=false.

Q3: pre-commit zu langsam?

1. lint-staged nur auf Staging (Standard)
2. Tests aus dem Hook
3. Bei sehr großen Repos ggf. ESLint nur auf .ts/.tsx, Rest nur Prettier

Q4: Kollegen ohne Husky-Hooks?

prepare in package.json sicherstellen; einmal pnpm install ausführen.

Q5: Husky unter Windows?

1. Git Bash
2. chmod +x .husky/pre-commit
3. Neu initialisieren:

rm -rf .husky
pnpm dlx husky init

Zusammenfassung und Best Practices

Etwa eine halbe Stunde Setup – langfristiger Gewinn fürs Team.

Kerngewinne

• Qualität: ESLint fängt Probleme früh ab
• Zusammenarbeit: einheitliches Format, weniger PR-Streit und Merge-Konflikte
• Automatisierung: Husky verhindert vergessene Checks

Empfehlungen

1. Schrittweise: erst Defaults, Regeln später verschärfen
2. Team-Abstimmung: Prettier-Optionen gemeinsam festlegen
3. Performance: pre-commit schlank halten, Schwergewicht in CI
4. Updates: Next.js 16 und ESLint-Entwicklung im Blick behalten (next lint entfällt)

Nächste Schritte

Wenn Sie noch ohne diese Kette arbeiten: heute mit diesem Guide starten – in etwa 30 Minuten steht das Setup. Konfiguration im Team teilen und Regeln an Ihre Gewohnheiten anpassen. Tools dienen Menschen, nicht umgekehrt.

Persönliche Erfahrung

Der Einstieg nervt manchmal – ESLint-9-Migration hat mich auch gekostet. Danach will ich nicht zurück: Commit ohne Format-Sorgen, lint läuft im Hook mit. PR-Reviews diskutieren Architektur statt Anführungszeichen. Die Zeit für das Setup hat sich mehrfach bezahlt gemacht.

---

Wenn beim Einrichten etwas hakt, schreiben Sie gerne in die Kommentare – ich helfe, wo ich kann.

Viel Erfolg beim Konfigurieren!