Design on kenji.blog

Hugo Theme-Anpassung: Wie man Tailwind CSS einführt

Sun, 13 Sep 2026 03:00:00 +0900

Einführung: Die starke Synergie zwischen dem Static Site Generator Hugo und Tailwind CSS

In der modernen Web-Frontend-Entwicklung ist die Vereinbarkeit von Leistung und Entwicklererfahrung (DX: Developer Experience) eines der wichtigsten Anliegen in jedem Projekt. Die Kombination von Hugo, das unter den Static Site Generatoren (SSG) zu den schnellsten der Welt gehört, mit Tailwind CSS, das das innovative Paradigma “Utility-First” eingeführt hat, kann als ultimative Lösung für dieses Problem angesehen werden.

Hugo ist in Go geschrieben und bietet eine unglaubliche Leistung, mit der Builds selbst für Websites mit Tausenden von Seiten in nur wenigen Sekunden oder Millisekunden abgeschlossen werden. Andererseits ermöglicht Tailwind CSS das direkte Schreiben unzähliger vordefinierter Utility-Klassen (z. B. flex, text-center, mt-4) in HTML, wodurch der Kontextwechsel zwischen CSS- und HTML-Dateien entfällt und Design-Iterationen beschleunigt werden.

In diesem Artikel werden wir die Schritte zur Integration von Tailwind CSS in ein Hugo-Theme und zum Aufbau einer fortschrittlichen Asset-Pipeline (Hugo Pipes) mit PostCSS im Detail erläutern – von den Grundlagen der Architektur bis hin zu mathematischen Leistungsoptimierungen.

1. Die Entwicklung von Utility-First CSS und komponentenbasiertem Design

Bevor wir zu den Schritten für die Integration von Tailwind CSS übergehen, ist es sehr hilfreich, die Geschichte und Entwicklung der CSS-Design-Philosophie zu verstehen, um zu begreifen, warum wir Tailwind CSS verwenden sollten.

Die Grenzen des traditionellen CSS-Designs (BEM und OOCSS)

In der Vergangenheit galt es in der Webentwicklung als Best Practice, semantische Klassennamen zu vergeben. Wenn man beispielsweise eine Kartenkomponente erstellte, trennte man HTML und CSS wie folgt:

1
2
3
4
5
6
7


<div class="card">
 <img class="card__image" src="image.jpg" alt="thumbnail">
 <div class="card__content">
 <h2 class="card__title">Titel</h2>
 <p class="card__description">Die Beschreibung wird hier eingefügt.</p>
 </div>
</div>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


.card {
 border-radius: 8px;
 box-shadow: 0 4px 6px rgba(0,0,0,0.1);
 background-color: #ffffff;
 overflow: hidden;
}
.card__title {
 font-size: 1.5rem;
 font-weight: bold;
 color: #333333;
}
/* Im Folgenden würden detailliertere Stile stehen */

Dieser auf BEM (Block Element Modifier) basierende Entwurf funktioniert bei kleinen Projekten gut, führt aber häufig zu den folgenden Problemen:

Erschöpfung und Ermüdung bei der Namensgebung: Jedes Mal, wenn eine ähnliche Komponente erstellt wird, muss man sich neue Klassennamen ausdenken (z. B. card-news, card-featured).
Aufblähen von CSS: Die Anzahl der CSS-Zeilen wächst mit jeder neuen Funktion, und einmal geschriebenes CSS wird selten gelöscht, aus Angst, man wisse nicht, “wo es verwendet wird”, wodurch sich toter Code ansammelt.
Kontextwechsel: Da HTML-Struktur und CSS-Stile in separaten Dateien verwaltet werden, steigt die Anzahl der Tab-Wechsel im Editor exponentiell an.

Paradigmenwechsel durch Tailwind CSS

Tailwind CSS löst diese Probleme durch einen Ansatz, der auf der “Kombination von Utility-Klassen” basiert. Wenn wir Tailwind CSS auf die obige Kartenkomponente anwenden, sieht das so aus:

1
2
3
4
5
6
7


<div class="rounded-lg shadow-md bg-white overflow-hidden">
 <img class="w-full h-48 object-cover" src="image.jpg" alt="thumbnail">
 <div class="p-6">
 <h2 class="text-2xl font-bold text-gray-800">Titel</h2>
 <p class="mt-2 text-gray-600">Die Beschreibung wird hier eingefügt.</p>
 </div>
</div>

Da die Klassennamen selbst spezifische Stilwerte darstellen (p-6 steht z. B. für padding: 1.5rem; usw.), kann man allein durch das Betrachten des HTMLs das endgültige Rendering-Ergebnis vorhersagen. Darüber hinaus extrahiert der JIT (Just-In-Time) Compiler von Tailwind nur die tatsächlich verwendeten Klassen in die endgültige CSS-Datei für die Produktion, wodurch die Dateigröße des CSS auf ein Minimum reduziert wird.

2. Die Architektur von Hugo Pipes und PostCSS

Um Tailwind CSS in Hugo zu integrieren, muss man die Asset-Verarbeitungs-Pipeline namens Hugo Pipes verstehen. Hugo Pipes ist eine leistungsstarke Funktion, die alle assetbezogenen Prozesse – wie die Kompilierung von Sass/SCSS, das Bündeln und Minifizieren von JavaScript und die Ausführung von PostCSS, das wir hier verwenden werden – innerhalb von Hugo selbst abschließt.

PostCSS ist ein Tool zum Transformieren von CSS mithilfe von JavaScript-Plugins. Tatsächlich funktioniert auch Tailwind CSS selbst als PostCSS-Plugin.

Der AST (Abstract Syntax Tree) Transformationsmechanismus in PostCSS

Zu verstehen, wie PostCSS CSS verarbeitet, ist bei der Fehlersuche enorm hilfreich. Das folgende Mermaid-Diagramm zeigt die Pipeline, in der PostCSS eine CSS-Datei einliest, sie mithilfe von Plugins konvertiert und das endgültige CSS ausgibt.

flowchart TD
A["Rohes CSS (styles.css)"] -->|Parser| B["AST (Abstrakter Syntaxbaum)"]
B --> C["Plugin 1: Tailwind CSS"]
C --> D["Plugin 2: Autoprefixer"]
D --> E["Plugin N: cssnano"]
E -->|Stringifier| F["Kompiliertes & optimiertes CSS"]

Parser: Analysiert die eingegebene rohe CSS-Zeichenfolge und wandelt sie in einen AST (Abstrakter Syntaxbaum) um, eine Datenstruktur, die programmgesteuert manipuliert werden kann.
Plugins:
- Tailwind CSS: Scannt Vorlagendateien (HTML oder Markdown) und fügt dem AST Knoten für die verwendeten Utility-Klassen hinzu. Es löst auch @tailwind-Direktiven auf.
- Autoprefixer: Bezieht sich auf die Can I Use-Datenbank und fügt dem AST bei Bedarf Vendor-Präfixe (-webkit-, -moz- usw.) als Eigenschaften hinzu.
Stringifier: Konvertiert den transformierten AST zurück in eine CSS-Zeichenfolge, die vom Browser interpretiert werden kann, und gibt diese aus.

3. Umgebungseinrichtung und Voraussetzungen

Lassen Sie uns nun mit dem eigentlichen Integrationsprozess beginnen. Zuerst überprüfen wir, ob die benötigte Software installiert ist.

Voraussetzungen

Hugo Extended Version: Sie benötigen die Extended-Version, die Sass/SCSS-Verarbeitungsfunktionen und native PostCSS-Integration enthält, anstelle der regulären Hugo-Version. Führen Sie den folgenden Befehl im Terminal aus und stellen Sie sicher, dass die Versionsinformationen die Zeichenfolge extended enthalten.
1 2 3

hugo version # Erwartete Ausgabe: # hugo v0.121.2-4146... windows/amd64 BuildDate=... VendorInfo=gohugoio +extended
Node.js und npm: Abhängigkeiten wie Tailwind CSS und PostCSS laufen auf Node.js. Stellen Sie sicher, dass Node.js (LTS-Version empfohlen) installiert ist.
1 2

node -v npm -v

Installation der npm-Pakete

Initialisieren Sie npm im Stammverzeichnis Ihres Projekts (der Ebene, auf der sich Hugos Konfigurationsdatei hugo.toml befindet) und installieren Sie die benötigten Pakete.

1
2
3
4
5


# Erzeugen der package.json
npm init -y

# Installieren von Tailwind CSS, PostCSS und Autoprefixer als Entwicklungsabhängigkeiten
npm install -D tailwindcss postcss postcss-cli autoprefixer

[!IMPORTANT] Wenn postcss-cli nicht installiert ist, kann ein Fehler auftreten, wenn Hugo versucht, PostCSS intern aufzurufen. Hugo Pipes verwendet intern postcss-cli, also stellen Sie sicher, dass es installiert ist.

4. Konfigurationsdateien erstellen (PostCSS & Tailwind CSS)

Nachdem die Pakete installiert sind, erstellen wir zwei wichtige Konfigurationsdateien, die das Verhalten des Projekts steuern. Platzieren Sie diese im Stammverzeichnis Ihres Projekts.

Erstellen von tailwind.config.js

Wenn Sie den folgenden Befehl in Ihrem Terminal ausführen, wird eine Standardkonfigurationsdatei generiert.

1

npx tailwindcss init

Öffnen Sie die generierte Datei tailwind.config.js in Ihrem Editor und konfigurieren Sie die Eigenschaft content. Dies ist sehr wichtig. Tailwind analysiert die Dateien in den hier angegebenen Pfaden und extrahiert die verwendeten Klassen. Geben Sie die Layout- und Inhaltsdateien entsprechend der Projektstruktur von Hugo genau an.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


/** @type {import('tailwindcss').Config} */
module.exports = {
 // Scanziele entsprechend Hugos Verzeichnisstruktur angeben
 content: [
 "./content/**/*.md",
 "./content/**/*.html",
 "./layouts/**/*.html",
 "./assets/**/*.js",
 // Wenn Sie ein Theme verwenden, müssen Sie auch dessen Verzeichnis einschließen
 // "./themes/my-theme/layouts/**/*.html",
 ],
 theme: {
 extend: {
 // Erweitern Sie hier benutzerdefinierte Farben oder Schriftarten
 colors: {
 'brand-primary': '#3490dc',
 'brand-secondary': '#ffed4a',
 },
 fontFamily: {
 'sans': ['Helvetica Neue', 'Arial', 'Hiragino Kaku Gothic ProN', 'Meiryo', 'sans-serif'],
 }
 },
 },
 plugins: [
 // Bei Bedarf offizielle Plugins hinzufügen (z. B. das Typography-Plugin)
 // require('@tailwindcss/typography'),
 ],
}

Erstellen von postcss.config.js

Als Nächstes erstellen Sie postcss.config.js im Stammverzeichnis des Projekts. Darin wird definiert, welche Plugins PostCSS in welcher Reihenfolge ausführt.

1
2
3
4
5
6


module.exports = {
 plugins: {
 tailwindcss: {},
 autoprefixer: {},
 }
}

Mit dieser Konfiguration führt Hugo, wenn es PostCSS aufruft, zuerst die Verarbeitung durch Tailwind CSS aus und wendet anschließend Autoprefixer an, um Vendor-Präfixe hinzuzufügen.

5. Aufbau der CSS-Asset-Pipeline in Hugo

Sobald die Konfiguration abgeschlossen ist, ist es an der Zeit, Tailwind CSS in das Hugo-Theme zu integrieren.

5-1. Erstellen der CSS-Datei als Einstiegspunkt

Erstellen Sie eine CSS-Datei als Einstiegspunkt im Verzeichnis assets/css/ (erstellen Sie es, falls es nicht existiert). Hier nennen wir sie main.css.

Dateipfad: assets/css/main.css

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


/* Laden der Basisstile von Tailwind (Reset CSS usw.) */
@tailwind base;

/* Laden der Komponentenklassen */
@tailwind components;

/* Laden der Utility-Klassen */
@tailwind utilities;

/* Wenn Sie eigenes benutzerdefiniertes CSS benötigen, können Sie es hier hinzufügen,
 es wird jedoch empfohlen, dafür wenn möglich die extend-Option in der tailwind.config.js zu nutzen */
@layer components {
 .btn-primary {
 @apply bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded transition-colors duration-300;
 }
}

5-2. Bearbeiten der Layout-Datei (head.html)

Als Nächstes weisen wir Hugos Template an, die oben genannte CSS-Datei zu laden, und definieren die Pipeline, um sie mit PostCSS zu verarbeiten. Im Allgemeinen wird das Partial-Template, das das <head>-Tag definiert, (z. B. layouts/partials/head.html) bearbeitet.

Dateipfad: layouts/partials/head.html

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


<head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>{{ .Title }} | {{ .Site.Title }}</title>

 <!-- Abrufen von assets/css/main.css -->
 {{ $css := resources.Get "css/main.css" }}

 <!-- Definieren der PostCSS-Optionen -->
 {{ $options := dict "inlineImports" true }}
 {{ $css = $css | resources.PostCSS $options }}

 <!-- Asset-Optimierungspipeline für die Produktionsumgebung -->
 {{ if hugo.IsProduction }}
 <!-- 1. Minify (Komprimierung) -->
 {{ $css = $css | minify }}
 <!-- 2. Fingerprint (Hinzufügen eines Hashes für Cache-Busting) -->
 {{ $css = $css | fingerprint "sha512" }}
 <!-- 3. Ausgeben des Tags mit SRI (Subresource Integrity) -->
 <link rel="stylesheet" href="{{ $css.RelPermalink }}" integrity="{{ $css.Data.Integrity }}" crossorigin="anonymous">
 {{ else }}
 <!-- In der Entwicklungsumgebung unkomprimiert ausgeben (Priorität auf Build-Geschwindigkeit) -->
 <link rel="stylesheet" href="{{ $css.RelPermalink }}">
 {{ end }}
</head>

Erläuterung der Pipeline und Mermaid-Diagramm

Im Folgenden wird erläutert, wie der obige Go-Template-Code die CSS-Datei verarbeitet, illustriert durch eine Reihe von Pipeline-Prozessen.

flowchart TD
A["assets/css/main.css"] -->|resources.Get| B["Hugo-Speicherbereich"]
B -->|resources.PostCSS| C["PostCSS + Tailwind JIT-Prozess"]
C --> D{"hugo.IsProduction ?"}
D -- Ja (Produktionsumgebung) --> E["minify (Leerzeichen/Zeilenumbrüche entfernen)"]
E --> F["fingerprint (Hash berechnen)"]
F --> G["public/css/main.[hash].css (mit SRI)"]
D -- Nein (Entwicklungsumgebung) --> H["public/css/main.css"]

resources.Get: Sucht die angegebene Datei im Verzeichnis assets und lädt sie als Ressourcenobjekt in den Speicher.
resources.PostCSS: Verweist auf die postcss.config.js im Stammverzeichnis des Projekts und wendet Tailwind CSS und Autoprefixer auf den CSS-Quellcode an. In der Entwicklungsumgebung (hugo server) arbeitet der JIT-Modus und generiert beim Ändern von Dateien schnell nur die benötigten Klassen.
minify: Entfernt beim Build für die Produktion (z. B. hugo --environment production) unnötige Leerzeichen und Kommentare und minimiert die Dateigröße.
fingerprint: Berechnet basierend auf dem Dateiinhalt einen SHA-Hash und hängt ihn an den Dateinamen an (z. B. main.ab12cd...css). Dies ermöglicht ein “Cache-Busting”, was sicherstellt, dass neue Dateien zuverlässig geladen werden, wenn das CSS aktualisiert wird, während der leistungsstarke Cache des Browsers genutzt wird.
integrity: Verwendet den durch den Fingerprint berechneten Hash-Wert, um ein SRI-Attribut auszugeben, das Manipulationen durch CDNs usw. verhindert.

6. Mathematische Leistungsanalyse in der CSS-Optimierung

Einer der größten Vorteile der Einführung von Tailwind CSS ist die Minimierung der ausgelieferten CSS-Dateigröße. Analysieren wir dies quantitativ mithilfe eines mathematischen Modells, um zu verstehen, wie sich dies auf die Web-Performance (insbesondere den First Contentful Paint: FCP) auswirkt.

Modell zur Reduzierung der CSS-Dateigröße

Bei traditionellen CSS-Frameworks (wie Bootstrap) wird das gesamte Framework geladen, einschließlich der nicht verwendeten Stile, was zu einer großen Dateigröße $S_{original}$ führt (ca. 150 KB bis 200 KB). Wenn die Dateigröße nach Anwendung des Purge-Prozesses durch den JIT-Compiler von Tailwind CSS $S_{purged}$ ist, kann dies mit der Reduzierungsrate $R_{purge}$ wie folgt ausgedrückt werden:

$$ S_{purged} = S_{original} \times (1 - R_{purge}) $$

In einem typischen Projekt erreicht $R_{purge}$ nahezu $0.9$ (90% Reduzierung), wodurch $S_{purged}$ auf nur noch etwa 10 KB bis 20 KB sinkt.

Zusätzlich erfolgt bei der Auslieferung eine Komprimierung auf der Serverseite mittels Brotli oder Gzip. Wenn die Komprimierungsrate $R_{compress}$ (typischerweise etwa 0,7 bis 0,8) beträgt, wird die endgültige Nutzlastgröße $S_{final}$, die über das Netzwerk übertragen wird, nach folgender Formel berechnet:

$$ S_{final} = S_{purged} \times (1 - R_{compress}) $$

Kritischer Rendering-Pfad und Netzwerklatenz

Die Zeit, die der Browser benötigt, um die ersten Inhalte auf dem Bildschirm zu zeichnen (FCP), kann durch die Summe aus der HTML-Download-Zeit, der CSS-Download-Zeit und der Rendering-Zeit angenähert werden.

$$ T_{FCP} \approx RTT + \frac{S_{HTML}}{BW} + RTT + \frac{S_{final}}{BW} + T_{render} $$

Hierbei ist:

$RTT$ : Round Trip Time (Netzwerkverzögerung zwischen Client und Server)
$BW$ : Netzwerkbandbreite (Bandwidth)

In Umgebungen mit schmaler $BW$ und hohem $RTT$ (hohe Latenz), wie z. B. in mobilen Netzwerken, minimiert der Ansatz von Tailwind CSS $S_{final}$ auf nur wenige Kilobyte. Dies treibt den Term $\frac{S_{final}}{BW}$ nahe Null und ist die treibende Kraft für das Erreichen unglaublicher Ergebnisse bei Tests (wie Google PageSpeed Insights).

7. Starten des Entwicklungsservers und Bestätigung des Hot-Reloadings

Nachdem alle Einstellungen vorgenommen wurden, starten Sie den Hugo-Entwicklungsserver und überprüfen Sie, ob Tailwind CSS ordnungsgemäß funktioniert.

1

hugo server -D

Rufen Sie http://localhost:1313/ in Ihrem Browser auf und vergewissern Sie sich, dass die Website angezeigt wird. Öffnen Sie eine Markdown-Inhaltsdatei oder ein Hugo-Template (die Dateien unter layouts/) und versuchen Sie, einige Klassen hinzuzufügen.

1
2
3
4
5


<!-- Beispiel für die Anwendung von Tailwind-Klassen zum Testen -->
<div class="bg-gradient-to-r from-blue-500 to-purple-600 text-white p-8 rounded-xl shadow-2xl text-center transform transition duration-500 hover:scale-105">
 <h1 class="text-4xl font-extrabold tracking-tight">Tailwind CSS + Hugo ist großartig!</h1>
 <p class="mt-4 text-lg font-medium">Vergewissern Sie sich, dass das Hot-Reloading sofort übernommen wird.</p>
</div>

Sobald Sie die Datei speichern, arbeiten Hugos leistungsstarker File Watcher und der JIT-Compiler von Tailwind zusammen, um das CSS im Millisekundenbereich neu zu erstellen. Sie werden die Freude erleben, wenn der Browser automatisch neu geladen wird (Hot-Reload).

Fehlerbehebung: Wenn Stile nicht angewendet werden

Sollten die Änderungen nicht sichtbar sein, prüfen Sie bitte die folgenden Punkte:

Die Einstellung des content-Pfads in tailwind.config.js Wenn der Pfad zu den zu scannenden Dateien falsch ist, kann Tailwind die in diesen Dateien verwendeten Klassen nicht erkennen und fügt sie dem CSS nicht hinzu. Überprüfen Sie insbesondere bei Verwendung eines Themes, ob der Pfad zum Theme-Verzeichnis fehlt.
PostCSS-Fehler Wenn Sie in den Protokollen des Hugo-Servers in Ihrem Terminal Fehler wie Error: failed to transform resource: PostCSS not found sehen, ist npm install möglicherweise nicht erfolgreich ausgeführt worden, oder postcss-cli fehlt.
Hugos Cache leeren In seltenen Fällen kann durch Hugos Caching ein altes CSS erhalten bleiben. Versuchen Sie, den Server zu stoppen, ihn mit hugo server --ignoreCache neu zu starten oder das temporäre Verzeichnis des Betriebssystems (z. B. /tmp/hugo_cache/) zu löschen.

8. Build für die Produktion und weitere Verbesserungen

Wenn Sie Ihre Website auf einem Produktionsserver (z. B. Netlify, Vercel, GitHub Pages, Cloudflare Pages) bereitstellen, müssen Sie Umgebungsvariablen setzen und die Optimierungspipeline für die Produktion ausführen.

1
2


# Beispiel für einen Produktions-Build-Befehl
NODE_ENV=production hugo --minify --environment production

Durch das Hinzufügen des Flags --environment production wird der {{ if hugo.IsProduction }}-Block in der Datei head.html ausgeführt, woraufhin das CSS minifiziert und der Fingerprint hinzugefügt wird.

Markdown-Styling mit dem Typography-Plugin

Auf Blog- oder Dokumentationsseiten wie bei Hugo können Klassen nicht direkt an die aus Markdown generierten reinen HTML-Elemente (<h1>, <p>, <ul> usw.) angehängt werden. In solchen Fällen ist das offizielle Typography-Plugin von Tailwind sehr nützlich.

Installieren Sie das Plugin

1

npm install -D @tailwindcss/typography

Fügen Sie es zu tailwind.config.js hinzu

1
2
3
4
5
6


module.exports = {
 // ...
 plugins: [
 require('@tailwindcss/typography'),
 ],
}

Anwendung im Template Durch einfaches Hinzufügen der Klasse prose (sowie optionaler Farb- und Größenvarianten) zum Container-Element, das den Artikelinhalt ausgibt, werden schöne Standardstile angewendet.
1 2 3

<article class="prose prose-lg prose-blue mx-auto mt-10"> {{ .Content }} </article>

Dadurch müssen keine komplexen CSS-Selektoren (z. B. .article-content h2 { ... }) manuell geschrieben werden, und die Modularität der Komponenten bleibt vollständig erhalten.

9. Fazit: Vollendung eines hochgradig wartbaren Frontend-Ökosystems

Gut gemacht! Damit ist die perfekte Webentwicklungs-Asset-Pipeline fertiggestellt, die die extrem schnelle Engine zur Generierung statischer Webseiten von Hugo mit den modernen Styling-Funktionen von Tailwind CSS und der Erweiterbarkeit von PostCSS vereint.

Das Tolle an dieser Architektur ist, “dass Sie sie nur einmal einrichten müssen”. Sobald die Pipeline eingerichtet ist, können Entwickler komplexe Benutzeroberflächen in rasanter Geschwindigkeit erstellen, ohne jemals eine CSS-Datei öffnen zu müssen, indem sie einfach intuitive Utility-Klassen in ihre HTML- oder Markdown-Templates schreiben.

Da zudem die ausgegebene CSS-Größe stets minimiert wird, führt dies direkt zu besseren Core Web Vitals-Scores und ist aus SEO-Sicht sehr vorteilhaft.

Die Kombination aus Hugo und Tailwind CSS wird für jedes Projekt, vom persönlichen Tech-Blog bis zur großen Unternehmens-Website, weiterhin eine der “besten Entscheidungen” sein. Nutzen Sie diese mächtige Toolchain auf jeden Fall und genießen Sie ein komfortables Web-Entwicklungsleben!

Design-Prinzipien für CSS bei der Dark-Mode-Unterstützung von Blogs

Sat, 12 Sep 2026 12:00:00 +0900

In der modernen Webentwicklung hat sich die Unterstützung des Dark Mode (Dunkelmodus) von einer bloßen „Nice-to-have“-Funktion zu einer „Must-have“-Anforderung zur Verbesserung der User Experience (UX) gewandelt. Besonders bei Medien wie Blogs und Dokumentationsseiten, die auf langes Lesen von Texten ausgelegt sind, ist die Bedeutung der Dark-Mode-Unterstützung extrem hoch, da sie die Augenbelastung der Nutzer verringert und den Akkuverbrauch der Geräte senkt.

In diesem Artikel werden wir die technischen Herausforderungen, die bei der Dark-Mode-Unterstützung von Blogs unweigerlich auftreten, sowie die Punkte eines hochgradig wartbaren CSS-Designs aus der Perspektive eines Frontend-Entwicklers sehr tiefgehend beleuchten. Wir decken alles rund um die Implementierung des Dark Mode ab: von der Nutzung von CSS Custom Properties (CSS-Variablen), fortgeschrittener JavaScript-Steuerung und SSR-Integration zur Vermeidung von FOUC (Flash of Unstyled Content), über Farbdesign (RGB, HSL und das neueste OKLCH) zur Gewährleistung der Barrierefreiheit (WCAG 2.1 AAA), bis hin zu praktischen Code-Beispielen mit Tailwind CSS.

1. Grundlagen des Theme-Designs mit CSS Custom Properties (CSS-Variablen)

Der aktuell standardmäßigste und leistungsstärkste Ansatz zur Implementierung des Dark Mode ist die Verwendung von CSS Custom Properties (CSS-Variablen). Während Variablen ($color) in CSS-Präprozessoren wie Sass zur Kompilierzeit statisch aufgelöst werden, werden CSS-Variablen zur Laufzeit des Browsers dynamisch aufgelöst und überschrieben. Dies macht es möglich, die Farbgebung der gesamten Seite sofort zu ändern, indem einfach Klassen über JavaScript umgeschaltet werden.

1.1 Definition des grundlegenden Farb-Themes

Zunächst definieren wir die Farbpalette für den Light Mode (Standard) mithilfe der Pseudoklasse :root. Das klassische Designmuster besteht dann darin, diese Variablen zu überschreiben, wenn ein Attribut wie [data-theme='dark'] (oder eine .dark-Klasse) hinzugefügt wird.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


/* Variablen-Definition für den Light Mode (Standard) */
:root {
 --color-bg-primary: #ffffff;
 --color-bg-secondary: #f3f4f6;
 --color-text-primary: #111827;
 --color-text-secondary: #4b5563;
 --color-accent: #3b82f6;
 --color-border: #e5e7eb;
}

/* Variablen-Überschreibung im Dark Mode */
[data-theme='dark'] {
 --color-bg-primary: #111827;
 --color-bg-secondary: #1f2937;
 --color-text-primary: #f9fafb;
 --color-text-secondary: #9ca3af;
 --color-accent: #60a5fa;
 --color-border: #374151;
}

/* Tatsächliche Anwendung */
body {
 background-color: var(--color-bg-primary);
 color: var(--color-text-primary);
 transition: background-color 0.3s ease, color 0.3s ease;
}

a {
 color: var(--color-accent);
}

Durch die vollständige Trennung von Layout- oder Typografie-Spezifikationen und Farb-(Theme-)Spezifikationen auf diese Weise wird die Wartbarkeit von CSS drastisch verbessert.

1.2 Nutzung von @media (prefers-color-scheme: dark)

Wenn der Dark Mode auf Betriebssystemebene eingestellt ist, ist es aus UX-Sicht wünschenswert, das dunkle Theme ab dem ersten Besuch der Website automatisch anzuwenden. Dies wird durch die Media-Query @media (prefers-color-scheme: dark) erreicht.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


/* Fallback, wenn das Betriebssystem auf Dark Mode eingestellt ist */
@media (prefers-color-scheme: dark) {
 :root:not([data-theme='light']) {
 --color-bg-primary: #111827;
 --color-bg-secondary: #1f2937;
 --color-text-primary: #f9fafb;
 --color-text-secondary: #9ca3af;
 --color-accent: #60a5fa;
 --color-border: #374151;
 }
}

Bei dieser Schreibweise wird die Dark-Mode-Einstellung des Betriebssystems respektiert und die Variablen werden überschrieben, es sei denn, der Benutzer hat explizit den Light Mode gewählt (data-theme='light').

2. Verständnis von Farbräumen und Barrierefreiheit (WCAG 2.1 AAA)

Beim Farbdesign für den Dark Mode reicht es nicht aus, einfach „den Hintergrund schwarz und den Text weiß zu machen“. Wenn der Kontrast zu stark ist, kann dies zu einer Überstrahlung führen und das Lesen erschweren; ist der Kontrast zu gering, wird die Sichtbarkeit beeinträchtigt. In den Web Content Accessibility Guidelines (WCAG) ist das Kontrastverhältnis zur Gewährleistung der Sichtbarkeit streng definiert.

2.1 Berechnungsformel für das WCAG-Kontrastverhältnis

Das Kontrastverhältnis (Contrast Ratio) $CR$ in den WCAG wird anhand der relativen Leuchtdichte (Relative Luminance) von Hintergrund- und Vordergrundfarbe wie folgt definiert:

$$CR = \frac{L_{lighter} + 0.05}{L_{darker} + 0.05}$$

Hierbei ist $L_{lighter}$ die relative Leuchtdichte der helleren Farbe und $L_{darker}$ die relative Leuchtdichte der dunkleren Farbe (der Wertebereich liegt zwischen 0,0 und 1,0). Um das Level AAA der WCAG 2.1 zu erreichen, ist ein Kontrastverhältnis von mindestens 7:1 für normalen Text und mindestens 4.5:1 für großen Text erforderlich.

Die relative Leuchtdichte $L$ wird aus den RGB-Werten des sRGB-Farbraums mit der folgenden komplexen Formel berechnet:

$$L = 0.2126 \times R + 0.7152 \times G + 0.0722 \times B$$

Für jede Komponente ($R, G, B$) wird der normalisierte Wert verwendet, der durch Teilen des ursprünglichen 8-Bit-Werts ($R_{sRGB}$) durch 255 ermittelt wird, und die folgende Transformation zur Aufhebung der Gammakorrektur durchgeführt:

$$ R, G, B = \begin{cases} \frac{C_{sRGB}}{12.92} & \text{if } C_{sRGB} \le 0.03928 \\ \left( \frac{C_{sRGB} + 0.055}{1.055} \right)^{2.4} & \text{otherwise} \end{cases} $$

Es ist schwierig, diese Berechnung manuell durchzuführen, aber durch den Einsatz von Farbdesign-Tools können mechanisch Farben ausgewählt werden, die das Kontrastverhältnis von 7:1 ($CR \ge 7.0$) erfüllen.

2.2 HSL vs. RGB vs. OKLCH

Früher waren RGB und HSL die vorherrschenden Methoden bei der Erstellung von Farbpaletten. Diese weisen jedoch in Bezug auf die „wahrnehmungsbezogene Gleichmäßigkeit“ große Mängel auf.

RGB: Es handelt sich um mechanische primäre Lichtfarben, was es für Menschen schwierig macht, intuitiv Anpassungen wie „heller machen“ oder „dunkler machen“ vorzunehmen.
HSL: Verwendet Farbton (Hue), Sättigung (Saturation) und Helligkeit (Lightness), aber die „Helligkeit (L)“ in HSL stimmt nicht mit der wahrgenommenen Helligkeit des menschlichen Auges überein. Beispielsweise haben ein reines Gelb und ein reines Blau mit einer Helligkeit von 50 % in HSL numerisch die gleiche Helligkeit, aber für das menschliche Auge erscheint das Gelb überwältigend heller.
OKLCH: Der neueste Farbraum, der kürzlich in das CSS Color Module Level 4 aufgenommen wurde. Er besteht aus Lightness (wahrgenommene Helligkeit), Chroma (Sättigung) und Hue (Farbton) und ist vollständig auf die menschlichen Seheigenschaften abgestimmt (wahrnehmungsbezogen gleichmäßig).

Durch die Verwendung von OKLCH kann die gleiche wahrgenommene Helligkeit (Lightness) auch dann beibehalten werden, wenn sich der Farbton (Hue) ändert, was die Generierung von Farbpaletten für den Dark Mode extrem vorhersehbar und sicher macht.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


/* Beispiel für die Definition von CSS-Variablen mit OKLCH */
:root {
 /* Höhere Basishelligkeit und geringere Sättigung für den Light Mode */
 --bg-base: oklch(0.98 0.01 250);
 --text-base: oklch(0.25 0.02 250);
 --primary-brand: oklch(0.65 0.15 250);
}

[data-theme="dark"] {
 /* Im Dark Mode wird nur die Helligkeit umgekehrt, um den wahrgenommenen Kontrast leicht beizubehalten */
 --bg-base: oklch(0.20 0.02 250);
 --text-base: oklch(0.95 0.01 250);
 --primary-brand: oklch(0.75 0.15 250); /* Etwas heller für den Dark Mode, um die Sichtbarkeit zu gewährleisten */
}

Durch die Einführung von OKLCH auf diese Weise lässt sich eine einfache Logik aufbauen, um ein konsistentes Kontrastverhältnis (WCAG AAA-Niveau) über mehrere Themes hinweg zu garantieren.

3. Vermeidung von FOUC (Flash of Unstyled Content) und SSR-Hydratisierung

Das Problem, das Entwickler bei der Unterstützung des Dark Mode am meisten plagt, ist das Flackern des Bildschirms, bekannt als FOUC (Flash of Unstyled Content).

3.1 Die Falle des Theme-Wechsels via clientseitigem JS

Bei SPAs wie React oder Vue (oder statischen Seiten durch SSG) ist es üblich, die Einstellungen des Nutzers im localStorage zu speichern, sie mit JavaScript auszulesen und das Theme umzuschalten. Wenn dieser Prozess jedoch z. B. im useEffect von React durchgeführt wird, treten die folgenden Probleme auf:

Der Browser rendert das HTML/CSS des Light Mode.
Das JS-Bundle wird geladen und ausgeführt.
Die dark-Einstellung wird aus dem localStorage gelesen.
Die Klasse dark wird dem HTML hinzugefügt und der Bildschirm wird plötzlich dunkel (Flackern).

3.2 Die perfekte Maßnahme gegen FOUC: Einsatz von Cookies und SSR

Die Best Practice, um FOUC vollständig zu vermeiden und Hydratisierungsfehler zu verhindern, besteht darin, die Theme-Einstellungen des Nutzers in document.cookie zu speichern und das HTML mit den entsprechenden Klassen bereits in der Phase des serverseitigen Renderings (SSR) zurückzugeben.

Das folgende Sequenzdiagramm zeigt den idealen Ablauf der Theme-Initialisierung mithilfe von Cookies.

sequenceDiagram
participant User as "Benutzer"
participant Browser as "Browser OS"
participant Server as "Server SSR"
participant DOM as "Client DOM"
User->>Browser: "Seite anfordern"
Browser->>Server: "GET-Anfrage mit Cookie (theme=dark)"
Server-->>Browser: "HTML mit <html data-theme='dark'> zurückgeben"
Browser->>DOM: "Initiales HTML rendern (Kein FOUC)"
DOM->>DOM: "Hydratisierungs-Skript ausführen"
alt "Cookie fehlt (Erster Besuch)"
DOM->>Browser: "OS prefers-color-scheme prüfen"
Browser-->>DOM: "matchMedia-Ergebnis (z.B. dark)"
DOM->>DOM: "data-theme='dark' via blockierendem Inline-Skript setzen"
end

3.3 Verteidigungslinie durch Inline-Skripte (Für statische Seiten, die keine Cookies verwenden können)

Bei Blogs, die reines SSG (Static Site Generation) ohne SSR-Möglichkeit nutzen (wie statische Exporte von Hugo, Gatsby oder Astro), ist es zwingend erforderlich, ein blockierendes Inline-JavaScript innerhalb des <head>-Tags zu platzieren, das die Klasse unmittelbar vor dem Rendern des DOM hinzufügt.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


<!-- Am Ende innerhalb von <head> platzieren -->
<script>
 (function() {
 try {
 var localTheme = localStorage.getItem('theme');
 var osTheme = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
 var theme = localTheme || osTheme;
 document.documentElement.setAttribute('data-theme', theme);
 } catch (e) {}
 })();
</script>

Da dieses kleine Skript das Rendering des Browsers blockiert und sofort ausgeführt wird, ist das Attribut data-theme bereits zum Zeitpunkt des Zeichnens des Bildschirms gesetzt, wodurch das Bildschirmflackern (FOUC) vollständig vermieden wird.

4. Implementierungsansätze mit Tailwind CSS und rohem SCSS/CSS

Wenn Sie den Dark Mode in ein reales Projekt integrieren, müssen Sie die werkzeugspezifischen Ansätze verstehen.

4.1 Dark Mode in Tailwind CSS

Tailwind CSS bietet standardmäßig die Variante dark:, was die Implementierung des Dark Mode extrem einfach macht. Setzen Sie die Eigenschaft darkMode in der Konfigurationsdatei (tailwind.config.js).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


// tailwind.config.js
module.exports = {
 // 'media' (abhängig von OS-Einstellung) oder 'class' (manuell umschaltbar)
 darkMode: 'class',
 theme: {
 extend: {
 colors: {
 /* Erweitern Sie die Tailwind-Farbpalette mithilfe von CSS-Variablen */
 primary: 'rgb(var(--color-primary) / <alpha-value>)',
 background: 'rgb(var(--color-background) / <alpha-value>)',
 }
 }
 }
}

Auf der HTML-Seite müssen Sie lediglich die Klassen wie folgt hinzufügen:

1
2
3
4


<div class="bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100">
 <h1 class="text-2xl font-bold">Hallo Welt</h1>
 <p class="mt-2">Tailwind macht den Dark Mode unglaublich einfach.</p>
</div>

Es ist jedoch eine Ursache für aufgeblähte Komponenten, dark:bg-xxx auf alle Elemente anzuwenden. In großen Blogs und Apps wird ein hybrides Design (semantisches Farbdesign) empfohlen, das auf CSS-Variablen basiert und von Tailwind aus auf diese CSS-Variablen verweist.

Hier ist ein Klassendiagramm, das die Vererbung und Anwendungsebenen von CSS-Variablen zeigt:

classDiagram
class GlobalCSSVariables {
"--color-brand-500"
"--color-gray-900"
}
class SemanticVariables {
"--bg-primary"
"--text-base"
"--accent"
}
class TailwindConfig {
"theme.colors.background"
"theme.colors.primary"
}
class UIComponents {
"class='bg-background text-primary'"
}
GlobalCSSVariables <|-- SemanticVariables : ":root & .dark"
SemanticVariables <|-- TailwindConfig : "tailwind.config.js"
TailwindConfig <.. UIComponents : "Wendet Utility-Klassen an"

4.2 Implementierung mit Raw SCSS/CSS (Nutzung von Mixins)

In Projekten, die SCSS selbst schreiben, ohne Tailwind zu verwenden, kapseln wir die Dark-Mode-Stile mithilfe von @mixin.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


/* Definition des SCSS Mixins */
@mixin dark-mode {
 /* Unterstützt sowohl das [data-theme='dark'] Attribut als auch OS-Einstellungen */
 [data-theme='dark'] & {
 @content;
 }
 @media (prefers-color-scheme: dark) {
 :root:not([data-theme='light']) & {
 @content;
 }
 }
}

/* Anwendungsbeispiel */
.card {
 background-color: #ffffff;
 color: #333333;
 border: 1px solid #eeeeee;

 @include dark-mode {
 background-color: #1a202c;
 color: #e2e8f0;
 border-color: #2d3748;
 }
}

Diese Methode ist intuitiv, aber da die Dateigröße des CSS nach der Kompilierung dazu neigt, aufzublähen (Media-Queries werden für jeden Selektor dupliziert), ist der aktuelle Trend die Umstellung auf ein Design, das sich auf CSS-Variablen (Custom Properties) konzentriert.

5. Dark-Mode-Optimierung für Bilder (Images) und SVGs

Auch wenn das Farbdesign von Text und Hintergrund abgeschlossen ist, wirken als Inhalt platzierte Bilder und Icons (SVGs), wenn sie im Light Mode verbleiben, extrem blendend und isoliert im Dark Mode. Eine Optimierung auch für diese ist unerlässlich.

5.1 CSS-Filter zur Reduzierung der Bildhelligkeit

Bitmap-Bilder wie Fotos können zu hell sein, wenn sie unverändert im Dark Mode angezeigt werden. Durch die Verwendung der CSS-Eigenschaft filter, um die Helligkeit (brightness) und den Kontrast (contrast) des Bildes leicht zu verringern, kann es natürlich in die Dark-Theme-UI integriert werden.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


[data-theme='dark'] img:not([src*=".svg"]) {
 /* Helligkeit verringern, Kontrast leicht erhöhen */
 filter: brightness(0.8) contrast(1.1);
 transition: filter 0.3s ease;
}

[data-theme='dark'] img:hover {
 /* Beim Hovern zur ursprünglichen Helligkeit zurückkehren (falls der Benutzer Details sehen möchte) */
 filter: brightness(1) contrast(1);
}

5.2 Bildunterscheidung mit dem `<picture>`-Tag

Logo-Bilder oder erklärende Illustrationen (wie JPEGs mit festem weißem Hintergrund) können nicht allein durch Filterung behandelt werden. In diesem Fall ist es die richtige Lösung, das HTML-Element <picture> und Media-Queries zu verwenden, um eine andere Bilddatei für den Dark Mode anzuzeigen.

1
2
3
4
5
6


<picture>
 <!-- Wird für Benutzer mit Dark-Mode-OS-Einstellung angezeigt -->
 <source srcset="/img/logo-dark.png" media="(prefers-color-scheme: dark)">
 <!-- Standard (Light Mode) -->
 <img src="/img/logo-light.png" alt="Website-Logo">
</picture>

Hinweis: Da diese Methode nicht mit manuellem Umschalten über localStorage etc. verknüpft ist (sie hängt nur von den OS-Einstellungen ab), müssen Sie bei der Implementierung einer manuellen Umschaltung die Bild-src dynamisch mit JS umschreiben oder display: none mit CSS-Klassen umschalten.

5.3 `currentColor`-Unterstützung für SVG-Icons

Für Inline-SVGs, die z. B. in Icons verwendet werden, ist es am elegantesten, die Füllfarbe an die Textfarbe des übergeordneten Elements zu koppeln. Geben Sie currentColor für die Attribute fill oder stroke des SVG an.

1
2
3
4


<!-- Der Wert der CSS color Eigenschaft (z.B. var(--text-primary)) wird automatisch angewendet -->
<svg viewBox="0 0 24 24" fill="currentColor">
 <path d="M12 2L2 22h20L12 2z" />
</svg>

Wenn nun in den Dark Mode gewechselt wird und die Textfarbe des übergeordneten Elements in das weiße Spektrum wechselt, ändert sich auch das SVG-Icon automatisch in das weiße Spektrum.

6. Fazit: Auf dem Weg zu einem nachhaltigen Dark-Mode-Design

Um in Blogs und Webanwendungen einen qualitativ hochwertigen Dark Mode zu implementieren, ist ein CSS-Design, das die folgenden Punkte abdeckt, unerlässlich:

Nutzung von CSS Custom Properties: Vermeiden Sie die feste Kodierung von Farbspezifikationen und abstrahieren Sie auf semantische Variablennamen (z.B. --bg-primary).
Einsatz des OKLCH-Farbraums: Entwerfen Sie ein sehr zugängliches Kontrastverhältnis (7:1 oder höher), das WCAG 2.1 AAA erfüllt, logisch in einem wahrnehmungsbezogen gleichmäßigen Farbraum.
Konsequente FOUC-Verhinderung: Eliminieren Sie das anfängliche Bildschirmflackern beim Laden vollständig durch die Kombination von SSR und Cookies oder durch blockierende Inline-Skripte im <head>.
Medien- und Asset-Optimierung: Nutzen Sie filter: brightness(), currentColor und <picture>-Tags, um auch Nicht-Text-Elemente in das dunkle Theme zu harmonisieren.

Diese feinen Anpassungen, die über eine bloße “Farbinvertierung” hinausgehen, sind die Voraussetzung für einen modernen Blog, der von den Nutzern geliebt wird und ein exzellentes, augenschonendes Leseerlebnis (Reading Experience) bietet. Entwickler, die den Dark Mode implementieren möchten, sollten die Designmuster in diesem Artikel als Referenz verwenden.

Grundlagen der Softwarearchitektur: Was ist Clean Architecture?

Sat, 12 Sep 2026 12:00:00 +0900

In der modernen Softwareentwicklung ist der Aufbau eines “veränderungsresistenten Systems” eine ständige Herausforderung. Änderungen der Geschäftsanforderungen, das Aufkommen neuer Frameworks, UI-Erneuerungen, Datenbankmigrationen. Für all diese Änderungen wird eine Architektur benötigt, die sich flexibel anpassen kann, ohne das gesamte System neu aufbauen zu müssen. Eine Antwort darauf ist die von Robert C. Martin (bekannt als Uncle Bob) vorgeschlagene Clean Architecture.

In diesem Artikel werden wir uns mit dem Wesen der Clean Architecture befassen, indem wir ihre Geschichte, ihren Zweck, die Details ihrer vier Schichten, die Abhängigkeitsregel und konkrete Implementierungsbeispiele betrachten. Wir werden eine sehr tiefe und detaillierte technische Erklärung liefern.

1. Probleme traditioneller Architekturen und die Geschichte der Clean Architecture

Historisch gesehen hat die Softwarearchitektur verschiedene Paradigmenwechsel erlebt. In frühen Systemen waren Geschäftslogik, UI und Datenzugriffscode eng miteinander gekoppelt (sogenannter Spaghetti-Code). Später, mit dem Ziel der Trennung von Anliegen (Separation of Concerns), wurde die 3-Schichten-Architektur (Präsentationsschicht, Geschäftslogikschicht, Datenzugriffsschicht) populär.

Die traditionelle 3-Schichten-Architektur hatte jedoch ein großes Problem: “Die Domäne (Geschäftslogik) wird von der Datenbank und dem Framework abhängig.”

Wenn beispielsweise die Geschäftslogikschicht die Datenzugriffsschicht (wie einen ORM) direkt aufruft, wirken sich Änderungen am Datenbankschema oder am ORM auf die Geschäftslogik aus. Das heißt, es entstand der Widerspruch, dass die “Geschäftsregeln”, die am wichtigsten sind und nicht geändert werden sollten, von der “Infrastruktur” abhängig wurden, in der technische Änderungen am wahrscheinlichsten auftreten.

Als Lösung dafür wurden Architekturen wie die folgenden konzipiert:

Hexagonale Architektur (Ports and Adapters) - Alistair Cockburn
Zwiebelarchitektur (Onion Architecture) - Jeffrey Palermo
DCI (Data, Context and Interaction) - James Coplien, Trygve Reenskaug
BCE (Boundary-Control-Entity) - Ivar Jacobson

Alle diese Architekturen haben dasselbe Ziel: die “Trennung von Anliegen (Separation of Concerns)”. Es geht darum, die Software in Schichten zu unterteilen, eine Umgebung zu schaffen, in der jede unabhängig testbar ist, und einen Zustand zu erreichen, in dem sie unabhängig von externen Agenten (UI, DB, Frameworks) ist.

Robert C. Martin integrierte diese hervorragenden architektonischen Konzepte, fasste sie zu einer einzigen praktischen Regel zusammen und nannte sie “Clean Architecture”.

2. Zweck und Merkmale der Clean Architecture

Ein System, das die Clean Architecture übernimmt, weist die folgenden Merkmale auf:

Unabhängig von Frameworks (Independent of Frameworks): Die Architektur hängt nicht von der Existenz von funktionsreichen Softwarebibliotheken ab. Dadurch können Frameworks als “Werkzeuge” verwendet werden, ohne das System in die Einschränkungen des Frameworks zwingen zu müssen.
Testbar (Testable): Die Geschäftsregeln können ohne die UI, Datenbank, den Webserver oder andere externe Elemente getestet werden.
Unabhängig von der UI (Independent of UI): Die UI kann leicht geändert werden, ohne den Rest des Systems zu ändern. Beispielsweise kann eine Web-UI durch eine Konsolen-UI ersetzt werden, ohne die Geschäftsregeln zu ändern.
Unabhängig von der Datenbank (Independent of Database): Oracle oder SQL Server können gegen Mongo, BigTable, CouchDB usw. ausgetauscht werden. Geschäftsregeln sind nicht an die Datenbank gebunden.
Unabhängig von externen Agenten (Independent of any external agency): Tatsächlich wissen die Geschäftsregeln überhaupt nichts über die Außenwelt.

3. Die 4 Schichten (Layers) der Clean Architecture

Die Clean Architecture wird typischerweise durch konzentrische Kreise dargestellt. Je näher man dem Zentrum kommt, desto mehr repräsentiert die Software Richtlinien auf höherer Ebene (hochabstrakte Geschäftsregeln). Je weiter man nach außen geht, desto mehr wird sie zu Mechanismen (konkreten Details).

graph TD
subgraph "External Interfaces (Frameworks & Drivers)"
A["Web"]
B["Benutzeroberfläche (UI)"]
C["Datenbank"]
D["Externe APIs"]
end
subgraph "Interface Adapters"
E["Controller"]
F["Gateways"]
G["Presenter"]
end
subgraph "Application Business Rules (Use Cases)"
H["Use-Case-Interaktoren"]
end
subgraph "Enterprise Business Rules (Entities)"
I["Entitäten"]
end
A --> E
B --> E
C --> F
D --> F
E --> H
F --> H
G --> H
H --> I

3.1. Entitäten (Entities)

Entitäten kapseln die unternehmensweiten Geschäftsregeln (Enterprise Business Rules). Eine Entität kann ein Objekt mit Methoden sein oder eine Menge von Datenstrukturen und Funktionen. Es sind die allgemeinsten und auf höchster Ebene angesiedelten Regeln, die von mehreren verschiedenen Anwendungen im Unternehmen wiederverwendet werden können. Selbst wenn Sie nur eine einzige Anwendung erstellen, sind die Entitäten die Geschäftsobjekte dieser Anwendung. Entitäten sind von externen Änderungen (wie Änderungen in der Seitennavigation oder bei der Sicherheit) absolut nicht betroffen.

3.2. Anwendungsfälle (Use Cases)

Die Use-Case-Schicht enthält anwendungsspezifische Geschäftsregeln (Application Business Rules). Hier werden alle Anwendungsfälle des Systems gekapselt und implementiert. Use Cases orchestrieren den Datenfluss zu und von den Entitäten und weisen diese an, ihre Geschäftsregeln anzuwenden, um die Ziele des Anwendungsfalls zu erreichen. Änderungen in dieser Schicht dürfen sich nicht auf die Entitäten auswirken. Ebenso wenig dürfen externe Änderungen an der Datenbank, der UI oder den Frameworks diese Schicht beeinflussen. Die Use Cases sind vollständig von diesen Belangen isoliert.

3.3. Schnittstellenadapter (Interface Adapters)

Die Schicht der Schnittstellenadapter ist eine Sammlung von Adaptern, die Daten von einem Format, das für die Use Cases und Entitäten bequem ist, in ein Format umwandeln, das für externe Agenten wie Datenbanken oder das Web am besten geeignet ist. Zum Beispiel gehören die Elemente der MVC (Model-View-Controller) Architektur einer GUI für das Web hierher. Der Controller nimmt die Eingaben des Benutzers entgegen, reicht sie an den Use Case weiter, und der Presenter nimmt die Ausgabe des Use Cases entgegen und formatiert sie für die Ansicht (UI). Es ist auch die Aufgabe dieser Schicht, Daten in ein Format zu konvertieren, das die Datenbank (wie SQL) versteht. Code, der weiter innen als diese Schicht liegt, sollte überhaupt nichts über die Datenbank wissen.

3.4. Frameworks und Treiber (Frameworks & Drivers)

Die äußerste Schicht besteht aus Werkzeugen wie Datenbanken und Web-Frameworks. Hier wird in der Regel wenig Code geschrieben, abgesehen von “Verbindungscode” (Glue-Code), um mit den inneren Kreisen zu kommunizieren. In dieser Schicht werden alle Details aufbewahrt. Das Web ist ein Detail. Die Datenbank ist ein Detail. Um den Schaden so gering wie möglich zu halten, platzieren wir diese Details auf der Außenseite.

4. Die Abhängigkeitsregel (The Dependency Rule)

Es gibt eine wichtigste Regel, die niemals gebrochen werden darf, damit die Clean Architecture funktioniert. Dies ist die “Abhängigkeitsregel (The Dependency Rule)”.

Quellcode-Abhängigkeiten dürfen nur nach innen (auf Richtlinien höherer Ebene) gerichtet sein.

Code in den inneren Kreisen darf absolut nichts über Code in den äußeren Kreisen wissen. Namen (Funktionen, Klassen, Variablen usw.), die in einem äußeren Kreis deklariert sind, dürfen von Code in einem inneren Kreis nicht erwähnt werden. Ebenso dürfen Datenformate, die in einem äußeren Kreis verwendet werden, nicht in einem inneren Kreis verwendet werden. Dies gilt insbesondere, wenn diese Formate durch ein Framework im äußeren Kreis generiert werden.

graph LR
A["Frameworks & Treiber"] -->| Abhängigkeit | B["Schnittstellenadapter"]
B -->| Abhängigkeit | C["Anwendungsfälle"]
C -->| Abhängigkeit | D["Entitäten"]
style A fill:#f9f9f9,stroke:#333,stroke-width:2px
style B fill:#e6f7ff,stroke:#333,stroke-width:2px
style C fill:#fff0f6,stroke:#333,stroke-width:2px
style D fill:#f6ffed,stroke:#333,stroke-width:2px

Mathematisch ausgedrückt: Wenn wir den Schichtindex als $L_i$ bezeichnen und $i=0$ als Entität (innerste Schicht) sowie $i=3$ als Framework (äußerste Schicht) definieren, dann muss für jede bestehende Abhängigkeit von einer Schicht $L_m$ zu $L_n$ immer die folgende Ungleichung gelten:

$$ m > n $$

Das heißt, der Vektor der Abhängigkeit $\vec{D}$ zeigt immer zum Zentrum.

5. Grenzen überschreiten: Das Dependency Inversion Principle (DIP)

Wenn man versucht, die Abhängigkeitsregel einzuhalten, stößt man sofort auf ein großes Problem: “Was tun, wenn der Use Case Daten aus der Datenbank abrufen muss?”

Wenn die Use-Case-Schicht (innen) direkt die Schnittstellenadapter-Schicht (die äußere Implementierung des Repositories) aufruft, würde die Abhängigkeit nach außen zeigen, was eine Verletzung der Abhängigkeitsregel wäre.

Die Lösung für dieses Problem ist das “D” aus den SOLID-Prinzipien (Dependency Inversion Principle: Prinzip der Abhängigkeitsumkehr).

Definition des Dependency Inversion Principle (DIP)

High-Level-Module sollten nicht von Low-Level-Modulen abhängen. Beide sollten von Abstraktionen abhängen.
Abstraktionen sollten nicht von Details abhängen. Details sollten von Abstraktionen abhängen.

Um dies zu erreichen, definieren wir eine Schnittstelle (Abstraktion) in der Use-Case-Schicht und implementieren diese Schnittstelle in der äußeren Schicht (Schnittstellenadapter). Die Use-Case-Schicht hängt nur von der selbst definierten Schnittstelle ab und nicht von konkreten Implementierungen auf der Außenseite.

classDiagram
class UseCaseInteractor {
- UserRepository repository
+ execute()
}
class UserRepository {
<<Interface>>
+ findById(id)
+ save(user)
}
class UserRepositoryImpl {
+ findById(id)
+ save(user)
}
UseCaseInteractor --> UserRepository : "Hängt ab von"
UserRepositoryImpl ..|> UserRepository : "Implementiert"
note for UseCaseInteractor "Innere Schicht (Use Case)"
note for UserRepository "Innere Schicht (Use Case)"
note for UserRepositoryImpl "Äußere Schicht (Schnittstellenadapter)"

Im obigen Diagramm verläuft der Kontrollfluss (Control Flow) zur Laufzeit von UseCaseInteractor $\rightarrow$ UserRepositoryImpl. Die Quellcode-Abhängigkeit (Source Code Dependency) verläuft jedoch von UserRepositoryImpl $\rightarrow$ UserRepository (nach innen). Durch den Einsatz von Polymorphismus konnte die Quellcode-Abhängigkeit entgegen dem Kontrollfluss ausgerichtet werden. Das ist der Grund, warum es als “Umkehrung der Abhängigkeit” bezeichnet wird.

6. Konkretes Implementierungsbeispiel mit TypeScript

Hier zeigen wir ein einfaches Implementierungsbeispiel (Benutzerregistrierungsfunktion) der Clean Architecture unter Verwendung von TypeScript.

6.1. Entitäten (Entities)

Dies sind die zentralsten Geschäftsregeln.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


// src/domain/entities/User.ts
export class User {
 constructor(
 public readonly id: string,
 public readonly name: string,
 public readonly email: string,
 public readonly createdAt: Date
 ) {}

 // Entitätsspezifische Geschäftsregeln (z.B. Überprüfung der Namenslänge usw.)
 public isValid(): boolean {
 return this.name.length >= 3 && this.email.includes('@');
 }
}

6.2. Anwendungsfälle (Use Cases)

In der Use-Case-Schicht definieren wir die Datenstrukturen für Eingabe und Ausgabe (DTOs) sowie die Repository-Schnittstelle, um die Abhängigkeit umzukehren.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59


// src/application/repositories/UserRepository.ts
import { User } from '../../domain/entities/User';

// Schnittstelle, die von der Use-Case-Schicht definiert wird
export interface UserRepository {
 findByEmail(email: string): Promise<User | null>;
 save(user: User): Promise<void>;
}

// src/application/usecases/RegisterUser/RegisterUserDTO.ts
export interface RegisterUserInputDTO {
 name: string;
 email: string;
}

export interface RegisterUserOutputDTO {
 id: string;
 name: string;
 email: string;
 createdAt: Date;
}

// src/application/usecases/RegisterUser/RegisterUserUseCase.ts
import { User } from '../../domain/entities/User';
import { UserRepository } from '../../repositories/UserRepository';
import { RegisterUserInputDTO, RegisterUserOutputDTO } from './RegisterUserDTO';

export class RegisterUserUseCase {
 // Hängt von der Abstraktion (Schnittstelle) ab. Nicht von der konkreten Implementierung.
 constructor(private readonly userRepository: UserRepository) {}

 public async execute(input: RegisterUserInputDTO): Promise<RegisterUserOutputDTO> {
 const existingUser = await this.userRepository.findByEmail(input.email);
 if (existingUser) {
 throw new Error('User already exists');
 }

 const newUser = new User(
 crypto.randomUUID(),
 input.name,
 input.email,
 new Date()
 );

 if (!newUser.isValid()) {
 throw new Error('Invalid user data');
 }

 // Ruft den Speichervorgang in der äußeren Datenbank auf, aber die Abhängigkeit zeigt nach innen (zur Schnittstelle)
 await this.userRepository.save(newUser);

 return {
 id: newUser.id,
 name: newUser.name,
 email: newUser.email,
 createdAt: newUser.createdAt
 };
 }
}

6.3. Schnittstellenadapter (Interface Adapters)

Wir erstellen die konkrete Zugriffsbearbeitung für die Datenbank (Repository-Implementierung) und den Controller zur Verarbeitung von HTTP-Anfragen.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42


// src/adapters/repositories/PostgresUserRepository.ts
import { UserRepository } from '../../application/repositories/UserRepository';
import { User } from '../../domain/entities/User';
// Nimmt einen DB-Client als äußere Schicht (Treiber) an
import { DatabaseClient } from '../../infrastructure/database/DatabaseClient';

export class PostgresUserRepository implements UserRepository {
 constructor(private readonly dbClient: DatabaseClient) {}

 public async findByEmail(email: string): Promise<User | null> {
 const record = await this.dbClient.query('SELECT * FROM users WHERE email = $1', [email]);
 if (!record) return null;
 return new User(record.id, record.name, record.email, record.created_at);
 }

 public async save(user: User): Promise<void> {
 await this.dbClient.query(
 'INSERT INTO users (id, name, email, created_at) VALUES ($1, $2, $3, $4)',
 [user.id, user.name, user.email, user.createdAt]
 );
 }
}

// src/adapters/controllers/UserController.ts
import { RegisterUserUseCase } from '../../application/usecases/RegisterUser/RegisterUserUseCase';

export class UserController {
 constructor(private readonly registerUserUseCase: RegisterUserUseCase) {}

 public async register(req: any, res: any): Promise<void> {
 try {
 const input = {
 name: req.body.name,
 email: req.body.email
 };
 const output = await this.registerUserUseCase.execute(input);
 res.status(201).json(output);
 } catch (error: any) {
 res.status(400).json({ message: error.message });
 }
 }
}

6.4. Hauptkomponente (Dependency Injection: DI)

Beim Starten der Anwendung werden alle Abhängigkeiten konstruiert (Wiring). Dies wird als Composition Root bezeichnet.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


// src/infrastructure/web/server.ts
import express from 'express';
import { DatabaseClient } from '../database/DatabaseClient';
import { PostgresUserRepository } from '../../adapters/repositories/PostgresUserRepository';
import { RegisterUserUseCase } from '../../application/usecases/RegisterUser/RegisterUserUseCase';
import { UserController } from '../../adapters/controllers/UserController';

const app = express();
app.use(express.json());

// 1. Initialisierung des Treibers
const dbClient = new DatabaseClient(/* Verbindungsinformationen */);

// 2. Initialisierung des Adapters (Instanziierung konkreter Klassen)
const userRepository = new PostgresUserRepository(dbClient);

// 3. Initialisierung des Use Cases (Injektion des Konkreten in die Schnittstelle = DI)
const registerUserUseCase = new RegisterUserUseCase(userRepository);

// 4. Initialisierung des Controllers
const userController = new UserController(registerUserUseCase);

// Routing
app.post('/users', (req, res) => userController.register(req, res));

app.listen(3000, () => {
 console.log('Server is running on port 3000');
});

Auf diese Weise übernimmt das äußerste “Startskript” die schmutzigen Details (Instanziierung konkreter Klassen) und übergibt den inneren Schichten nur saubere Schnittstellen. Diese Struktur stellt sicher, dass die Geschäftslogik vollständig von der Außenwelt isoliert ist.

7. Mathematische Betrachtung von Kopplung (Coupling) und Kohäsion (Cohesion)

Im Software-Engineering dienen Kopplung (Coupling) und Kohäsion (Cohesion) als Metriken zur Bewertung der Qualität einer Architektur.

Die Kopplung $C$ stellt die Stärke der Abhängigkeiten zwischen Modulen dar. Wenn Modul $A$ von Modul $B$ abhängt, die Gesamtzahl der Abhängigkeiten im System $N_{dep}$ ist und die Anzahl der Module $N_{mod}$ ist, kann einer der Indikatoren für die Komplexität wie folgt ausgedrückt werden:

$$ Complexity \propto \frac{N_{dep}}{N_{mod}} $$

In der Clean Architecture lenkt die Anwendung des DIP die physikalischen Abhängigkeitspfeile hin zu Abstraktionen. Die Änderungshäufigkeit (Instabilität: $I$) der Abstraktionen (Schnittstellen) ist so konzipiert, dass sie sehr gering ist.

Die Instabilität $I$ wird mit der folgenden Formel berechnet (definiert von Robert C. Martin):

$C_e$ (Efferent Coupling): Ausgehende Kopplung (Anzahl der Dinge, von denen ich abhänge)
$C_a$ (Afferent Coupling): Eingehende Kopplung (Anzahl der Dinge, die von mir abhängen)

$$ I = \frac{C_e}{C_e + C_a} $$

Wenn $I = 0$, ist die Komponente völlig stabil (sie hängt von nichts ab und wird von anderen als Abhängigkeit genutzt).
Wenn $I = 1$, ist die Komponente völlig instabil (niemand hängt von ihr ab, aber sie hängt von anderen ab).

Die “Entitätsschicht” der Clean Architecture hat $C_e = 0$ (keine Abhängigkeit nach außen), also ist $I = 0$. Das bedeutet, es ist die stabilste Schicht. Umgekehrt haben die “UI-Schicht” und die “DB-Schicht” $C_a \approx 0$ und $C_e > 0$, also ist $I \approx 1$, was sie zu leicht veränderbaren Schichten (instabilen Schichten) macht.

Ein wichtiges architektonisches Prinzip, das SDP (Stable Dependencies Principle), besagt: “Abhängigkeiten müssen in Richtung stabilerer Komponenten zeigen (Komponenten mit einem kleineren $I$)”. Die konzentrischen Kreise der Clean Architecture visualisieren genau dieses SDP und sind so gestaltet, dass die Abhängigkeiten von außen ($I=1$) nach innen ($I=0$) weisen.

8. Teststrategie und Clean Architecture

Einer der größten Vorteile der Clean Architecture ist ihre Testbarkeit. Da die Schichten getrennt sind, können Tests für jede Schicht unabhängig geschrieben werden.

8.1. Testen von Entitäten (Unit Test)

Da es sich um reine Logik ohne externe Abhängigkeiten handelt, werden weder eine DB noch Mocks benötigt. Es sind zuverlässige Tests, die extrem schnell ausgeführt werden können.

8.2. Testen von Use Cases (Unit Test with Mocks)

Da alle externen Abhängigkeiten wie Repositories als Schnittstellen definiert sind, müssen Sie beim Testen lediglich Test-Mocks oder In-Memory-Implementierungen (Fakes) injizieren (DI). Es ist nicht erforderlich, eine echte Datenbank zu starten. Dies ermöglicht ein schnelles Testen komplexer Verzweigungen und Ausnahmen in der Geschäftslogik.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


// Beispiel für einen Use-Case-Test (unter Annahme von Jest)
test('Es sollte ein Fehler auftreten, wenn versucht wird, sich mit einer bestehenden E-Mail-Adresse zu registrieren', async () => {
 // Erstellung eines Fake-Repositories
 const mockRepo: UserRepository = {
 findByEmail: async (email) => new User('1', 'Test', email, new Date()), // Gibt einen bestehenden Benutzer zurück
 save: async (user) => {}
 };

 const useCase = new RegisterUserUseCase(mockRepo);

 // Ausführung des Use Cases und Fehler-Assertion
 await expect(useCase.execute({ name: 'Bob', email: 'test@example.com' }))
 .rejects
 .toThrow('User already exists');
});

8.3. Testen von Adaptern (Integration Test)

Die Implementierungsklasse des Repositories stellt eine tatsächliche Verbindung zur Datenbank her, um zu testen, ob das SQL korrekt ist. Der Test für den Controller überprüft den Teil, der eine HTTP-Anfrage empfängt und JSON zurückgibt. Hier wird keine detaillierte Überprüfung der Geschäftslogik durchgeführt; es wird nur bestätigt, dass die “Konvertierung” und die “Kommunikation” korrekt sind.

9. Nachteile der Clean Architecture und wann man sie übernehmen sollte

Obwohl die Clean Architecture allmächtig erscheint, ist sie keine Silberkugel. Die folgenden Nachteile (Kompromisse) existieren:

Erhöhte anfängliche Lern- und Entwicklungskosten: Die Anzahl der Dateien und Schnittstellen (Abstraktionen) steigt signifikant an. Es gibt viel “Boilerplate-Code” (Standardcode) wie z.B. das Umpacken von DTOs.
Overkill für kleine Projekte: Für einen Prototyp, der in wenigen Tagen erstellt wird, oder ein einmaliges Werkzeug, bei dem kaum Änderungen zu erwarten sind, ist die Übernahme dieser Architektur oft mit unnötigen Kosten verbunden. Auch für einfache APIs, die nur CRUD-Operationen ausführen, ist sie ungeeignet.

Wann man sie übernehmen sollte:

Produkte, die voraussichtlich über einen langen Zeitraum (mehrere Jahre oder länger) gewartet und betrieben werden.
Systeme, in denen die Geschäftsregeln komplex sind und sich Spezifikationen häufig ändern.
Wenn eine Arbeitsteilung (Frontend, Backend, Infrastruktur usw.) in einem großen Entwicklungsteam gefördert werden soll.
Wenn komplexe Geschäftsbereiche in Kombination mit Domain-Driven Design (DDD) modelliert werden sollen.

10. Fazit

Die Clean Architecture ist eine Designphilosophie, die den Kern des Systems, nämlich die “Geschäftsregeln”, vor den “Details” wie der UI, Datenbanken und Frameworks schützt.

Ihr Kern besteht aus der Abhängigkeitsregel und dem Dependency Inversion Principle (DIP). Durch deren korrekte Anwendung wird die Software flexibel gegenüber Änderungen, einfacher zu testen und kann ihren Wert über einen langen Zeitraum erhalten.

Wichtig ist nicht, die Verzeichnisstruktur der Clean Architecture blind zu imitieren, sondern das Wesentliche zu verstehen – “warum es so aufgeteilt ist” und “wohin die Abhängigkeitspfeile zeigen” – und sie entsprechend der Größe und Komplexität des eigenen Projekts angemessen anzuwenden.

Referenz: “Clean Architecture: A Craftsman’s Guide to Software Structure and Design” von Robert C. Martin