Block library

The block library is a catalog of reusable page units. MagiCMS copies a chosen block into your project as src/blocks/<Name>/ and regenerates BlockRenderer.astro.

Each library entry ships as:

• <Name>.astro — the markup.
• <Name>.schema.json — the fields you edit in MagiCMS.
• optional <Name>.jsonLd.ts — structured data for that block type.
• preview.svg — thumbnail in the picker.

Field types, target slots and translation rules are the same for every block. See Content model and Schema field types rather than per-block reference pages.

Install from MagiCMS (Block types → library). After install, the copy in your project is yours: change the Astro component, trim schema fields, or add project-specific markup.

Reload from package overwrites that copy with the catalog version — useful for upstream fixes, destructive if you have local customisation. Reload does not overwrite shared kit files that already exist in src/lib/.

New block types for one project: node gen.mjs MyBlock, then install so the renderer picks them up. Naming stays PascalCase.

Some blocks import helpers from @/lib/ (for example chapter scroll and in-view motion). Those files are not companions next to the block; they are a named kit on the schema:

"projectKits": ["scene-presence"]

On install (and reload), MagiCMS copies the kit into your project only if the path is missing. The first block that lists the kit seeds the files; the next scene block skips them. Customised helpers are never overwritten.

This is not the same as Features (opt-in bundles such as News). A kit is a dependency the block declares so Blank sites still get working JavaScript when you install one scene block.

Shipped kit scene-presence: src/lib/inView.ts, chapterScroll.ts, sceneMotion.ts, sceneNavigator.ts. MagiCMS Block types shows which paths will be copied.

To add a kit in the MagiCMS codebase: put files under packages/ui/src/project-kits/<id>/ (folder paths = project paths), register the id in PROJECT_KITS (packages/ui/src/lib/projectKits.ts), then list it on the block schema.