Erste Schritte

Von der Installation bis zum ersten Build — alles was du brauchst um mit der CP Component Registry loszulegen.

Voraussetzungen

Node.js

Version 22 oder neuer

pnpm

Version 9 oder neuer

Git

SSH-Zugang zu GitHub

Editor

VS Code empfohlen

Projekt aufsetzen

1. Registry klonen & CLI installieren

Einmalig pro Rechner. Das Setup-Script installiert die CLI global via npm link. Danach steht cp-components überall zur Verfügung.

git clone git@github.com:andrenagusch/cp-registry.git
cd cp-registry
pnpm install              # Projekt-Dependencies
./cli/setup.sh            # CLI global installieren
cp-components --help      # Prüfen

2. Neues Projekt erstellen (interaktiv)

Ohne Argumente startet der interaktive Modus: Projektname, Sitepackage, Components und Skills per Multi-Select auswählen.

mkdir mein-projekt && cd mein-projekt
cp-components init

2b. Alternativ: Non-interaktiv

Mit Flags direkt erstellen — ideal für Skripte und CI.

cp-components init --name "mein-projekt" --sitepackage "mein_sitepackage"

3. Dependencies installieren

Wechsle ins Astro-Template-Verzeichnis und installiere die Pakete.

cd src/mein-projekt
pnpm install

4. Brand-Farben eintragen

Oeffne src/styles/theme/colors.css und trage die Projektfarben ein.

/* src/styles/theme/colors.css */
@theme {
  --color-brand-primary: oklch(78% 0.18 95);
  --color-brand-primary-hover: oklch(70% 0.18 95);
  --color-brand-secondary: oklch(55% 0.15 260);
  --color-brand-foreground: oklch(20% 0.02 260);
  --color-brand-muted: oklch(55% 0.02 260);
  --color-brand-surface: oklch(99% 0.005 260);
  --color-brand-surface-alt: oklch(96% 0.01 260);
  --color-brand-border: oklch(88% 0.02 260);
  --color-brand-destructive: oklch(55% 0.22 25);
  --color-brand-success: oklch(60% 0.18 145);
  --color-brand-focus: oklch(55% 0.25 260);
}

5. Components hinzufügen

Interaktiv oder per Befehl. Dependencies werden automatisch aufgelöst.

# Interaktiv (Multi-Select)
cp-components add

# Oder direkt
cp-components add button card accordion hero navigation footer

6. Entwickeln

Starte den Dev-Server und fange an zu bauen.

pnpm dev

Projektstruktur

Nach cp-components init sieht dein Projekt so aus:

mein-projekt/
├── src/
│   └── mein-projekt/               # Astro-Template (hier wird gearbeitet)
│       ├── src/
│       │   ├── components/a11y/    # A11y-Utilities (Focus-Trap, ARIA etc.)
│       │   ├── styles/             # Komplettes CSS-System
│       │   │   ├── base/           # Reset, Grid, Typography
│       │   │   ├── theme/          # Colors (leer), Fonts, Breakpoints
│       │   │   ├── utilities/      # Fluid Spacings
│       │   │   └── globals.css     # Haupt-Stylesheet
│       │   ├── layouts/Layout.astro
│       │   ├── pages/index.astro
│       │   └── types/index.d.ts
│       ├── public/
│       ├── package.json
│       ├── astro.config.mjs
│       ├── tsconfig.json
│       ├── cp.config.mjs           # TYPO3-Sync Konfiguration
│       └── cp-components.json      # Installierte Components
├── packages/
│   └── mein_sitepackage/           # TYPO3 Sitepackage
│       └── Resources/Public/
│           ├── Css/
│           ├── JavaScript/
│           └── Images/
└── .gitignore

CLI-Referenz

Alle Befehle werden aus dem Astro-Template-Verzeichnis ausgeführt (src/{name}/).

cp-components init [--name "name"] [--sitepackage "name"]

Neues Projekt erstellen. Ohne Flags: interaktiver Modus mit Multi-Select für Components und Skills.

cp-components add [components...]

Components hinzufügen. Ohne Argumente: interaktiver Multi-Select. Löst Dependencies automatisch auf.

cp-components list [-c category]

Alle verfügbaren Components anzeigen, gruppiert nach Kategorie.

cp-components diff <name>

Unterschiede zwischen lokaler Version und Registry-Version anzeigen.

cp-components sync [-f] [--dry-run]

Alle installierten Components aktualisieren (nur unmodifizierte).

cp-components new <Name> [-c category]

Neue Component scaffolden (Boilerplate: Astro-Datei, Manifest, Showcase).

cp-components remove <components...> [-f]

Components aus dem Projekt entfernen. Warnt bei Abhaengigkeiten.

cp-components validate

Alle Component-Manifeste auf Konsistenz prüfen.

cp-components skills [namen... | all | --universal]

Claude Code Skills & Agents installieren. Ohne Argumente: interaktiver Multi-Select.

Build & TYPO3-Sync

Normaler Build

Erstellt einen statischen Build für Entwicklung und Preview.

pnpm build

TYPO3-Build

Exportiert CSS, JS und Assets ins Sitepackage unter packages/.

pnpm build:typo3

TYPO3-Sync konfigurieren

Die Datei cp.config.mjs steuert den Export. Die wichtigsten Optionen:

export default {
  // Sitepackage-Name (oder per Env: CP_SITEPACKAGE)
  sitepackage: 'mein_sitepackage',

  // Manueller Pfad zum Resources-Verzeichnis (optional)
  sitepackagePath: process.env.CP_SITEPACKAGE_RESOURCES_DIR ?? null,

  // Bucket-Unterverzeichnis (null = flach, 'Assets' = Public/Assets/Css)
  bucketDir: null,

  // Welche Assets kopiert werden sollen
  assets: { fonts: true, images: true, svgs: true, icons: true, media: true },

  // CSS-Ausgabe
  css: {
    outputName: 'style.css',
    rewriteMaskPaths: true,   // mask-image Pfade für TYPO3
    rewriteFontPaths: true,   // Font-Pfade ohne Hash
    rewriteAssetPaths: true,  // Asset-Pfade relativ
  },
};

Components anpassen

Nach der Installation gehören die Components dir. Du kannst sie frei ändern — das ist gewollt.

Änderungen prüfen

cp-components diff accordion

Zeigt Unterschiede zur Registry-Version.

Aktualisieren

cp-components sync

Aktualisiert nur unmodifizierte Components.

Neues Component beitragen

1. src/components/{Name}/
2. registry/components/{name}.json
3. src/pages/components/{name}.astro

Component, Manifest und Showcase-Seite.

CLI verwalten

Das Setup-Script kümmert sich um Installation, Updates und Deinstallation. Es verwendet intern npm link (nicht pnpm link).

Installieren / Deinstallieren

# Installieren (einmalig)
./cli/setup.sh

# Deinstallieren
./cli/setup.sh uninstall

Aktualisieren / Status

# Nach git pull: neu bauen
./cli/setup.sh update

# Status prüfen
./cli/setup.sh status

Design-Token Übersicht

Alle Components nutzen diese semantischen Farb-Tokens. Du musst nur die Werte in colors.css eintragen — der Rest funktioniert automatisch.

Token	Zweck	Beispiel
`--color-brand-primary`	Hauptfarbe (Buttons, Akzente)	`bg-brand-primary`
`--color-brand-primary-hover`	Hover-State Primary	`hover:bg-brand-primary-hover`
`--color-brand-secondary`	Sekundaerfarbe	`bg-brand-secondary`
`--color-brand-foreground`	Standard-Textfarbe	`text-brand-foreground`
`--color-brand-muted`	Subtiler Text, Platzhalter	`text-brand-muted`
`--color-brand-surface`	Seitenhintergrund	`bg-brand-surface`
`--color-brand-surface-alt`	Card/Section-Hintergründe	`bg-brand-surface-alt`
`--color-brand-border`	Rahmen, Divider	`border-brand-border`
`--color-brand-destructive`	Fehler, Delete	`text-brand-destructive`
`--color-brand-success`	Erfolg	`text-brand-success`
`--color-brand-focus`	Focus-Ring Farbe	`ring-brand-focus`