Der Build ist grün. Das Deploy läuft durch. Dann fällt im Browser auf, dass zwischen zwei Links ein Leerzeichen fehlt. Oder der Server findet plötzlich keine index.html mehr im Root. Wer Astro einsetzt, landet früher oder später im dist Ordner und fragt sich, was da eigentlich passiert ist. Mit Astro 7 lohnt sich der Blick dorthin mehr als je zuvor.
KI Workshop am Hockenheimring für euer ganzes Team
Zwei Workshoptage, zwei Räume, ein Unternehmen. Die Fachabteilungen bauen mit Roland eigene KI Tools als Astro App, die Developer lernen mit Benjamin Klein Agentic Coding mit Guardrails:
- Alle Abteilungen: eigene Tools für echte Aufgaben statt einzelner Chatbots
- Developer: KI Agenten mit Quality Gates, die Code für Production liefern
- Abends: E Kart auf der Strecke und eine Führung hinter die Kulissen
- Termin: wird mit euch abgestimmt, aktuelle Termine auf Anfrage
Der dist Ordner in dreißig Sekunden
astro build rendert jede Seite zu HTML und legt alles in dist ab. Ohne Adapter ist das eine flache Struktur. Das HTML liegt im Root und folgt dem Routing aus src/pages.
- HTML Dateien: eine pro Route, standardmäßig als
about/index.html - _astro: CSS, JavaScript und optimierte Bilder mit Content Hash im Namen
- Dateien aus public: werden 1 zu 1 kopiert, ohne Hash und ohne Optimierung
Der Hash ist der eigentliche Trick. Ändert sich eine Datei, ändert sich ihr Name. Deshalb dürfen Dateien in _astro sehr lange im Browser Cache liegen. Das HTML bekommt kurze Cache Zeiten, weil es auf die neuen Namen zeigt. Alle Optionen und Codebeispiele haben wir auf der Seite Astro Static Site Build und dist Ordner Struktur gesammelt.
Was Astro 7 im Output verändert
Astro 7 ist ein Release für Tempo. Ein neuer Compiler in Rust, Markdown über eine Rust Pipeline und Vite 8 mit Rolldown. Das Astro Team nennt in seinen Benchmarks 15 bis 61 Prozent schnellere Builds. Nachzulesen im offiziellen Astro 7 Blogpost.
Die Ordner bleiben gleich. Der Inhalt der Dateien kann sich trotzdem ändern:
- Kein HTML Fix mehr: Der alte Compiler hat kaputtes Markup still repariert. Der neue reicht es durch. Offene Tags brechen jetzt den Build.
- Leerzeichen nach JSX Regeln:
compressHTMLsteht per Default auf'jsx'. Zwei Inline Elemente auf getrennten Zeilen kleben dann zusammen. Abhilfe schafft ein explizites{" "}odercompressHTML: true. - Sätteri für Markdown: Remark und Rehype Plugins brauchen jetzt
@astrojs/markdown-remarkmit demunified()Processor. - CSS sieht anders aus: Farben und
url()Werte können anders geschrieben sein. Optisch gleich, aber String Vergleiche in Tests schlagen an.
Die vollständige Liste steht im Upgrade Guide für Astro 7. Wer noch @astrojs/db nutzt, muss umziehen. Unser Weg ist SQLite mit Drizzle direkt im Astro Projekt.
Wenn plötzlich client und server auftauchen
Das ist der Klassiker. Im Projekt steht noch ein Adapter, etwa @astrojs/node, obwohl die Seite rein statisch ist. Dann teilt Astro den Output in dist/client und dist/server. Das Deploy Skript kopiert dist und findet im Root kein HTML.
Die Lösung ist meist kurz. Braucht ihr kein Rendern pro Request, fliegt der Adapter raus. Braucht ihr es doch, startet die Runtime über dist/server/entry.mjs, und dist/client wird als statische Dateien ausgeliefert. Wer auf GitHub Pages deployt, braucht zusätzlich eine leere .nojekyll Datei in public. Sonst blendet Jekyll den Ordner _astro aus.
Der Build Cache gehört in die Pipeline
Astro legt Zwischenstände in node_modules/.astro ab. Seit Astro 7.2 gibt es dazu ein experimentelles Flag für Incremental Builds. Seiten aus getStaticPaths() mit einem cacheKey werden übersprungen, wenn sich weder Daten noch Code geändert haben.
- Flag setzen:
experimental.incrementalBuild: truein derastro.config.mjs. - cacheKey liefern: etwa einen Zeitstempel aus dem CMS oder den
digesteines Content Eintrags. - Cache Ordner sichern: In der CI genau diesen einen Ordner zwischen den Läufen cachen.
Ein Haken bleibt. Änderungen an der Middleware invalidieren den Cache nicht. Dann hilft astro build --force. Alle Details stehen in der Doku zu Incremental Builds. Weil das Feature experimentell ist, schalten wir es nur mit Tests in der Pipeline ein.
Wie wir den Output absichern
Ein grüner Build sagt wenig über das, was im Browser ankommt. Bei uns läuft deshalb eine feste Kette. Vor dem Build prüfen TypeScript im strict Mode und Vitest den Code. Nach dem Build startet astro preview, und Cypress läuft gegen den fertigen Output.
Gerade nach einem großen Upgrade lohnt sich ein Vergleich vorher und nachher. Fehlende Leerzeichen oder verrutschte Elemente findet ein Screenshot Vergleich schneller als jedes Review. Barrierefreiheit prüfen wir im selben Lauf, so wie bei den Accessibility Testing Tools beschrieben. Was bei jedem Push passiert, steht im Beitrag zu Quality Gates in der Pipeline.
Mehr zu Astro bei Never Code Alone
Einen Einstieg in das Framework gibt die Seite Astro als Static Site Generator. Wie JavaScript nur dort landet, wo es gebraucht wird, zeigt Astro Islands und Performance Architektur. Script Tags ohne Überraschungen erklärt Astro Script Tag für Production. Alle Frontend Themen sammelt die Übersicht Frontend Development.
Zwei Tage KI für das ganze Unternehmen am Hockenheimring
Die meisten Firmen schulen nur ihre Developer. Am Hockenheimring lernt das ganze Team. Die Fachabteilungen bauen mit Roland eigene Tools, die danach im Alltag laufen. Die Developer lernen mit Benjamin Klein, wie KI Agenten mit Guardrails Code für Production liefern. Abends geht es auf die E Kart Bahn und hinter die Kulissen der Rennstrecke.
Der Termin wird mit euch abgestimmt, aktuelle Termine auf Anfrage. Das Vorgespräch ist kostenlos.
Häufige Fragen zum Astro dist Ordner
Wie sieht der Astro dist Ordner 2026 aus?
Ohne Adapter ist er flach. HTML Dateien liegen im Root und folgen dem Routing aus src/pages. CSS, JavaScript und optimierte Bilder landen mit Content Hash im Ordner _astro. Dateien aus public kopiert Astro unverändert. Mit Adapter teilt Astro den Output in dist/client und dist/server.
Was ändert Astro 7 am Build Output 2026?
Die Ordnerstruktur bleibt gleich. Der Rust Compiler korrigiert kein ungültiges HTML mehr, compressHTML entfernt Leerzeichen nach JSX Regeln, und Markdown läuft über Sätteri. CSS Werte können anders serialisiert sein. Gebündelt wird mit Vite 8 und Rolldown, was Builds laut Astro Team deutlich schneller macht.
Warum fehlen nach dem Astro 7 Upgrade Leerzeichen 2026?
Der Default von compressHTML ist jetzt ‚jsx‘. Leerzeichen zwischen Inline Elementen auf getrennten Zeilen fallen dabei weg, so wie in React. Setzt das Leerzeichen explizit mit {“ „} oder stellt compressHTML auf true, um das alte Verhalten zurückzuholen.
Warum erzeugt Astro 2026 einen client und server Ordner?
Die Aufteilung entsteht, sobald ein Adapter in der Config steht. dist/client enthält Assets und prerenderte Seiten, dist/server den Code für das Rendern pro Request. Wer rein statisch deployen will, entfernt den Adapter. Dann liegt das HTML wieder direkt im Root von dist.
Wie beschleunige ich den Astro Build in der CI 2026?
Cacht den Ordner node_modules/.astro zwischen den Läufen. Mit dem experimentellen Flag incrementalBuild überspringt Astro Seiten aus getStaticPaths, wenn cacheKey und Code unverändert sind. Das Upgrade auf Astro 7 bringt zusätzlich Tempo. Den dist Ordner selbst cacht ihr nicht.
