Astro-Entwickler in Karlsruhe

Mein Name ist Mariusz Szatkowski. Ich bin Einzelentwickler in Gdynia und arbeite seit 2006 mit WordPress und seit einigen Jahren mit Astro. Für Karlsruhe schreibe ich über etwas, das in älteren Astro-Projekten oft stillschweigend wächst: eigener Code zwischen Framework und Seite. Ein Skript, das nach dem Build läuft. Eine Regel in der Konfiguration. Eine Weiterleitung, die irgendwo im Hosting-Panel steht. Jedes Stück ist klein, zusammen werden sie zur Hürde beim nächsten Major-Upgrade. Meine Angaben stammen aus der Astro-Dokumentation und den Upgrade-Anleitungen, die Versionen aus der npm-Registry. Stand November 2026 ist dort Astro 7.4.11 die aktuelle Version.

#Wo welche Änderung hingehört

Astro bietet mehrere Stellen, an denen eigener Code eingreifen darf. Wer sie verwechselt, baut Umwege. Die Tabelle ordnet typische Aufgaben zu.

#Wann eine kleine Integration besser ist als ein Skriptstapel

Ein einzelnes Skript in package.json ist völlig in Ordnung. Ein Skriptstapel wie astro build && node a.js && node b.js && node c.js kippt aus zwei Gründen. Erstens laufen die Skripte außerhalb von Astro: Sie kennen weder outDir noch site noch die Liste der erzeugten Seiten und lesen sich diese Angaben aus Dateien oder Umgebungsvariablen zusammen. Zweitens hängt die Reihenfolge an der Shell, und ein Fehler in Skript zwei erscheint als Exit-Code ohne Zusammenhang.

Eine Integration hängt sich dagegen in die Phasen ein, die Astro ohnehin durchläuft, und bekommt dafür die passenden Daten übergeben. Jeder Hook erhält außerdem einen logger, sodass Meldungen im gewohnten Format der Astro-Ausgabe erscheinen. Das lohnt sich, sobald ein Projekt mehr als ein Nachbearbeitungsskript hat oder ein Skript Dinge braucht, die nur Astro weiß. Bei einem einzigen Skript, das eine Datei kopiert, bleibt es beim Skript.

#Die Hooks, die ich tatsächlich einsetze

Die Integration API kennt mehr Hooks, als die meisten Projekte brauchen. Diese vier tauchen bei mir regelmäßig auf:

Zwei Randnotizen. astro:build:setup ist laut Dokumentation die letzte Gelegenheit, die Vite-Konfiguration für den Build zu ändern; im Zweifel empfiehlt die Seite astro:build:start. Und astro:build:generated läuft vor dem Aufräumen der Build-Artefakte, ist aber laut Dokumentation ein sehr seltener Fall: Nehmen Sie astro:build:done, wenn Sie nicht zwingend an die Dateien davor müssen.

Ein kleines Beispiel, wie ich es als Datei im Repository ablegen würde. Die Integration trägt eine Middleware ein und schreibt nach dem Build die Liste der Seiten in eine Datei, die ein Test nach dem Deploy auswerten kann:

// integrations/site-tools.mjs
import { writeFile } from 'node:fs/promises';
import { fileURLToPath } from 'node:url';

/** @type {() => import('astro').AstroIntegration} */
export default () => ({
  name: 'site-tools',
  hooks: {
    'astro:config:setup': ({ addMiddleware }) => {
      addMiddleware({
        entrypoint: new URL('./middleware.mjs', import.meta.url),
        order: 'pre',
      });
    },
    'astro:build:done': async ({ pages, dir, logger }) => {
      const paths = pages.map((page) => page.pathname);
      await writeFile(fileURLToPath(new URL('pages.json', dir)), JSON.stringify(paths));
      logger.info(`${paths.length} Seiten in pages.json eingetragen`);
    },
  },
});

Eingetragen wird sie in der Konfiguration:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import siteTools from './integrations/site-tools.mjs';

export default defineConfig({ integrations: [siteTools()] });

Zwei Eigenheiten der Dokumentation stecken darin. order: 'pre' lässt die Middleware vor anderer Middleware laufen, 'post' danach. Und dir ist das Ausgabeverzeichnis des Clients: Was Sie dort ablegen, ist öffentlich erreichbar. Schreiben Sie in diesen Ordner nur, was jeder lesen darf. Wie eine solche Datei in einer Testkette verwendet wird, steht auf der Seite für Essen.

#Vite-Plugins in Astro

Astro baut auf Vite auf. Laut Dokumentation lassen sich Vite- und Rollup-Plugins einbinden, entweder direkt unter vite.plugins in der astro.config oder aus einer Integration heraus per updateConfig({ vite: { plugins: [...] } }) im Hook astro:config:setup. Das Rezept der Astro-Dokumentation zeigt es mit @rollup/plugin-yaml, damit sich eine .yml-Datei per import laden lässt. Für den Editor braucht es zusätzlich eine *.d.ts-Deklaration, sonst fehlen die Typen.

Der Vite-Leitfaden für Plugins beschreibt außerdem virtuelle Module: Ein Plugin kann Informationen aus der Build-Zeit über normale ESM-Importe an den Quellcode geben, etwa Build-Datum oder Versionsnummer. Die Konvention stellt der interne Bezeichner mit \0 voran. Das ist ein Muster, das ich nur dann einsetze, wenn die Information sonst zweimal gepflegt würde.

Mit Astro 7 ändert sich die Grundlage. Laut Upgrade-Anleitung nutzt Astro 7 Vite 8 als Dev-Server und Bundler. Das betrifft vor allem Integrationen und Plugins, die Interna von Vite verwenden. Die meisten Projekte kommen laut Anleitung ohne Anpassung durch. Wer ein eigenes Plugin pflegt, liest die Vite-8-Migrationsanleitung, bevor er auf Astro 7 geht. Der Vite-Leitfaden weist außerdem darauf hin, dass die Rolldown-Hooks pro Umgebung aufgerufen werden: Ein Plugin sollte nicht davon ausgehen, dass nur eine Umgebung läuft.

#Middleware: was sie bei einer statischen Seite tut

Eine Middleware ist eine Datei src/middleware.ts, die onRequest(context, next) exportiert. Sie kann die Antwort ändern, Daten in context.locals ablegen oder eine eigene Antwort zurückgeben. Entscheidend steht im ersten Absatz der Dokumentation: Das Rendern findet bei vorab erzeugten Seiten zur Build-Zeit statt, erst bei On-Demand-Seiten bei der Anfrage. Nur dann stehen Cookies und Header einer echten Anfrage zur Verfügung.

Für eine rein statische Seite heißt das: Eine Middleware kann beim Build Daten für Astro.locals bereitstellen, aber nicht auf Besucher reagieren. Das gilt auch für Weiterleitungen. Die Seite zur Render-Schnittstelle sagt, dass redirect() bei statisch erzeugten Routen einen Client-Redirect per <meta http-equiv="refresh"> erzeugt und keine Statuscodes unterstützt. Bei On-Demand-Routen ist ein Statuscode möglich, ohne Angabe wird 302 gesendet.

Wer feste alte Adressen weiterleiten will, nimmt deshalb zuerst redirects in der Konfiguration. Die Dokumentation erlaubt auch externe Ziele und dynamische Routen mit gleichen Parametern auf beiden Seiten. Beim Build entstehen entweder HTML-Dateien mit meta refresh oder, bei unterstützten Adaptern, die Konfigurationsdatei des Hosts. Seit Astro 5 stehen Weiterleitungen und injizierte Routen in derselben Prioritätsreihenfolge wie dateibasierte Routen; wer injectRoute() und redirects gemischt nutzt, prüft nach dem Upgrade, welche URL wohin führt.

Eine Middleware für Weiterleitungen sinnvoll ist, wenn die Regel nicht aus einer Liste besteht, sondern aus der Anfrage folgt. Das Beispiel dazu, das die Integration oben einhängt:

// integrations/middleware.mjs
import { defineMiddleware } from 'astro:middleware';

const moved = new Map([['/leistungen/webdesign', '/leistungen/webentwicklung/']]);

export const onRequest = defineMiddleware((context, next) => {
  const target = moved.get(new URL(context.request.url).pathname);
  return target ? context.redirect(target, 301) : next();
});

Ich lese den Pfad aus context.request.url, nicht aus Astro.url.pathname. Laut Upgrade-Anleitung zu Astro 6 können sich beide bei Prozent-kodierten Segmenten unterscheiden, weil die Route normalisiert wird. Für eine Weiterleitungsregel ist der ursprüngliche Pfad die verlässlichere Quelle. Bei mehreren Middleware-Funktionen verkettet sequence() sie in fester Reihenfolge; ab Astro 7 steht die Middleware in der Standard-Pipeline hinter Weiterleitungen aus der Konfiguration, Sitzungen und Actions und vor dem Rendern der Seite.

Zwei Fallen aus der Dokumentation. Erstens: locals lässt sich seit Astro 5 nicht mehr als Ganzes ersetzen. Wer früher context.locals = { ... } schrieb, muss Object.assign(context.locals, { ... }) verwenden. Zweitens: Reicht man next() einen Pfad für ein Rewrite, entsteht eine neue Anfrage. Das Lesen des Request-Bodys wirft danach einen Fehler, was vor allem Actions mit HTML-Formularen trifft; die Dokumentation empfiehlt dafür Astro.rewrite() im Template. Ob eine Middleware auf Fehlerseiten läuft, entscheidet außerdem der Adapter, wie die Seite zu Error pages festhält.

Wie man Seiten On-Demand mit einem Adapter betreibt, steht auf der Seite für Berlin. Sicherheits-Header gehören bei einer statischen Seite meist ins Hosting und sind auf der Seite für Frankfurt beschrieben.

#Sprache erkennen: Hinweis statt Umleitung

Astro bringt für mehrsprachige Seiten ein eigenes Routing mit. Setzt man routing: "manual", schaltet Astro laut Dokumentation seine i18n-Middleware ab, und die Logik liegt bei Ihnen. Die Spracherkennung selbst ist nur bei On-Demand-Seiten möglich: Astro.preferredLocale und Astro.preferredLocaleList werten den Header Accept-Language aus. Alle Seiten, auch vorab gerenderte, kennen dagegen Astro.currentLocale.

Technisch ist eine Umleitung nach Browsersprache also einfach. Ob sie sinnvoll ist, ist eine andere Frage. Google schreibt in der Dokumentation zu sprach- und länderabhängigen Seiten, dass der Crawler mit Adressen aus den USA kommt und ohne Accept-Language anfragt, sodass nicht alle Inhalte für alle Regionen gecrawlt oder indexiert werden müssen. Empfohlen werden getrennte URLs je Sprache mit rel="alternate" und hreflang. Ich baue deshalb meist keine erzwungene Umleitung, sondern einen Hinweis mit Link zur passenden Sprachfassung. Das Zusammenspiel von Sprachversionen und hreflang beschreibt die Seite für Zürich.

Foto: H. Zell, CC BY-SA 3.0, Wikimedia Commons.

Wo die Frage nach der Sprache in Karlsruhe konkret wird, zeigt die Seite der Stadt zur internationalen Wirtschaft. Dort beschreibt die Wirtschaftsförderung den PAMINA Business Club als Netzwerk, das Wirtschaft, Wissenschaft und Verwaltung in Nordbaden, der Südpfalz und im Nord-Elsass verbindet. Mehr als 50 Wirtschaftsförderungsgesellschaften, Kammern und Gemeinden sind laut der Seite Mitglied. Außerdem nennt sie ein digitales Willkommensportal der TechnologieRegion Karlsruhe für zugezogene internationale Fachkräfte. Ob Ihre Seite deshalb eine zweite Sprache braucht, entscheiden Ihre Besucher und Ihr Vertrieb, nicht die Technik. Wenn ja, ist die Reihenfolge: erst URL-Struktur und hreflang, dann, falls überhaupt, ein Hinweis per Middleware.

#Eigenen Code über Astro-Majors aktualisierbar halten

Astro 5 erschien laut npm-Registry am 3. Dezember 2024, Astro 6 am 10. März 2026 und Astro 7 am 22. Juni 2026. Das sind drei Majors in rund 19 Monaten. Die Upgrade-Anleitungen zeigen, was dabei eigenen Integrationscode traf:

Daraus folgen fünf Regeln, nach denen ich eigenen Code baue:

1. Nur dokumentierte Hooks und Optionen. Alles, was Astro nicht als öffentliche API beschreibt, kann im nächsten Major verschwinden. Die Upgrade-Anleitung von Astro 6 nennt etwa ausdrücklich Interna von astro:actions, die entfernt wurden.
2. Ein Ordner, eine Datei pro Zweck. Der gesamte eigene Code liegt in integrations/. Beim Upgrade ist klar, wo gesucht werden muss.
3. Typen aus Astro. Mit AstroIntegration und defineMiddleware meldet der Compiler Signaturänderungen beim Build. Wie ich Typen in einem Astro-Projekt einsetze, beschreibt die Seite für Bielefeld.
4. Ein Test, der die Ausgabe prüft. Bei der Integration oben: Die Anzahl der Einträge in pages.json muss zur Anzahl der Dateien im Ausgabeordner passen. Fehlt der Hook, schlägt der Test fehl, nicht erst der Besucher.
5. Upgrade in einer Testumgebung, mit dem offiziellen Befehl. Die Anleitung empfiehlt npx @astrojs/upgrade, das Astro und die offiziellen Integrationen gemeinsam aktualisiert. Danach lese ich den Abschnitt zu Integration API, Build und Vite, bevor eine Zeile Produktion berührt wird.

Wenn ein Projekt Inhalte aus einem CMS holt und dafür einen Loader statt einer Integration braucht, ist das ein anderes Werkzeug. Es steht auf der Seite für Nürnberg. Und wenn die Suchmaschinenoptimierung der Anlass ist, etwa eine Sitemap, die eine Integration erzeugt, ist die Seite für Genf die bessere Quelle.

#Checkliste vor dem Projekt

#So läuft ein Projekt mit mir

Ich arbeite allein, remote und schriftlich. Es gibt keine Termine und keine Telefonate, jede Entscheidung bleibt nachlesbar.

1. Anfrage. Sie schreiben mir, welche Astro-Version läuft, was heute nach dem Build passiert und was zuletzt beim Upgrade schiefging.
2. Fragen. Ich frage schriftlich nach Zugang zum Repository, zur Build-Pipeline und zum Hosting.
3. Umfang. Sie bekommen eine schriftliche Einschätzung mit Annahmen und Ausschlüssen.
4. Umsetzung in einer Testumgebung. Die Integration entsteht auf einem Branch, mit Build-Test.
5. Abnahme. Sie prüfen auf einer Staging-Adresse. Nach Ihrer Freigabe geht es in die Produktion.
6. Übergabe. Der Code liegt in Ihrem Repository, dazu eine kurze schriftliche Anleitung. Eine Wartung danach ist optional; wie sie aussieht, steht bei der WordPress-Wartung in Karlsruhe beschrieben, die Methode ist bei Astro dieselbe.

Gestaltung, Mockups und Wireframes liefern Sie selbst. Ich setze Ihr Layout um und ändere es nicht.

#Was ich von Ihnen brauche

• Lesezugriff auf das Repository und die Build-Konfiguration.
• Die Astro-Version aus der package.json und die Hosting-Art.
• Eine Liste der Skripte, die nach dem Build laufen, und der Weiterleitungen, die heute irgendwo gepflegt werden.
• Eine Person auf Ihrer Seite, die Entscheidungen trifft und den Staging-Stand abnimmt.

Die Core Web Vitals (LCP bis 2,5 s, INP bis 200 ms, CLS bis 0,1 laut web.dev) messe ich vor und nach dem Eingriff, damit sichtbar bleibt, ob eine Middleware die Auslieferung verlangsamt hat.

#Häufige Fragen

#Brauche ich für Weiterleitungen eine Middleware?

Meist nicht. Für eine feste Liste alter Adressen reicht redirects in der astro.config. Laut Dokumentation schreiben unterstützte Adapter daraus die Konfiguration des Hosts, ohne Adapter entstehen HTML-Dateien mit meta refresh. Eine Middleware lohnt sich, wenn die Entscheidung von der Anfrage abhängt, etwa von einem Cookie oder einem Header, und die Seite On-Demand gerendert wird.

#Läuft eine Middleware auch bei einer rein statischen Astro-Seite?

Ja, aber nur beim Build. Laut Dokumentation läuft sie bei vorab gerenderten Seiten zur Build-Zeit. Cookies und Header einer echten Anfrage gibt es dort nicht. Für Entscheidungen pro Anfrage brauchen Sie On-Demand-Rendering mit einem Adapter.

#Kann eine Middleware die Sprache der Besucher erkennen und umleiten?

Technisch ja, bei On-Demand-Seiten über Astro.preferredLocale. Ich rate meist von einer erzwungenen Umleitung ab. Google weist darauf hin, dass Seiten, die je nach Land oder Sprache anderen Inhalt liefern, womöglich nicht vollständig gecrawlt und indexiert werden, und empfiehlt getrennte URLs mit hreflang. Ein Hinweis mit Link auf die passende Sprache ist sicherer.

#Muss ich eine Integration als npm-Paket veröffentlichen?

Nein. Eine Integration ist ein Objekt mit Namen und Hooks. Sie kann als Datei im Repository liegen und in der astro.config eingetragen werden. Das Paket mit dem Schlüsselwort astro-integration brauchen Sie nur, wenn astro add sie installieren soll.

#Was passiert mit meiner eigenen Integration bei einem Astro-Update?

Das hängt davon ab, welche Teile der API sie nutzt. Dokumentierte Hooks bleiben meist stabil, Interna nicht: Astro 6 hat zum Beispiel routes im Hook astro:build:done entfernt, Astro 7 stellt auf Vite 8 um. Ich prüfe vor jedem Major-Upgrade die Upgrade-Anleitung auf den Abschnitt zur Integration API und baue die Seite danach in einer Testumgebung.

#Welche Datenschutzaufsicht ist für einen Betrieb in Karlsruhe zuständig?

Für nicht-öffentliche Stellen mit Sitz in Baden-Württemberg der Landesbeauftragte für den Datenschutz und die Informationsfreiheit (LfDI BW). Nach seiner Seite zu Aufgaben und Zuständigkeiten kontrolliert er dort ansässige Unternehmen und Vereine. Schreibt eine Middleware personenbezogene Daten in ein Protokoll, sollten Sie das mit Ihrer Rechtsberatung klären. Ich liste, welche Daten der Code anfasst.

#Ihr Projekt in einer Nachricht

Über das Kontaktformular erreichen Sie mich. Nennen Sie die Adresse des Repositories oder der Seite, die Astro-Version, was nach dem Build läuft und Ihren Termin. Meine Antwort kommt schriftlich: erst Rückfragen, dann eine Einschätzung des Umfangs. Schon die erste schriftliche Einschätzung ist gratis und verpflichtet Sie zu nichts. Alle Astro-Leistungen im Überblick finden Sie auf der Seite Astro-Entwickler.