Einstieg

Wie aus dem Starter ein Kundenprojekt wird.

Zum ersten Mal hier?

Diese Seite ist die knappe Referenz zum Initialisierungsprozess. Wer den Starter noch nicht kennt — oder von Joomla und YOOtheme kommt —, fährt mit Der erste Tag besser: derselbe Weg, aber Schritt für Schritt bis zur ersten selbst gebauten Seite.

Voraussetzungen

• Node 24 (Active LTS) — die Version steht in .nvmrc
• pnpm (Version aus dem Feld packageManager in der package.json)
• Git und Zugriff auf die GitHub-Organisation
• PHP 8.3 und Composer — nur für Projekte mit dem Standalone-PHP-Formular-Handler

Ein neues Projekt anlegen

Der bevorzugte Weg ist „Use this template". Er erzeugt ein Repository mit eigener, leerer Historie: Die Commits des Starters gehören nicht in ein Kundenprojekt, und ein git log soll dort die Geschichte dieses Kunden erzählen.

gh repo create Kicktemp/kunde-projekt --private --template Kicktemp/astro-boilerplate
git clone git@github.com:Kicktemp/kunde-projekt.git
cd kunde-projekt
pnpm install

Ein normales git clone des Starters funktioniert auch, bringt aber dessen komplette Historie und dessen Remote mit. Wer das tut, setzt anschließend selbst einen neuen Remote und entscheidet, was mit der Historie geschehen soll — der Init fasst Git nicht an.

pnpm starter:init

pnpm starter:init

Der Befehl stellt rund fünfzehn Fragen und schreibt daraus die Projektkonfiguration. Was er erhebt, landet vollständig in project.config.ts und ist damit öffentlich — nach Geheimnissen fragt er nirgends.

Was gefragt wird

Frage	Wozu
Projektname und Domain	site.url, Titelvorlage, kanonischer Host der .htaccess
Beschreibung, Sprache	Meta-Beschreibung, lang-Attribut, Sprachkonfiguration
Auftraggeber, Kontakt	Impressum, JSON-LD, Kontaktseite ohne Formular
Ladenlokal oder Praxis	LocalBusiness-Schema — verlangt zusätzlich die Anschrift
Deploymentziel	Mittwald oder GitHub Pages; bestimmt, welcher Workflow bleibt
Formular-Backend und Captcha	forms.provider, forms.endpoint, forms.captcha
Google Tag Manager	Container-ID, Consent Mode, welche Tags im Container liegen
Vue	installiert @astrojs/vue und setzt das Flag, wenn es geklappt hat
Demo-Inhalte	Startseite und Demo-Bilder des Starters entfernen oder behalten

Abgeleitet und deshalb nicht gefragt: die Einwilligungskategorien (sie folgen daraus, was das Projekt tatsächlich lädt), die Titelvorlage, der kanonische Host und meta.starterVersion.

Nach WebMCP fragt der Init ebenfalls nicht. Das Flag ist experimentell und löst heute nichts aus; wer es einschaltet, tut das bewusst und mit der Dokumentation daneben.

Was er ändert

• schreibt project.config.ts, package.json (Name, Beschreibung, Version 0.1.0), README.md, project/brief.md und legt .env aus .env.example an — ohne Werte
• ersetzt bei „Demo entfernen" die Startseite durch einen leeren Anfang und nimmt die Demo-Bilder aus src/content/assets.yaml
• entfernt den nicht gewählten Deployment-Workflow, die Demo-Bilder und tests/e2e/starter-demo.spec.ts; in Projekten ohne Standalone-PHP-Backend zusätzlich server/ samt seinen Tests und den PHP-Gliedern der Qualitätskette

Nicht angetastet bleiben docs/, CHANGELOG.md und die Release-Please-Dateien — ihre Workflows prüfen github.repository und laufen in einem abgeleiteten Repository nie — und vor allem Git: keine Commits, keine Remotes, keine Tags. Der Styleguide bleibt ebenfalls; er ist das Gate der axe-Prüfung, nicht Demo-Material (ADR 0016).

Vorher ansehen

pnpm starter:init --dry-run --answers antworten.json

Gibt den vollständigen Plan aus und schreibt nichts. --answers erwartet dieselben Angaben wie der Dialog als JSON; Beispiele liegen unter tests/fixtures/starter/.

Weitere Schalter: --force (auch bei bereits initialisiertem Projekt oder offenen Änderungen), --skip-build (den abschließenden Probebau überspringen).

Danach

git diff          # der Init als eine einzige, überprüfbare Änderung
pnpm verify       # muss grün sein

Der Init gibt am Ende aus, was von Hand folgt. Je nach Projekt gehört dazu:

• Impressum und Datenschutzerklärung mit echten Angaben füllen — die Seiten des Starters sind Gerüste, keine Rechtstexte
• Logo und OG-Bild in src/assets/ austauschen und ihre Alt-Texte auf altApproved: true setzen
• GitHub Secrets für das Deployment setzen beziehungsweise GitHub Pages auf „GitHub Actions" stellen
• server/forms/config/config.local.php auf dem Zielsystem anlegen und eine echte Übermittlung abschicken und im Postfach nachsehen

Alltag

pnpm dev            # Entwicklungsserver
pnpm verify         # komplette Qualitätskette, identisch zur CI

pnpm verify führt Format, Lint, Typprüfung, Unit-Tests, die Tests des Formular-Handlers, alle Builds und die End-to-End-Tests aus. Vor jedem Commit grün.

Ein Projekt auf eine neuere Starter-Version heben

meta.starterVersion in project.config.ts sagt, von welchem Stand ein Projekt kommt. Genau dafür steht sie dort — der Starter entwickelt sich weiter, und ein Kundenprojekt soll Verbesserungen übernehmen können, ohne neu aufgesetzt zu werden.

git remote add starter git@github.com:Kicktemp/astro-boilerplate.git
git fetch starter --tags

# Was sich seit dem eigenen Stand geändert hat
git log --oneline v0.8.1..starter/main
git diff v0.8.1 starter/main -- src/lib docs/adr

Übernommen wird gezielt, nicht als Ganzes:

• Fast immer gefahrlos — src/lib/, server/forms/src/, tests/, docs/, die Workflows. Das ist der Motor des Starters, und er kennt kein Projekt.
• Ansehen, dann entscheiden — src/components/, src/styles/theme.css. Hier hat ein Kundenprojekt eigene Änderungen.
• Nie blind — project.config.ts, src/pages/, src/content/. Das ist das Projekt.

Kommen neue Pflichtfelder in der Konfiguration dazu, sagt es der nächste Build: Die Prüfung ist streng und nennt Pfad und Ursache. Nach dem Upgrade meta.starterVersion auf den übernommenen Stand setzen und pnpm verify laufen lassen.

Ein ADR im Starter ist der Hinweis, dass sich etwas Grundsätzliches geändert hat — das Verzeichnis ist beim Upgrade die erste Anlaufstelle.