Guides TYPO3 Content Blocks modeling for Content Elements, Record Types, Page Types, and File Types as the single source of truth. Use when creating, migrating, auditing, or debugging Content Blocks config.yaml files, make:content-block output, content elements, record types, page types, file types, collections, IRRE, labels, previews, or friendsoftypo3/content-blocks behavior.
Guides TYPO3 Content Blocks modeling for Content Elements, Record Types, Page Types, and File Types as the single source of truth. Use when creating, migrating, auditing, or debugging Content Blocks config.yaml files, make:content-block output, content elements, record types, page types, file types, collections, IRRE, labels, previews, or friendsoftypo3/content-blocks behavior.
compatibility
TYPO3 v14.3+ — `friendsoftypo3/content-blocks` 2.x (verify on [Packagist](https://packagist.org/packages/friendsoftypo3/content-blocks))
Compatibility: This skill targets TYPO3 v14.3+ with Content Blocks 2.x. Always match the Packagist friendsoftypo3/content-blocks constraint to your Core version.
For Content Blocks 1.x on TYPO3 v13, upstream requires () — confirm on Packagist.
Examples use TYPO3 v14 APIs and CB 2.x; adjust if upstream constraints differ.
TYPO3 ≥ 13.4
typo3/cms-core: ^13.4
composer.json
TYPO3 API First: Always use TYPO3's built-in APIs, core features, and established conventions before creating custom implementations. Do not reinvent what TYPO3 already provides. Always verify that the APIs and methods you use exist and are not deprecated in TYPO3 v14 by checking the official TYPO3 documentation.
Migration Coverage: Content Blocks migration and cross-skill handoff guidance are documented directly in this skill and its local add-ons.
1. The Single Source of Truth Principle
Content Blocks is the modern approach to creating custom content types in TYPO3. It eliminates redundancy by providing a single YAML configuration that generates:
TCA (Table Configuration Array)
Database schema (SQL)
TypoScript rendering
Backend forms and previews
Labels and translations
Why Content Blocks?
Traditional Approach
Content Blocks Approach
Multiple TCA files
One config.yaml
Manual SQL definitions
Auto-generated schema
Separate TypoScript
Auto-registered rendering
Scattered translations
Single labels.xlf
Complex setup
Simple folder structure
2. Installation
# Install via Composer (DDEV recommended)
ddev composer require friendsoftypo3/content-blocks
# After installation, clear caches
ddev typo3 cache:flush
Version constraint: Content Blocks 1.x requires TYPO3 ≥ 13.4 (typo3/cms-core: ^13.4 in the package). TYPO3 13.1–13.3 do not satisfy that Composer constraint.
Security Configuration (Classic Mode)
For non-composer installations, deny web access to ContentBlocks folder:
List under basics: to pull in Core field groups: TYPO3/Header, TYPO3/Appearance, TYPO3/Links, TYPO3/Categories. See the Content Blocks basics reference.
# EXT:my_sitepackage/ContentBlocks/ContentElements/hero-banner/config.yamlname:myvendor/hero-bannergroup:defaultdescription:"A full-width hero banner with image and CTA"prefixFields:trueprefixType:fullbasics:-TYPO3/Appearance-TYPO3/Linksfields:-identifier:headeruseExistingField:true-identifier:subheadlinetype:Textlabel:Subheadline-identifier:hero_imagetype:Fileminitems:1maxitems:1allowed:common-image-types-identifier:cta_linktype:Linklabel:CalltoActionLink-identifier:cta_texttype:Textlabel:ButtonText
When a Content Block should follow shadcn/ui styling, keep the Content Block YAML as the content model and move repeated visual structure into shared Fluid components. The frontend.fluid.html entrypoint should map {data} fields to typed atomic components rather than duplicating bespoke CSS in every block.
Preserve existing field identifiers, fixture.json, labels, and editor workflows unless the content model itself is changing.
Use shared Fluid components for shadcn primitives such as Button, Badge, Card, Form controls, Tabs, Accordion, Alert, Table, and Sheet/Dialog shells.
Put <f:argument> type contracts in reusable Fluid components and partials. Avoid adding required arguments to a Content Block entry template unless the render context is fully controlled.
Use f:asset.css / f:asset.script only for block-specific assets. Shared shadcn/Tailwind tokens and utility classes belong in the site CSS entrypoint.
For interactive shadcn patterns, use Alpine or small vanilla controllers with ARIA and data-state attributes instead of React/Radix runtime dependencies.
Create or update styleguide fixtures so every Content Block can be rendered with realistic content in light and dark mode.
Read the full guide when the task needs detailed examples, long templates, troubleshooting matrices, appendices, or sections not included above. Keep this file unloaded for narrow tasks so the skill follows progressive disclosure.
