windwiderstand.de/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

RustyAstro is an Astro + Svelte frontend for RustyCMS (a Rust-based CMS). It fetches all content via REST API, generates TypeScript types from the OpenAPI spec, and deploys as a static site to Firebase Hosting.

Requires: RustyCMS running at PUBLIC_CMS_URL (default http://localhost:3000) for development and build.

Commands

# Development (requires RustyCMS running separately)
yarn dev                    # Generates API types, starts Astro dev server on :4321

# Build
yarn build                  # Generate types → Astro build → Pagefind indexing

# Preview production build
yarn preview

# Type generation (requires RustyCMS running)
yarn generate:api-types     # Regenerate src/lib/cms-api.generated.ts from OpenAPI spec

# Cache management
yarn cache:warm             # Pre-populate .cache/cms/ with all common API responses

# Storybook (UI component development)
yarn storybook              # Start Storybook on :6006

# Deploy
yarn deploy                 # Build + firebase deploy

There are no test commands — this project has no test suite.

Architecture

Data Flow

All content comes from RustyCMS via src/lib/cms.ts. At build time, Astro calls CMS functions in getStaticPaths() to generate static pages. A caching layer makes the build resilient to CMS downtime.

RustyCMS API → cms.ts (process cache + disk cache) → Astro pages → Static HTML

CMS Client (src/lib/cms.ts)

The central module for all API access. Key conventions:

• slug = URL path (for links, routing)
• _slug = API/internal ID (for CMS GET requests)
• Slugs are normalized (leading slashes removed)
• Caching: in-process deduplication + disk cache at .cache/cms/ (Node.js only, lazy-imported)
• Dev mode: no list-caching so new CMS entries appear immediately

Generated Types

src/lib/cms-api.generated.ts is auto-generated from the OpenAPI spec — never edit manually. Regenerate with yarn generate:api-types after schema changes in RustyCMS.

Page Routing

• / → src/pages/index.astro — lists all Pages from CMS
• /:slug → src/pages/[slug].astro — dynamic page content
• /post/:slug → src/pages/post/[slug].astro — blog post detail
• /blog/ and /posts/ — paginated post lists (both route variants exist)

Content Block System

Pages contain rows of content blocks. Each block type has a corresponding Svelte component in src/components/blocks/. Layout is controlled by src/lib/block-layout.ts using a 12-column Tailwind grid — parent containers need grid grid-cols-12.

i18n / Translations

All UI strings come from a CMS translation bundle, never hardcoded in components.

Flow:

1. src/middleware.ts loads the app bundle from CMS once per request → Astro.locals.translations
2. In Astro components: const translations = Astro.locals.translations ?? {}; use t(translations, T.key)
3. In Svelte (SSR): wrap with <TranslationProvider> and use useTranslate() hook
4. In client:load islands: useTranslate() has no Svelte context during SSR → pass translations as a prop from the Astro page and use static t(translations, T.key) instead

Translation keys are defined in src/lib/translations.ts as the TRANSLATION_KEYS array (type-safe). Strings are stored in RustyCMS under content/de/translation_bundle/app.json5. Placeholders use {{name}} syntax.

Image Handling

src/lib/rusty-image.ts proxies image transforms through RustyCMS (/api/transform). Transformed images are cached at public/images/transformed/ and survive builds. The RustyImage component exists in both .astro (SSR) and .svelte (client islands) variants.

Layout

src/layouts/Layout.astro is the master layout. It:

• Wraps content in <TranslationProvider> for Svelte context
• Loads header navigation and footer from CMS
• Optionally renders a TopBanner fullwidth image
• Renders Breadcrumbs (supports both static labels and translation keys)

Environment Variables

Variable	Required	Purpose
PUBLIC_CMS_URL	Yes	RustyCMS base URL (no trailing slash)
PUBLIC_SITE_URL	No	Canonical/sitemap URL (production)
PUBLIC_SITE_NAME	No	og:site_name and JSON-LD
PUBLIC_UMAMI_SCRIPT_URL	No	Analytics
PUBLIC_UMAMI_WEBSITE_ID	No	Analytics

Deployment

Static build deployed to Firebase Hosting. Cache headers: 1-year immutable for assets, 1-hour for HTML. Config in firebase.json and .firebaserc.