Astro-Entwickler in Berlin

Eine Astro-Website ist zuerst ein Ordner mit Dateien. Ob sie in Berlin schnell und rechtssicher läuft, entscheidet sich an der Frage danach: Reicht ein statisches Hosting, oder braucht ein Teil der Seite Code, der bei jeder Anfrage läuft? Dann kommen ein Adapter, Umgebungsvariablen, Cache-Header und eine Region dazu. Auf dieser Seite gehe ich diese Punkte so durch, wie ich sie vor einem Projekt kläre. Die Technik stammt aus der Astro-Dokumentation und den Dokumentationen der Anbieter, die ich dafür abgerufen habe.

Ich bin Mariusz Szatkowski, ein einzelner Entwickler in Gdynia, und arbeite remote und schriftlich. Layout und Gestaltung liefern Sie, ich setze sie um.

#Wofür das in Berlin eine Rolle spielt

Das Amt für Statistik Berlin-Brandenburg weist auf seiner Seite zu den Unternehmen für Berlin im Jahr 2024 die Zahl 188.834 aus, gezählt als rechtliche Einheiten mit Beschäftigten oder Umsätzen. Die Zahl sagt nichts über Ihre Website. Sie zeigt nur, dass Berliner Firmen sehr unterschiedlich aufgestellt sind: Eine Kanzlei mit zehn Seiten hat andere Anforderungen an den Betrieb als ein Händler mit Kundenkonto. Deshalb beginne ich nicht bei der Plattform, sondern bei dem, was Ihre Seite zur Laufzeit tun muss.

#Standard: statisch, ohne Adapter

Laut Dokumentation zum Rendern auf Anfrage wird eine Astro-Website standardmäßig vollständig vorgerendert, der Ausgabemodus ist static. Das Ergebnis liegt nach dem Build laut Deploy-Anleitung im Ordner dist/, der sich über outDir ändern lässt. Diesen Ordner kann jeder Webserver ausliefern.

Der Vorteil für den Betrieb: Es gibt keinen Server, der gepatcht werden muss, und zur Laufzeit läuft kein Code, der Besucherdaten verarbeitet. Die Deploy-Anleitung führt eine Reihe von Anbietern, die nur statische Seiten unterstützen, darunter GitHub Pages und GitLab Pages. Die meisten großen Hoster in der Liste, darunter Cloudflare, Netlify und Vercel, unterstützen beides, statisch und auf Anfrage.

Für eine Unternehmensseite mit Leistungen, Referenzen, Blog und Kontaktformular reicht das oft. Das Formular braucht dann einen Dienst oder einen Endpunkt, aber das ist eine eigene Entscheidung, die ich mit Ihnen vorher festhalte.

#Wann ein Adapter nötig wird

Für Seiten, die erst bei der Anfrage entstehen, schreibt die Dokumentation einen Adapter vor: “To render any page on demand, you need to add an adapter.” Typische Gründe:

• ein Kundenbereich mit Anmeldung,
• Inhalte, die pro Besucher oder pro Anfrage verschieden sind,
• API-Endpunkte, die bei jedem Aufruf rechnen oder eine Datenquelle abfragen,
• Formulare und Aktionen, die serverseitig verarbeitet werden,
• Vorschauen für Redakteure, die ungebaute Entwürfe sehen sollen.

Der Wechsel ist kleiner, als er klingt. Mit export const prerender = false stellen Sie einzelne Seiten auf Anfrage um, der Rest bleibt statisch. Umgekehrt gibt es output: 'server', das alle Seiten auf Anfrage rendert; einzelne lassen sich mit export const prerender = true wieder vorrendern. Laut Dokumentation ändert server nur die Voreinstellung und fügt keine Funktion hinzu.

Astro pflegt offiziell Adapter für Node.js, Netlify, Vercel und Cloudflare. Was sie nach der jeweiligen Adapter-Dokumentation mitbringen:

Zwei Einschränkungen aus diesen Seiten, die in Angeboten gern fehlen. Der Cloudflare-Adapter unterstützt laut Dokumentation Cloudflare Pages nicht mehr, empfohlen wird Cloudflare Workers; die Anleitung für Cloudflare beschreibt dafür wrangler.jsonc und npx wrangler deploy. Und beim Node-Adapter lädt weder Astro noch der Adapter Umgebungsvariablen für Sie: Wer selbst hostet, muss sie über den Prozess, ein Werkzeug wie dotenvx oder die Docker-Konfiguration bereitstellen.

Foto: A.Savin, CC BY-SA 3.0, Wikimedia Commons.

#Umgebungsvariablen mit astro:env

Mit Zugangsdaten und Schlüsseln gehen Projekte am häufigsten schief: ein Token im Repository, ein Schlüssel im Browser-Bundle. Astro bietet dafür seit Version 5.0.0 das Modul astro:env, die Variablen werden in der Konfiguration als Schema beschrieben:

// astro.config.mjs
import { defineConfig, envField } from "astro/config";

export default defineConfig({
  env: {
    schema: {
      API_URL: envField.string({ context: "client", access: "public", optional: true }),
      API_SECRET: envField.string({ context: "server", access: "secret" }),
    },
    validateSecrets: true,
  },
});

Die Dokumentation unterscheidet drei Arten: öffentliche Variablen für den Client (astro:env/client), öffentliche und geheime Variablen für den Server (astro:env/server). Geheime Variablen für den Client gibt es nicht, weil es laut Dokumentation keinen sicheren Weg gibt, sie dorthin zu schicken. Im Code sieht das so aus:

---
import { API_SECRET } from "astro:env/server";
---

Was das gegenüber import.meta.env bringt, steht in der Anleitung zu Umgebungsvariablen: import.meta.env ersetzt Werte beim Build statisch, im Browser sind nur Variablen mit dem Präfix PUBLIC_ sichtbar. astro:env prüft Typ und Schema. Standardmäßig validiert Astro beim Start nur die öffentlichen Variablen; validateSecrets: true (laut Konfigurationsreferenz seit 5.0.0) prüft beim Start des Dev-Servers und beim Build auch die geheimen. Das ist für die Build-Pipeline nützlich: Ein fehlendes Secret bricht den Build ab, statt eine kaputte Seite auszuliefern.

Für Werte außerhalb des Schemas liest getSecret() aus astro:env/server den Rohwert. Die Referenz zum Modul empfiehlt es gegenüber process.env, weil der Adapter die Implementierung liefert und ein Wechsel des Anbieters den Aufruf nicht ändert. Beim Cloudflare-Adapter funktioniert astro:env laut Dokumentation mit Cloudflare-Variablen und -Secrets; Secrets setzen Sie dort mit der Wrangler-CLI, lokal über die Datei .dev.vars.

Was ich daraus mache: Ich lege das Schema zu Projektbeginn an, in .env.example stehen nur Namen ohne Werte, und die echten Werte tragen Sie oder ich im Anbieter ein, nie im Repository.

#Cache-Header: wer setzt sie wo

Hier unterscheiden sich die Betriebsarten am stärksten.

Statische Dateien. Auf Cloudflare gilt ohne eigene Regel laut Dokumentation zu Headern Cache-Control: public, max-age=0, must-revalidate: Der Browser darf speichern, muss aber jedes Mal prüfen. Eigene Regeln stehen in einer Datei _headers in public/, bis zu 100 Regeln mit je höchstens 2.000 Zeichen pro Zeile. Netlify kennt ebenfalls _headers im Veröffentlichungsordner oder [[headers]] in netlify.toml, siehe Dokumentation zu Headern.

Antworten aus Funktionen. Beide Anbieter schreiben dasselbe: Die Regeln der _headers-Datei gelten nicht für Antworten aus Worker- oder Function-Code. Netlify nennt ausdrücklich SSR-Seiten. Header setzen Sie dann im Code, in Astro auf der Seite mit Astro.response.headers. Das geht laut Dokumentation nur dort: Wenn die Komponentenlogik läuft, sind die Header schon gesendet, deshalb lassen sie sich in Layouts und Komponenten nicht ändern.

Node-Adapter. Im Modus standalone liefert der Server dist/client/ aus und setzt für die Dateien mit Hash im Namen unter _astro laut Dokumentation Cache-Control: public, max-age=31536000, immutable.

Adapter-Optionen. Netlify: cacheOnDemandPages: true cached auf Anfrage gerenderte Seiten bis zu einem Jahr, einzelne Seiten überschreiben das mit Headern wie CDN-Cache-Control. Vercel: isr cached sie wie vorgerenderte Seiten nach der ersten Anfrage, isr.expiration steuert die Dauer und isr.exclude nimmt Routen aus.

Route Caching in Astro. Seit Astro 7.0.0 gibt es laut Konfigurationsreferenz den Schlüssel cache. Die Anleitung zum Caching beschreibt eine plattformunabhängige Schnittstelle für Seiten und Endpunkte auf Anfrage: Mit Astro.cache.set() legen Sie maxAge, swr und tags fest, cache.invalidate() entwertet nach Tag oder Pfad. Es braucht einen Provider; memoryCache() ist eingebaut, die Anbieter für Netlify, Vercel und Cloudflare sind laut Anleitung experimentell und müssen manuell eingeschaltet werden. Im Dev-Server sind die Aufrufe wirkungslos, geprüft wird also mit Build und Vorschau. Für vorgerenderte Seiten sagt die Anleitung nichts.

Mein Vorgehen: Statische Seiten bekommen lange Laufzeiten nur für Dateien mit Hash im Namen, HTML wird kurz oder mit Revalidierung gecacht. Bei Seiten auf Anfrage lege ich pro Route fest, wie lange ein veralteter Stand ausgeliefert werden darf, und teste das gebaut, nicht im Dev-Server.

#EU-Region wählen

Bei statischen Dateien liefert das CDN vom Standort nahe dem Besucher. Eine Region wählen Sie nur dort, wo Code läuft.

Netlify. Die Dokumentation zu Functions nennt als Voreinstellung für neue Sites cmh (Ohio). Frankfurt heißt fra, Dublin dub, London lhr. Die Auswahl erfolgt unter Cloud compute, Functions, Region und gilt für alle Funktionen, ein neues Deployment ist nötig; laut Dokumentation steht das auf Pro- und Enterprise-Plänen zur Verfügung. Pro Funktion lässt sich die Region in netlify.toml setzen. Bei Frameworks, die ihre Funktionsdateien beim Build erzeugen, darunter Astro, geht nur die Einstellung für das ganze Projekt. Jede Funktion läuft in genau einer Region.

Cloudflare. Workers laufen laut Dokumentation zur Platzierung standardmäßig im Rechenzentrum, das der Anfrage am nächsten liegt. Mit placement in wrangler.jsonc lässt sich das verschieben, etwa mit mode: "smart" oder mit region in der Form anbieter:region. Der Zweck ist die Wartezeit zu Ihrer Datenbank, nicht die Eingrenzung der Verarbeitung auf ein Land. Wer Daten nur in der EU verarbeiten lassen will, braucht dafür die Vertragsunterlagen von Cloudflare, nicht diese Einstellung.

Vercel. Die Region der Functions und ihre Standardeinstellung habe ich bei der Migration ausführlich beschrieben, dort steht auch, wie Auftragsverarbeitung und Drittlandübermittlung zusammenhängen: Hosting und Datenstandort bei einer Migration nach Astro. Das wiederhole ich hier nicht.

Eigener Server. Mit dem Node-Adapter wählen Sie Standort und Anbieter selbst. Dafür gehören Betriebssystem, Node-Version und Proxy zu Ihrer Pflege, bei Bedarf übernehme ich sie im Rahmen der Wartung in Berlin.

Zuständig für Unternehmen in Berlin ist die Berliner Beauftragte für Datenschutz und Informationsfreiheit, die sich auf datenschutz-berlin.de als Aufsichtsbehörde beschreibt. Rechtliche Bewertungen gebe ich nicht ab; ich liefere die technischen Angaben, die Ihre Datenschutzberatung für die Dokumentation braucht.

#Prüfliste vor der Hosting-Entscheidung

#Wie ein Projekt mit mir abläuft

1. Sie schicken mir schriftlich die URL, das Ziel, den Termin und den aktuellen Stack.
2. Ich stelle meine Fragen in Textform: Was muss zur Laufzeit passieren, welche Daten fallen an, wer betreibt?
3. Sie erhalten eine schriftliche Einschätzung mit Annahmen und Umfang. Die erste ist unentgeltlich.
4. Ich baue auf einer Staging-Umgebung, Sie nehmen schriftlich ab.
5. Beim Livegang halte ich Hosting, Region, Variablen und Header in einer kurzen Betriebsdokumentation im Repository fest.
6. Auf Wunsch folgt die Wartung: Updates auf Staging getestet, Sicherung außerhalb des Hostings, Monitoring, monatlicher Bericht. Ein Stundenkontingent gilt nur für den jeweiligen Monat.

Layout und Texte liefern Sie. Ich arbeite remote, ohne Treffen und Anrufe.

#Häufige Fragen

#Brauche ich für eine Firmenwebsite überhaupt einen Adapter?

Meist nicht. Astro rendert standardmäßig alle Seiten beim Build vor, das Ergebnis sind Dateien, die jeder Webserver oder jedes CDN ausliefern kann. Einen Adapter brauchen Sie, sobald eine Seite erst bei der Anfrage entstehen soll, etwa ein Kundenbereich oder ein Endpunkt, der pro Besucher antwortet.

#Welcher Adapter ist der richtige?

Das entscheidet der Betrieb, nicht das Framework. Node passt, wenn Sie einen eigenen Server oder Container betreiben. Netlify, Vercel und Cloudflare passen, wenn der Anbieter Server, Zertifikate und Skalierung übernehmen soll. Ich vergleiche die Optionen anhand der Funktionen, die Ihre Seite wirklich braucht.

#Wohin gehören Zugangsdaten, Schlüssel und Tokens?

Nie in den Quellcode und nie in eine Variable, die der Browser sieht. Mit astro:env lege ich Zugangsdaten als Secret für den Server an. Ein Secret für den Client lässt Astro nicht zu. Wo die Werte beim Anbieter liegen, steht in dessen Konsole oder Konfiguration, nicht im Repository.

#Reicht es, bei Netlify oder Cloudflare Frankfurt einzustellen?

Es beantwortet nur, wo der Code läuft. Netlify legt Functions bei neuen Sites laut Dokumentation in Ohio ab, Frankfurt muss gewählt werden. Cloudflare führt Workers standardmäßig im Rechenzentrum nahe dem Besucher aus. Ob der Anbieter darüber hinaus Daten übermittelt, steht in seinem Auftragsverarbeitungsvertrag.

#Gelten die Cache-Header aus der Hosting-Konfiguration auch für Seiten mit Adapter?

Nicht überall. Bei Netlify und Cloudflare gelten die Header der Dateien _headers laut Dokumentation nur für statische Dateien, nicht für Antworten aus Funktionen oder Workern. Dafür setze ich Header im Code der Seite oder nutze, wo es passt, das Route Caching von Astro.

#Kann ich später von statisch auf Adapter wechseln?

Ja. Die Dokumentation beschreibt den Weg: Adapter ergänzen und einzelne Seiten mit export const prerender = false auf Anfrage umstellen. Der Rest der Website bleibt statisch.

#Weitere Astro-Themen aus der DACH-Region

Zu anderen Fragen rund um Astro gibt es eigene Seiten: Content Collections in Stuttgart, Islands in Wiesbaden, Formulare und Actions in Wuppertal, Starlight in Mannheim, View Transitions in Münster, Loader für Redaktionssysteme in Nürnberg, WordPress als Headless-Quelle in Wien, mehrsprachige Websites in Zürich und Layouts aus Komponenten in Basel. Wer von Next.js kommt, findet die Next.js-Seite für Berlin und die Migrationsseite.

#Schreiben Sie mir

Schicken Sie mir über das Kontaktformular die URL Ihrer Website, Ihr Ziel, Ihren Termin und den aktuellen Stack, bei einer neuen Seite auch, welche Daten sie verarbeiten soll. Ich lese Ihre Angaben, frage in Textform nach und antworte an Werktagen schriftlich. Mein erster schriftlicher Aufschlag zu Betriebsart, Umfang und Annahmen ist unentgeltlich. Wenn eine statische Seite ohne Adapter genügt, sage ich Ihnen das.