|
| 1 | +--- |
| 2 | +name: astro-strapi-blocks |
| 3 | +description: >- |
| 4 | + Integrates @sensinum/astro-strapi-blocks with Strapi 5 Blocks fields in Astro: wiring |
| 5 | + `data` from API responses, theming with `extend` and `overwrite`, and custom block |
| 6 | + components. Use when adding or editing Strapi block rendering, rich text zones, or |
| 7 | + `StrapiBlocks` / theme configuration. |
| 8 | +--- |
| 9 | + |
| 10 | +# Astro Strapi Blocks (Strapi 5 + Astro) |
| 11 | + |
| 12 | +## Prereq |
| 13 | + |
| 14 | +- `data` is **raw** Strapi 5 **Blocks** JSON: `StrapiBlockField` (array of blocks). Do not pre-stringify; pass the same shape the REST/GraphQL client returns. |
| 15 | +- Install `@sensinum/astro-strapi-blocks`, Astro per package requirements. |
| 16 | + |
| 17 | +## Pass data into the component |
| 18 | + |
| 19 | +1. In the Astro page, layout, or section component, receive the object that already includes the blocks field (e.g. from a loader, `getEntry`, or `fetch`). |
| 20 | +2. Pass that field: `data={entity.<blocksField>}`. |
| 21 | +3. If the field can be empty, guard the parent or accept empty array (the renderer maps over `data`). |
| 22 | + |
| 23 | +**Anti-pattern:** building a new array by hand in the view unless the CMS is not the source of truth. Prefer one mapping from API types to your components at the data layer, then a single `data={...}`. |
| 24 | + |
| 25 | +## Theme: `extend` vs `overwrite` |
| 26 | + |
| 27 | +- **`extend`:** merges with the package default. String arrays (class lists) are **concatenated**; nested objects are merged. Use to tweak (e.g. add `prose` classes, brand links) while keeping default spacing where useful. |
| 28 | +- **`overwrite`:** replaces arrays at a given path; nested objects are still deep-merged, but any array you set **replaces** the default for that key. Use for a full design system look that should not retain Tailwind defaults from the built-in theme. |
| 29 | + |
| 30 | +**Order of application (library behavior):** `overwrite` is applied first, then `extend` on the result. In a mixed `theme`, use `overwrite` to reset major sections and `extend` to add a few project-wide tokens. |
| 31 | + |
| 32 | +**Lists and nesting:** for nested list markers, configure `list.indent.ordered` and `list.indent.unordered` as arrays: index 0 = top level, index 1 = first nested, etc. Use `getPropertyClass` and level when writing custom list markup that mirrors the default. |
| 33 | + |
| 34 | +## Centralizing themes |
| 35 | + |
| 36 | +- Export a default theme object (or factory) from a small module and import it in pages/sections. Keeps `StrapiBlocks` calls consistent. |
| 37 | +- If the same blocks must **look different** on different surfaces (e.g. on dark vs light, or in a card), return a **derived** theme from a base object (e.g. clone and adjust class strings for links/foreground). Avoid duplicating full theme trees in every `.astro` file. |
| 38 | + |
| 39 | +## Custom block components (`blocks` prop) |
| 40 | + |
| 41 | +Map built-in type keys to Astro components: `heading`, `paragraph`, `quote`, `list`, `code`, `image`. |
| 42 | + |
| 43 | +Each override receives props consistent with the built-in block (see package README: `data`, `theme`, `class`, type-specific: `level`, `format`, `language`, `url`, `caption`, etc.). |
| 44 | + |
| 45 | +1. Co-locate a custom `*.astro` file with your UI layer. |
| 46 | +2. Reuse `renderPropertyClasses` / `getPropertyClass` from the package for class paths that match the default theme structure. |
| 47 | +3. For text rich runs, follow how default blocks forward `data` to child item renderers (links, strong, etc.) so you do not drop formatting. |
| 48 | + |
| 49 | +`StrapiBlockCustom` in the package wraps your component: your component receives the same prop contract as the default block for that type. |
| 50 | + |
| 51 | +## New “block” types |
| 52 | + |
| 53 | +Strapi 5 only emits the types the editor supports. This package **renders** the standard set. To add **custom** types you must add them in Strapi (e.g. custom field / plugin) and handle them in your own code path—`StrapiBlocks` only dispatches the built-in `type` values. If you need custom CMS blocks in one zone, use a **dynamic zone** in Strapi and a parent Astro switch that picks `StrapiBlocks` for rich-text fields and your components for other components. |
| 54 | + |
| 55 | +## Checklist (new feature) |
| 56 | + |
| 57 | +- [ ] Blocks field typed or asserted as `StrapiBlockField` / your shared API types. |
| 58 | +- [ ] `data` points at the unmodified blocks array from the response. |
| 59 | +- [ ] Theme: choose `extend`, `overwrite`, or both with clear intent. |
| 60 | +- [ ] Custom block: props match README; use theme helpers for class names. |
| 61 | +- [ ] Lists: if styling nested markers, set `list.indent` arrays to enough depth. |
| 62 | + |
| 63 | +## Further reading |
| 64 | + |
| 65 | +- [reference.md](reference.md) — path cheat sheet and `StrapiBlockUserTheme` shape. |
| 66 | +- Package `README.md` in the repository root for default theme table and copy-paste examples. |
0 commit comments