|
| 1 | +--- |
| 2 | +name: astro-strapi-starter |
| 3 | +description: >- |
| 4 | + Develop and extend the Astro + Strapi starter: content.config with @sensinum/astro-strapi-loader, |
| 5 | + Strapi 5 data in Astro pages, StrapiBlocks for rich text Blocks fields, dynamic zone BlockRenderer, |
| 6 | + Tailwind 4 and shadcn/ui. Use when wiring Strapi collections, new block components, or |
| 7 | + CMS-driven pages using this template. |
| 8 | +--- |
| 9 | + |
| 10 | +# Astro × Strapi starter (VirtusLab template) |
| 11 | + |
| 12 | +## Scope |
| 13 | + |
| 14 | +- **Stack:** Astro 6+, Strapi 5, `@sensinum/astro-strapi-loader`, `@sensinum/astro-strapi-blocks`, Tailwind CSS 4, shadcn-style UI in `src/components/ui/`. |
| 15 | +- **Goal:** Add or change CMS-driven content, query shapes, and UI while keeping one source of truth for Strapi REST objects and a clear split between **dynamic zone components** and **rich-text Blocks**. |
| 16 | + |
| 17 | +## Read next |
| 18 | + |
| 19 | +- **Loader (queries, collections, locales):** stub with upstream links in [../astro-strapi-loader/SKILL.md](../astro-strapi-loader/SKILL.md) — canonical: [raw SKILL on GitHub](https://raw.githubusercontent.com/VirtusLab-Open-Source/astro-strapi-loader/main/.ai/astro-strapi-loader/SKILL.md) |
| 20 | +- **StrapiBlocks (rich text):** stub with upstream links in [../astro-strapi-blocks/SKILL.md](../astro-strapi-blocks/SKILL.md) — canonical: [raw SKILL on GitHub](https://raw.githubusercontent.com/VirtusLab-Open-Source/astro-strapi-blocks/main/.ai/astro-strapi-blocks/SKILL.md) |
| 21 | +- **Project overview:** [../AGENTS.md](../AGENTS.md) |
| 22 | + |
| 23 | +## Configuration flow |
| 24 | + |
| 25 | +1. **Environment:** `STRAPI_URL`, `STRAPI_TOKEN` in `.env` (see `env.example`). Required for a live build against Strapi; the starter can fall back if the CMS is down (see `content.config.ts` and pages). |
| 26 | +2. **Collections:** In `src/content.config.ts`, define **named query objects** (e.g. `homepageQuery`, `pagesQuery`) and pass them to `generateCollections({ url, token }, [{ name, query }, ...])`. Export merged `collections`. |
| 27 | +3. **Queries:** Reuse **fragments** (hero, SEO, shared components) with object spread. For dynamic zones, use `on` with **exact component UIDs** from the Strapi schema. |
| 28 | +4. **Pages:** Use `getCollection` / `getEntry` from `astro:content`. Single types often appear as a one-item collection—normalize with a small helper if you use `[0]`. |
| 29 | + |
| 30 | +## Two rendering paths (do not confuse them) |
| 31 | + |
| 32 | +| Source in Strapi | In Astro | Package / pattern | |
| 33 | +|------------------|----------|-------------------| |
| 34 | +| **Dynamic zone** (components with `__component`) | Map `__component` in a parent (e.g. `BlockRenderer.astro`) | Project components under `src/components/blocks/` | |
| 35 | +| **Rich text → “Blocks”** (editor blocks JSON) | `<StrapiBlocks data={...} />` | `@sensinum/astro-strapi-blocks` | |
| 36 | + |
| 37 | +Use **StrapiBlocks** for the Strapi 5 **Blocks** rich-text field. Use **custom Astro components** for **dynamic zone** entries your schema defines (hero, CTA, etc.). |
| 38 | + |
| 39 | +## StrapiBlocks in this project |
| 40 | + |
| 41 | +- Import: `import { StrapiBlocks } from '@sensinum/astro-strapi-blocks'`. |
| 42 | +- Pass **unmodified** field data, e.g. from a text component’s `content` or hero copy. |
| 43 | +- Optional: `theme`, `class`, or `blocks={{ ... }}` overrides per package docs. |
| 44 | +- Centralize large `theme` objects in a module to avoid drift between pages. |
| 45 | + |
| 46 | +## New dynamic zone block (example workflow) |
| 47 | + |
| 48 | +1. Add the component in Strapi and note its `__component` string. |
| 49 | +2. Extend `Strapi*Component` types in `src/types/strapi.ts` if you use TypeScript strongly. |
| 50 | +3. Add a new Astro file under `src/components/blocks/` and a branch in `BlockRenderer.astro`. |
| 51 | +4. Update **populate** for the dynamic zone so the new component’s media and relations are included (see loader skill, `on` / nested `populate`). |
| 52 | + |
| 53 | +## New collection or content type |
| 54 | + |
| 55 | +1. Add a **query** object and a new entry in the `generateCollections` definition list. |
| 56 | +2. Add Zod/typing as needed; keep field names aligned with the API. |
| 57 | +3. Add pages under `src/pages/` that call `getCollection` with the new key. |
| 58 | + |
| 59 | +## UI (Tailwind + shadcn) |
| 60 | + |
| 61 | +- Global design tokens and Tailwind: `src/styles/global.css`. |
| 62 | +- React shadcn primitives: `src/components/ui/`, `cn()` from `@/lib/utils`, aliases from `components.json`. |
| 63 | +- Pure Astro + Tailwind lives alongside React islands—keep one visual language (spacing, color tokens) across both. |
| 64 | + |
| 65 | +## Verification |
| 66 | + |
| 67 | +- `npm run build` runs `astro check` and a production build—use after changing schemas, `content.config.ts`, or block components. |
0 commit comments