Schnellstart-Tutorial: 5 Schritte von npm install zur fertigen Astro-Seite
Tutorials 10 min read

Astro-Projekt in 5 Minuten aufsetzen

Arnold Wender
Arnold Wender
#Astro #Tutorial #npm #Component Library #Storybook

Du hast ein Astro-Projekt und willst nicht bei null anfangen. Hier ist der schnellste Weg von der leeren Seite zu einer funktionierenden Website mit Navigation, SEO, Accessibility und Design System.

150
Komponenten
17
Kategorien
0
Abhängigkeiten
8
Starter-Templates

Voraussetzung

Ein bestehendes Astro-Projekt (v4 oder v5). Falls noch keins existiert:

npm create astro@latest mein-projekt
cd mein-projekt

Die 5 Schritte im Überblick

Von der leeren Seite zur fertigen Website

  1. Paket installieren

    Ein npm-Befehl — keine Runtime-Abhängigkeiten, nur .astro- und .ts-Dateien.

  2. Im Storybook erkunden

    549 Stories mit interaktiven Controls durchsuchen und passende Komponenten finden.

  3. BaseLayout aufsetzen

    SEO, Header, Footer, Breadcrumbs und Accessibility-Toolbar in einem Layout vereinen.

  4. Seiten mit Sections bauen

    Hero, Features, FAQ, Testimonials und CTA-Abschnitte zusammensetzen.

  5. Design mit Tokens anpassen

    CSS Custom Properties überschreiben oder den DesignSystemProvider nutzen.

Schritt 1: Installieren

npm install @wendermedia/astro-components

Das Paket hat keine Runtime-Abhängigkeiten. Es bringt nur Astro-Komponenten mit — .astro- und .ts-Dateien, die direkt in deinem Build-Prozess kompiliert werden.

Schritt 2: Im Storybook erkunden

Bevor du irgendetwas importierst, öffne das Live-Storybook und sieh dir an, was verfügbar ist:

wm-astro-components.netlify.app

Die Docs-Seite jeder Komponente zeigt:

  • Props mit Typen und Defaults
  • Live-Preview mit interaktiven Controls
  • Varianten (Light/Dark, verschiedene Größen, Zustände)
  • CSS Custom Properties, die die Komponente nutzt
  • Accessibility-Check über den A11y-Tab

Schritt 3: BaseLayout aufsetzen

Eine typische Astro-Seite braucht vier Dinge: SEO-Meta-Tags, eine Grundstruktur, Navigation und Accessibility-Tools. Das alles kommt in ein zentrales Layout.

---
// src/layouts/BaseLayout.astro
import { SEO } from '@wendermedia/astro-components/seo';
import { Header, Footer } from '@wendermedia/astro-components/layout';
import { SkipLinks, AccessibilityToolbar } from '@wendermedia/astro-components/accessibility';
import { Breadcrumbs } from '@wendermedia/astro-components/navigation';

interface Props {
  title: string;
  description: string;
}

const { title, description } = Astro.props;
---

<!doctype html>
<html lang="de">
  <head>
    <SEO title={title} description={description} />
  </head>
  <body>
    <SkipLinks />
    <Header />
    <Breadcrumbs items={[{ label: 'Home', href: '/' }, { label: title }]} />
    <main id="main-content">
      <slot />
    </main>
    <Footer />
    <AccessibilityToolbar position="right" />
  </body>
</html>
Was du bekommst mit 6 Imports:

- <title> und <meta description> Tags
- Open Graph und Twitter Card Meta-Tags
- Skip-to-Content Navigation (Accessibility)
- Responsive Header mit Navigation
- Breadcrumbs mit BreadcrumbList JSON-LD
- Semantischer <main> Bereich
- Responsive Footer
- Accessibility-Toolbar (Schriftgröße, Kontrast, Fokus)

Das sind sechs Imports und du hast: Meta-Tags, Skip-Navigation, Header, Footer, Breadcrumbs mit JSON-LD und einen Accessibility-Toolbar mit Schriftgröße, Kontrast und Fokus-Optionen.

Schritt 4: Seiten bauen

Mit dem Layout steht die Basis. Jetzt kommen Seitenabschnitte aus der sections-Kategorie:

---
// src/pages/index.astro
import BaseLayout from '../layouts/BaseLayout.astro';
import { Hero, Features, FAQ, CTA } from '@wendermedia/astro-components/sections';
import { Testimonials } from '@wendermedia/astro-components/sections';
---

<BaseLayout title="Startseite" description="Beschreibung">
  <Hero
    title="Überschrift"
    subtitle="Unterüberschrift"
    ctaText="Jetzt starten"
    ctaHref="/kontakt"
  />

  <Features features={[
    { title: 'Schnell', description: 'Astro liefert Zero-JS per Default.' },
    { title: 'Barrierefrei', description: 'WCAG 2.2 AA konform.' },
    { title: 'SEO-optimiert', description: 'Strukturierte Daten automatisch.' },
  ]} />

  <Testimonials testimonials={[
    { quote: 'Endlich eine Library ohne Overhead.', author: 'Max M.', role: 'Frontend Dev' },
  ]} />

  <FAQ items={[
    { question: 'Brauche ich React?', answer: 'Nein. Alles ist reines Astro.' },
    { question: 'Funktioniert das mit Tailwind?', answer: 'Ja. CSS Custom Properties kombinieren sich mit Tailwind.' },
  ]} />

  <CTA title="Bereit?" description="Starte jetzt." buttonText="npm installieren" buttonHref="https://www.npmjs.com/package/@wendermedia/astro-components" />
</BaseLayout>

Schritt 5: Design anpassen

Die Komponenten kommen mit neutralen Default-Tokens. Für eigenes Branding gibt es zwei Wege:

---
// Option A: DesignSystemProvider
import { DesignSystemProvider } from '@wendermedia/astro-components/design-system';
---

<DesignSystemProvider
  primaryColor="#059669"
  secondaryColor="#0284c7"
  fontFamily="'DM Sans', sans-serif"
  borderRadius="0.75rem"
/>
/* Option B: CSS Custom Properties direkt in global.css */
:root {
  --color-primary-500: #059669;
  --color-secondary-500: #0284c7;
  --font-family-body: 'DM Sans', sans-serif;
  --radius-md: 0.75rem;
  --shadow-md: 0 4px 6px rgba(0,0,0,0.1);
  --space-section-md: 4rem;
}

Beide Wege sind gleichwertig. Der Provider ist bequemer, die Custom Properties geben mehr Kontrolle.

Import-Pfade aller 17 Kategorien

Kategorie Import-Pfad Anzahl
Accessibility @wendermedia/astro-components/accessibility 12
Content @wendermedia/astro-components/content 4
Design System @wendermedia/astro-components/design-system 1
E-Commerce @wendermedia/astro-components/ecommerce 5
Forms @wendermedia/astro-components/forms 6
Gallery @wendermedia/astro-components/gallery 3
Images @wendermedia/astro-components/images 4
Layout @wendermedia/astro-components/layout 3
Layouts @wendermedia/astro-components/layouts 15
Maps @wendermedia/astro-components/maps 2
Media @wendermedia/astro-components/media 3
Navigation @wendermedia/astro-components/navigation 4
Products @wendermedia/astro-components/products 2
SEO @wendermedia/astro-components/seo 8
Sections @wendermedia/astro-components/sections 68
Social @wendermedia/astro-components/social 3
UI @wendermedia/astro-components/ui 19

CLI-Tool für neue Projekte

Wer ein komplett neues Projekt starten will, kann das CLI-Tool nutzen:

npx create-wm-component

Acht Templates stehen zur Auswahl: Blog, E-Commerce, Landing Page, Portfolio, Corporate, Docs, SaaS und Affiliate. Jedes Template setzt die richtigen Komponenten, Layouts und Design Tokens auf.

Häufige Setup-Fragen

Setup FAQ

Nächster Schritt

Öffne das Storybook, such dir eine Komponente aus und bau sie ein. Jede Docs-Seite zeigt den Import-Pfad, die Props und eine Live-Preview.