Communitygithub.com

five-angles-company/convex-starter

Arbeite mit der Astro-Marketing-Website unter apps/landing. Verwenden Sie dies beim Bearbeiten der Landing Page, Hinzufügen von Abschnitten/Komponenten, Verwendung von shadcn/@workspace/ui in Astro, Anpassungen des Tailwind v4-Stils oder Hinzufügen dynamischer Daten zur Landing Page. Erfasst das Zero-JS-Modell, den Tailwind @source-Fix für .astro-Dateien und das Convex-Muster für statische Websites.

Was ist convex-starter?

Dieses Skill beschreibt die Entwicklungs- und Pflegerichtlinien für die statische Astro-Marketing-Website unter `apps/landing`. Es definiert, wann dieser Skill verwendet werden soll (alle Änderungen innerhalb des `apps/landing`-Verzeichnisses) und wann nicht (Next.js-Apps oder Mobile), und hebt das zentrale Zero-JS-Modell hervor: React-Komponenten werden standardmäßig zu statischem HTML zur Build-Zeit gerendert, ohne Client-JavaScript auszuliefern, es sei denn, eine `client:*`-Direktive wird explizit hinzugefügt. Das Skill geht detailliert auf die Integration von Tailwind v4 ein, insbesondere auf den wichtigen `@source`-Fix, der sicherstellt, dass Utility-Klassen, die in `.astro`-Dateien geschrieben werden, auch tatsächlich im finalen CSS generiert werden – ein häufiger Fehler, da das gemeinsame `globals.css` standardmäßig nur `.ts/.tsx` scannt. Es behandelt auch die Verwendung von Convex für dynamische Daten (z. B. Formulare) über einen Server-Endpunkt mit `ConvexHttpClient` anstelle eines React-Clients, und warnt vor Fallstricken wie CSS-Kommentaren, die glob-ähnliche Muster enthalten und das CSS beschädigen können. Plattform: Astro (statisch), @workspace/ui (shadcn/Tailwind v4), Convex für Backend-Dienste.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/five-angles-company/convex-starter/tree/HEAD/.claude/skills/astro-landing

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Landing (Astro)

apps/landing ist eine statische Astro-Website, die @workspace/ui (shadcn / Tailwind v4) wiederverwendet, um markenkonform zu bleiben – mit nahezu null Client-JavaScript.

Verwendung

  • Jede Änderung in apps/landing: Abschnitte, Komponenten, Styling oder das Hinzufügen dynamischer Daten.

Wann NICHT verwenden

  • Die Next.js-Apps oder Mobil – andere Laufzeiten.

Zero-JS-Modell

  • Astro rendert React-Komponenten standardmäßig zu statischem HTML zur Build-Zeit. Die Verwendung einer shadcn-Komponente (<Button>, <Card>, <Badge>) liefert präsentationstechnisch kein Client-JS aus.
  • JS wird nur ausgeliefert, wenn Sie eine client:*-Direktive hinzufügen (client:load, client:visible). Verwenden Sie sie nur für wirklich interaktive Teile und behalten Sie diese interaktive Gruppe in einer einzelnen .tsx-Insel – React-Kontext wird nicht über separate Astro-Inseln geteilt.
  • Für als Buttons gestylte Links bevorzugen Sie <a class={buttonVariants(...)}> gegenüber einem hydrierten Button.

Tailwind v4 + gemeinsame Tokens (der tragende Fix)

  • Tailwind v4 wird über @tailwindcss/vite in astro.config.mjs eingebunden (die alte @astrojs/tailwind-Integration ist veraltet).
  • src/styles/global.css importiert das gemeinsame Theme und fügt eine Astro-Inhaltsquelle hinzu:
    @import "@workspace/ui/globals.css";
    @source "./**/*.{astro,ts,tsx}";
    
    Das gemeinsame globals.css scannt standardmäßig nur .ts/.tsx, daher werden ohne die hinzugefügte @source Utility-Klassen, die in .astro-Markup geschrieben sind, nie generiert (sie werden stillschweigend nicht angewendet).
  • CSS-Kommentarfalle: Ein CSS-Kommentar, der einen **/-Glob enthält (z. B. zur Beschreibung von apps/**/*), schließt den Kommentar vorzeitig (*/) und beschädigt die nächste Regel. Halten Sie Globs aus Kommentaren heraus.

Dynamische Daten (bei Bedarf)

  • Die Landing Page hat keinen React-Provider und keine WorkOS-Authentifizierung. Verwenden Sie für ein Formular/einen dynamischen Aufruf einen Astro Server-Endpunkt mit ConvexHttpClient aus convex/browser für eine einmalige Mutation/Query – nicht ConvexReactClient/ConvexProviderWithAuth.

Fallstricke

  • Das Importieren des vollständigen @workspace/ui/globals.css zieht zusätzliche Theme-Variablen/Animationen herein – das ist in Ordnung (Tailwind entfernt ungenutzte Utilities).
  • Es gibt kein next-themes hier, daher ist die Landing Page nur hell (light-only), es sei denn, Sie fügen ein kleines Inline-.dark-Umschalt-Skript hinzu.
  • next/font ist nicht verfügbar – verwenden Sie @fontsource/* oder einen <link> für exakte Schriftarten-Gleichheit.

Überprüfung

  • pnpm --filter landing build → statisches dist/; index.html hat keine <script>-Tags für Seiten ohne client:*.
  • Eine Klasse, die nur in .astro verwendet wird (z. B. bg-primary), erscheint im gebauten CSS (der @source-Fix funktioniert).
  • pnpm --filter landing typecheck (astro check) wird bestanden.

Verwandte Skills