Astro-Entwickler in Bielefeld

Ich bin Mariusz Szatkowski, arbeite seit 2006 mit WordPress und baue heute Websites mit Astro. Ich sitze in Gdynia in Polen und arbeite vollständig remote und schriftlich, als einzelner Entwickler. Diese Seite hat ein Thema: wie ein Astro-Projekt so eingerichtet wird, dass es nach der Übergabe wartbar bleibt. Das heißt strikte TypeScript-Einstellungen, eine Typprüfung vor dem Build, typisierte Props und Konfiguration, einheitlicher Code und eine automatische Prüfung vor jedem Deployment.

#Warum Typen bei einer Übergabe zählen

Die Wirtschaftsförderung WEGE nennt auf ihrer Standortseite für die Bielefelder IT-Wirtschaft rund 220 kleine und mittelständische Unternehmen mit 6.196 Beschäftigten, Stand 30. Juni 2025. Der Anteil der IT-Dienstleistungen an der Beschäftigung liegt mit 3,1 Prozent über dem Durchschnitt von Nordrhein-Westfalen und Deutschland. Zudem nennt WEGE das IT-Kompetenznetzwerk BIKONET als Plattform der Branche in der Stadt und der Region.

Für Ihre Website heißt das: Wer sie in Bielefeld betreibt, hat die Wahl, die Pflege nach dem Launch an einen Dienstleister vor Ort oder an die eigene IT zu geben. Diese Person kennt mein Projekt nicht. Ohne Typen und Prüfungen muss sie erst raten, welche Felder eine Komponente erwartet und welche Variable fehlt. Mit ihnen sagt der Editor es ihr, und der Build sagt es noch einmal.

Foto: Daniel Schwen, CC BY-SA 3.0, Wikimedia Commons.

#Welche tsconfig-Vorlage: base, strict oder strictest

Astro bringt laut TypeScript-Anleitung drei erweiterbare Vorlagen mit: base, strict und strictest. Die Dokumentation empfiehlt strict oder strictest, wenn Sie TypeScript im Projekt schreiben. Die Vorlagen stehen im Astro-Repository, ich habe sie dort gelesen:

Die Einrichtung ist eine Zeile:

{
  "extends": "astro/tsconfigs/strictest",
  "include": [".astro/types.d.ts", "**/*"],
  "exclude": ["dist"]
}

include und exclude empfiehlt die Dokumentation, damit Astro-Typen eingebunden und gebaute Dateien nicht geprüft werden. Was strict laut TypeScript-Referenz bedeutet: Die Option schaltet eine ganze Familie von Prüfungen gleichzeitig ein, darunter strictNullChecks und noImplicitAny. Spätere TypeScript-Versionen können dort weitere Prüfungen ergänzen, ein Update kann also neue Fehler melden.

Zwei Optionen aus strictest verändern den Code am stärksten:

• noUncheckedIndexedAccess fügt jedem Zugriff über einen Index undefined hinzu. produkte[0].titel meldet dann einen Fehler, bis der Fall “Liste ist leer” behandelt ist. Das ist genau der Fehler, der auf einer Live-Seite als leere Fläche auftaucht.
• exactOptionalPropertyTypes unterscheidet “Feld fehlt” von “Feld ist undefined”. Laut TypeScript-Dokumentation zeigt sich der Unterschied etwa bei "feld" in objekt.

Dazu kommt verbatimModuleSyntax. Die Astro-Dokumentation empfiehlt, Typen mit import type zu importieren, damit der Bundler sie nicht als JavaScript behandelt, und nennt die Option als in allen Vorlagen aktiviert.

Bestehendes Projekt: Ich starte mit strict, lasse astro check laufen und schalte die Optionen aus strictest einzeln zu. Jede Option ist ein eigener Schritt mit eigener Fehlerliste, nicht ein Block mit dreihundert Meldungen.

#astro check: die Prüfung, die der Build nicht macht

Die Anleitung sagt es klar: astro dev und astro build wandeln den Code mit esbuild um, prüfen aber keine Typen. Ein falscher Prop-Name baut also fehlerfrei und fällt erst im Browser auf. tsc im Terminal ignoriert laut Dokumentation .astro-Dateien. Für beides gibt es den Befehl astro check.

Laut CLI-Referenz führt er Diagnosen über das Projekt aus, meldet Fehler in der Konsole und beendet sich bei Fehlern mit Exit-Code 1. Er ist ausdrücklich für CI-Abläufe gedacht. Die Dokumentation schlägt vor, das Build-Skript so zu ändern:

{
  "scripts": {
    "build": "astro check && astro build"
  }
}

Damit stoppt ein Typfehler den Build, bevor etwas ausgeliefert wird. Weitere Punkte aus der Referenz:

• --minimumFailingSeverity warning lässt den Befehl auch bei Warnungen scheitern, Standard ist error. Ich nutze das auf Wunsch, wenn ein Projekt komplett sauber sein soll.
• astro sync erzeugt .astro/types.d.ts und die Typen für astro:content, astro:env und astro:actions. astro dev, astro build und astro check rufen es selbst auf.
• Für Vue- und Svelte-Dateien nennt die Anleitung vue-tsc und svelte-check als zusätzliche Werkzeuge.

Eine Falle bei den Versionen, Stand 11.11.2026: In der npm-Registry steht TypeScript 7.0.2 als aktuelle Version. Das Paket @astrojs/check (aktuell 0.9.12, veröffentlicht am 21.10.2026) erklärt als Peer-Abhängigkeit aber typescript in Version ^5.0.0 || ^6.0.0. Ein blindes Update auf die neueste TypeScript-Version kann deshalb die Installation oder die Prüfung stören. Ich trage die Hauptversion im Projekt fest ein, und die Übergabe-Notiz nennt sie.

#Typisierte Props und typisierte Routen

Eine Komponente bekommt ein Props-Interface im Frontmatter. Das ist das Beispiel aus der Astro-Dokumentation, leicht auf einen Ansprechpartner übertragen:

---
interface Props {
  name: string;
  rolle?: string;
}

const { name, rolle = "Vertrieb" } = Astro.props;
---
<p>{name}, {rolle}</p>

Wer die Komponente falsch einsetzt, sieht den Fehler im Editor und bei astro check. Drei Hilfen aus astro/types, die die Dokumentation nennt und die ich oft brauche:

• HTMLAttributes<"a"> für Komponenten, die ein HTML-Element umhüllen: Die gültigen Attribute kommen dann ohne Handarbeit mit.
• ComponentProps<typeof Button>, um die Props einer anderen Komponente zu verwenden, auch wenn sie ihren Typ nicht exportiert.
• GetStaticPaths mit InferGetStaticParamsType und InferGetStaticPropsType, damit Astro.params und Astro.props in dynamischen Routen den Typ der Funktion erben statt eines handgeschriebenen Duplikats.

Ein Hinweis aus der Dokumentation, der oft übersehen wird: Eine Komponente ohne Props bekommt type Props = Record<string, never>, dann meldet schon ein überzähliges Attribut einen Fehler.

#Typisierte Inhalte

Props sind nur die halbe Kette. Die Inhalte, die in sie fließen, stehen in Markdown oder kommen aus einem CMS. Astro prüft sie mit Content Collections und einem Zod-Schema, und strict oder strictest bringen laut Dokumentation die TypeScript-Einstellungen mit, die Collections brauchen. Wie Schema und Loader aufgebaut sind, beschreibt meine Seite für Content Collections in Stuttgart. Für Formulare, deren Eingaben beim Absenden geprüft werden, steht das Gegenstück auf der Seite zu Formularen und Actions in Wuppertal.

#Konfiguration mit astro:env: ein Schema statt verstreuter Variablen

Ohne Schema liest der Code import.meta.env.IRGENDWAS, und ein Tippfehler liefert still undefined. Seit Astro 5.0.0 gibt es dafür astro:env. Laut Anleitung legen Sie im Schema in astro.config.mjs für jede Variable Kontext (client oder server), Zugriff (secret oder public) und Datentyp fest:

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

export default defineConfig({
  env: {
    validateSecrets: true,
    schema: {
      FORMULAR_URL: envField.string({ context: "server", access: "public" }),
      FORMULAR_TOKEN: envField.string({ context: "server", access: "secret" }),
      KARTEN_ZOOM: envField.number({ context: "client", access: "public", default: 12 }),
    },
  },
});

Im Code kommen die Werte typisiert aus astro:env/server oder astro:env/client. Wichtig ist, was die Dokumentation zu den Arten festhält:

Secrets für den Client gibt es nicht: Die Dokumentation begründet das damit, dass es keinen sicheren Weg gibt, sie an den Client zu schicken. Mit validateSecrets: true prüft Astro die Secrets beim Start. Ohne die Option werden sie geprüft, sobald etwas aus astro:env/server importiert wird, und Sie müssen beim Build möglicherweise Platzhalterwerte übergeben.

Zwei Grenzen nennt die Anleitung selbst: astro:env ist ein virtuelles Modul und läuft nur im Astro-Kontext, etwa in Komponenten, Endpunkten und Middleware. Und Werte aus .env-Dateien stehen in astro.config nicht zur Verfügung. Für Secrets, die nicht im Schema stehen oder dynamisch kommen, gibt es getSecret(). Die Referenz empfiehlt es statt process.env, weil der Adapter die Umsetzung liefert und sich bei einem Wechsel nichts ändert. Wo Ihre Seite läuft, beeinflusst also, wie Variablen gelesen werden: Das Thema Hosting und Adapter steht auf der Berliner Seite.

Datenschutz in einem Satz: Zugangsdaten zu Formular- oder Newsletter-Diensten sind kein Detail der Technik. Art. 32 DSGVO verlangt geeignete technische und organisatorische Maßnahmen und nennt unter Absatz 1 Buchstabe d ein Verfahren zur regelmäßigen Überprüfung ihrer Wirksamkeit (Verordnung (EU) 2016/679). Eine CI-Prüfung ersetzt dieses Verfahren nicht, sie ist aber ein Baustein, den man nachweisen kann. Zuständige Aufsicht für Unternehmen in Bielefeld ist die Landesbeauftragte für Datenschutz und Informationsfreiheit Nordrhein-Westfalen, kurz LDI NRW.

#Linting und Formatierung: ein Stil für alle

Typen finden Fehler in der Logik. Stilfragen und typische Fallen findet ein Linter, und die Formatierung nimmt den Streit über Einrückung aus jeder Änderung.

• Linting: eslint-plugin-astro bietet die Konfigurationen base und recommended. Für TypeScript in Astro-Komponenten braucht es zusätzlich typescript-eslint. Die Anleitung verlangt ESLint ab Version 10.0.0 und Node.js ab 22.22.3, 24.16.0 oder 26.3.0 (Stand 11.11.2026, Plugin-Version 3.2.1 vom 17.09.2026).
• Formatierung: prettier-plugin-astro ist das offizielle Prettier-Plugin für .astro-Dateien. Die README empfiehlt, den Parser für *.astro in der Prettier-Konfiguration ausdrücklich auf astro zu setzen.

Beides wandert als Konfigurationsdatei ins Repository. Ein neuer Entwickler muss nichts nachfragen: Er startet das Projekt, und der Editor formatiert wie alle vor ihm.

#Die Prüfung vor jedem Deployment

Alle Werkzeuge helfen nur, wenn jemand sie ausführt. Deshalb laufen sie automatisch bei jeder Änderung, bevor ausgeliefert wird. Ein Beispiel für GitHub Actions:

name: pruefung
on: [push, pull_request]
jobs:
  pruefen:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npx eslint .
      - run: npx prettier --check .
      - run: npx astro check
      - run: npm run build

Die Reihenfolge ist Absicht: erst die billigen Prüfungen, zuletzt der Build. Die Versionen v7 der beiden Actions entsprechen den neuesten Releases im jeweiligen GitHub-Repository (Stand 11.11.2026). Astro 7.4.11 verlangt laut package.json Node.js ab 22.23.4, node-version: 22 löst auf die neueste 22er-Version auf. Wo die Prüfung in Ihre Auslieferung greift, lege ich mit Ihnen schriftlich fest. Läuft sie rot, wird nicht deployt.

#Checkliste: Ist Ihr Astro-Projekt übergabefähig?

#So läuft ein Projekt mit mir

Alles läuft schriftlich: Sie schicken mir die Adresse der Website oder des Repositories, das Ziel und einen Termin, falls es einen gibt. Ich antworte mit offenen Fragen und danach mit einer schriftlichen Einschätzung samt Annahmen. Gearbeitet wird auf einer Staging-Umgebung, Sie nehmen schriftlich ab. Gestaltung, Mockups und Grafik bringen Sie mit, ich setze sie um. Danach können Sie eine Wartung mit mir vereinbaren oder die Pflege abgeben: Das Repository ist darauf vorbereitet.

#Häufige Fragen

#Muss ich TypeScript schreiben, damit sich das lohnt?

Nein. Laut Astro-Dokumentation behandelt Astro Komponenten immer als TypeScript, und der Editor leitet daraus Hinweise ab, auch ohne eine einzige Typangabe. Wer Props, Inhalte und Konfiguration typisiert, bekommt allerdings Fehlermeldungen, bevor die Seite online geht.

#Prüft astro build die Typen?

Nein. Die Dokumentation sagt, dass astro dev und astro build den Code nur mit esbuild umwandeln und keine Typen prüfen. Deshalb lege ich astro check vor den Build, damit ein Typfehler das Deployment stoppt.

#Sollte ich die strengste Vorlage nehmen?

Bei einem neuen Projekt ja, bei einem bestehenden meist nicht sofort. strictest meldet in altem Code oft sehr viele Stellen auf einmal. Ich starte dann mit strict und schalte einzelne Optionen nacheinander zu.

#Wo gehören Zugangsdaten für Formular- oder Newsletter-Dienste hin?

In Umgebungsvariablen, nie in den Quelltext. Mit astro:env lege ich sie als Server-Secret im Schema fest. Sie landen dann nicht im Bundle, und ein fehlender Wert fällt beim Start auf.

#Kann der Dienstleister nach der Übergabe ohne Sie weiterarbeiten?

Das ist das Ziel. Konfiguration, Prüfskripte und CI-Datei liegen in Ihrem Repository. Wer es klont, startet mit denselben Prüfungen, die auch vor dem Deployment laufen.

#Was muss ich Ihnen vor dem Start schicken?

Die Adresse der Website oder des Repositories, das Ziel, einen Termin falls es einen gibt und den aktuellen Stack. Gestaltung und Layout liefern Sie, die technische Umsetzung übernehme ich.

#Schreiben Sie mir

Der Weg zu mir ist das Kontaktformular. Nennen Sie die Adresse der Website oder des Repositories, was sie leisten soll, Ihren Termin und den aktuellen Stand: Astro-Version, vorhandene Tests, Hosting. Ich antworte schriftlich, erst mit Rückfragen, dann mit einer Aufwandseinschätzung. Schon die erste Einschätzung bekommen Sie gratis, ohne Verpflichtung. Wie ich Inhalte aus einem CMS in Astro anbinde, steht auf der Seite für Nürnberg, alle Astro-Leistungen im Überblick auf der Seite Astro-Entwickler.