Claude Code & TYPO3: A Practical Developer Guide
Development
What Are Site Sets in TYPO3 v13? Key Features & Configurations
Do you remember the days of digging through sys_template records, manually importing TypoScript, and juggling multiple @import statements? With TYPO3 v13, the core team has introduced Site Sets, a new concept designed to unify and modernize site-level configuration.
If you’re an editor or integrator/developer, you’ll love how Site Sets simplify setup, improve dependency management, and create cleaner, more maintainable TYPO3 projects.
In this article, we’ll explore the fundamentals of Site Sets, how they work behind the scenes, and why they are more than just a way of including TypoScript.
We’ll also provide examples for each step: from creating a custom set, defining your settings, and automatically loading TypoScript, to finally configuring everything with minimal database clutter.
Site Sets are available in TYPO3 v13 LTS and are designed to coexist with existing configuration approaches, allowing teams to adopt them incrementally during upgrades from earlier TYPO3 LTS versions.
What Are Site Sets?
Site Sets are composable pieces of configuration introduced in TYPO3 v13 (starting from version 13.1). They encapsulate various parts of a site’s configuration, TypoScript, TSconfig, settings definitions, reference-enabled content blocks, and more, into a single logical unit.
Instead of scattering configurations across static includes, ext_localconf.php, or sys_template records, Site Sets allow you to bundle everything neatly so you can:
- Apply these configurations to multiple TYPO3 sites with ease.
- Reuse the same sets across different projects or different subsets of a single project.
- Handle dependencies automatically, letting you layer multiple Site Sets on top of one another without worrying about load order conflicts.
What Site Sets Are and What They Are Not
- Are: Site-scoped configuration bundles that group related TypoScript, TSconfig, and settings.
- Are not: A replacement for TYPO3 Extensions, a TYPO3 Templates, or application-level business logic.
- Are optional: Site Sets are not mandatory in TYPO3 v13 and can be adopted incrementally alongside existing configuration approaches.
Why It’s Time to Drop Legacy Methods
In previous TYPO3 versions, adding new functionalities often involved multiple steps: creating static TypoScript includes, referencing them in your page or site template, or manually calling @import in TypoScript files.
This approach could get messy when multiple extensions were involved, leading to confusion in load order and duplication.
With Site Sets:
- No More Static TypoScript:
The classic way of storing TypoScript in sys_template records is often avoidable for many common scenarios, as configuration can now be delivered in a structured, site-scoped way. - No More Manual @import:
The load order can be handled through Site Set dependencies, reducing the need to manage @import statements manually. - No More Global TSconfig:
Page TSconfig can now be delivered per site, making multi-site setups easier to manage without relying on global configuration.
1. Cleaner Configuration
Gone are the days of storing TypoScript in sys_template records and dealing with @import complexities. Site Sets unify everything in well-defined directories.
2. Less Database Clutter
Settings once stored in multiple places are now consolidated in file-based YAML configurations, making version control easier.
3. Automatic Ordering & Deduplication
When multiple sets require the same snippet of TypoScript, dependencies are intelligently layered by TYPO3, no more conflicting or duplicated code blocks.
What TYPO3 Guarantees and What It Does Not
- Guaranteed: Declared Site Set dependencies are loaded in a defined order.
- Not guaranteed: TYPO3 does not resolve semantic or logical conflicts between configurations.
- Important: Deduplication applies to dependency loading, not to business logic or overlapping TypoScript definitions.
4. Editor-Friendly
A new Site Settings Editor in TYPO3 (introduced around v13.3) lets editors adjust settings via the backend, reducing the need to dive into YAML files or the database.
Basic Structure of a Site Set
A Site Set consists of a config.yaml file where you define metadata and dependencies, along with optional files to auto-load TypoScript, TSconfig, and custom settings.
1. config.yaml – The Core of Your Site Set
# EXT:your_extension/Configuration/Sets/YourSet/config.yaml
name: your-vendor/your-set
label: Your Set
# Provide references to other sets you want to include
dependencies:
- namespace/teaser
- namespace/slider
- namespace/myelement- name: A unique identifier for your set.
- label: The human-readable name for your set.
- dependencies: Other sets that your set depends on. TYPO3 will load these first, ensuring all configuration is available in the correct order.
2. settings.definitions.yaml – Defining Editable Settings
If your set needs to expose user-editable settings (for example, the default number of items in a carousel), you can declare them in settings.definitions.yaml.
# EXT:your_extension/Configuration/Sets/YourSet/settings.definitions.yaml
settings:
foo.bar.baz:
label: 'Your example set settings'
description: 'You need to add description'
type: int
default: 53. settings.yaml – Configuring Dependencies or Subsets
If your set depends on other sets, or you want to override their default settings, you place these overrides in settings.yaml.
# EXT:your_extension/Configuration/Sets/YourSet/settings.yaml
styles:
content:
defaultHeaderType: 1By organizing settings this way, your set remains flexible. Other extensions or projects can later inherit your set without having to re-define everything in multiple places.
What Should Not Be Placed in a Site Set
- Temporary overrides intended for short-lived changes
- Page-specific or one-off project hacks
- Experimental or unstable configuration that may change frequently
# EXT:your_extension/Configuration/Sets/YourSet/config.yaml
name: your-vendor/your-set
label: 'Your Set'
dependencies:
- namespace/teaser
- namespace/myelement- name: Uniquely identifies your set
- label: Display name in the TYPO3 backend
- dependencies: Sets that must be loaded first
2. Add Settings Definitions (settings.definitions.yaml)
# EXT:your_extension/Configuration/Sets/YourSet/settings.definitions.yaml
settings:
yourVendor.yourSet.maxSliderItems:
label: 'Maximum Slider Items'
description: 'Sets how many items can appear in the slider'
type: int
default: 5
yourVendor.yourSet.enableAdvancedMode:
label: 'Enable Advanced Mode'
description: 'Toggles additional features for power users'
type: bool
default: false3. Override Settings (settings.yaml)
# EXT:your_extension/Configuration/Sets/YourSet/settings.yaml
yourVendor.yourSet.maxSliderItems: 3
yourVendor.yourSet.enableAdvancedMode: true4. Automatically Load TypoScript
# EXT:your_extension/Configuration/Sets/YourSet/setup.typoscript
page = PAGE
page.10 = TEXT
page.10.value = This is loaded via My Site Set5. Automatically Load Page TSconfig
# EXT:your_extension/Configuration/Sets/YourSet/page.tsconfig
TCEFORM.tt_content {
imageorient.disabled = 1
}6. Apply the Set to a TYPO3 Site
# config/sites/your-site/config.yaml
base: 'https://your-domain.com/'
rootPageId: 1
dependencies:
- your-vendor/your-setTYPO3 loads the Site Set and its dependencies when initializing the site.
No More Static Include TypoScript, @import, Page TSconfig
TypoScript dependencies can now be included via Site Set dependencies, providing a structured alternative to legacy approaches such as static_file_include or manual @import statements. Configuration is resolved at the site level, reducing the need to manage inclusion order manually across templates or extensions.
Automatic TypoScript Loading
Inside the same directory as config.yaml, if you place setup.typoscript or constants.typoscript files, TYPO3 will load them automatically. This means:
EXT:your_extension/Configuration/Sets/YourSet/
│ ├─ config.yaml
│ ├─ setup.typoscript # Auto-loaded as TypoScript Setup
│ ├─ constants.typoscript # Auto-loaded as TypoScript Constants
│ └─ page.tsconfig # Auto-loaded as Page TSconfigBy using this structure, TypoScript can be provided without relying on manual @import statements or the “Include Static TypoScript” option in sys_template records. Inclusion is handled as part of the Site Set configuration at the site level.
Automatic Page TSconfig
Similar to TypoScript, Page TSconfig is applied on a site scope. By placing a page.tsconfig file next to your config.yaml, all pages belonging to that site inherit these TSconfig settings.
This allows fine-grained control at the site level and reduces the need for global TSconfig inclusion or manual registration in ext_localconf.php.
New Backend Module for Site Settings in TYPO3 v13.3
Starting with TYPO3 v13.3, a new Site Settings Editor module has been introduced. Editors and integrators can now manage per-site settings directly from the TYPO3 backend, rather than editing YAML files manually.
- Centralized Management: All site-specific settings are accessible under “Site Management > Settings.”
- Category Organization: Settings can be grouped into categories declared in settings.definitions.yaml.
- Minimal Change Footprint: Only modified values are stored, keeping your YAML configurations clean.
For instance, if you have a custom set with the following settings.definitions.yaml:
# EXT:my_extension/Configuration/Sets/MySet/settings.definitions.yaml
categories:
myCategory:
label: 'My Category'
settings:
my.example.setting:
label: 'My example setting'
category: myCategory
type: string
default: ''
my.seoRelevantSetting:
label: 'My SEO relevant setting'
category: seo
type: int
default: 5You’ll find a new section labeled “My Category” inside the Site Settings Editor, where you can override the default value of my.example.setting.
Responsibility Split: Developer vs Editor
- Developer: Defines the settings schema, data types, defaults, and categories in settings.definitions.yaml.
- Editor: Overrides allowed values through the Site Settings Editor in the TYPO3 backend.
- Storage: Definitions live in YAML files, while overridden values are stored separately and only persisted when changed.
Advanced Use Cases
Framework-Style Extensions
An extension can ship multiple sets (like “basic,” “pro,” “enterprise”), each with different configurations. Site admins select which set suits their site’s complexity.
Multi-Site Consistency
If running multiple sites that share features, you can ensure they all inherit the same base set while providing site-specific tweaks in separate settings.yaml or even via the Site Settings Editor.
Gradual Migration
For existing TYPO3 installations, you can gradually migrate older TypoScript to sets. Start with a single set, move your existing @import or static includes into setup.typoscript and constants.typoscript, and remove old references from sys_template once stable.
When Gradual Migration Is Not Recommended
Projects with highly experimental configuration, frequent short-term overrides, or unstable extension setups may benefit from postponing migration until configuration has stabilized.
Real-World Benefits of Including TYPO3 v13 Site sets
In practice, Site Sets primarily affect how configuration is structured and maintained, rather than introducing new frontend or editorial features.
- Time-Saving: Configuration is grouped at the site level, reducing the need to trace settings across multiple templates or inclusion mechanisms.
- Consistency: Shared configuration can be reused across sites, helping teams apply the same structural standards in multi-site environments.
- Reduced Global Scope: TypoScript, Page TSconfig, and settings are scoped per site, which helps limit unintended side effects in complex installations.
- Editor Interaction: Where settings are exposed deliberately, editors can adjust values through the backend without modifying configuration files.
- Ongoing Compatibility: Site Sets align with the configuration direction introduced in TYPO3 v13, allowing projects to follow current core conventions without relying on deprecated patterns.
Conclusion
Site Sets introduce a structured way to manage site-level configuration in TYPO3 v13 by grouping TypoScript, Page TSconfig, and settings into clearly defined, site-scoped units.
They reduce reliance on scattered configuration records and make dependencies between configuration layers more explicit. For teams working with multi-site setups, shared configuration, or long-running TYPO3 projects, Site Sets provide a consistent foundation that aligns with the configuration model introduced in TYPO3 v13.
At the same time, they are designed to coexist with existing approaches, allowing gradual adoption without forcing immediate refactoring.
As with other TYPO3 configuration mechanisms, their value depends on how deliberately they are used. Applied thoughtfully, Site Sets can help keep configuration maintainable and transparent as projects evolve.
FAQs
No. Site Sets are optional in TYPO3 v13 and coexist with existing configuration methods. Projects can continue using sys_template, static TypoScript, or extension-based configuration and adopt Site Sets gradually if and where they make sense.
No. Site Sets do not replace TypoScript. They provide a structured way to deliver and scope TypoScript at the site level, but TypoScript itself remains the configuration language used for rendering and behavior.
Yes. A TYPO3 site can depend on multiple Site Sets. TYPO3 resolves them based on declared dependencies and load order, allowing layered configuration without manual inclusion management.
Setting definitions are stored in YAML files within the Site Set. Only overridden values are persisted separately, allowing configuration to remain mostly file-based and version-controlled.
Yes. Site Sets are part of TYPO3 v13 LTS and are designed for long-term use. They are intended to support stable configuration management across minor updates within the v13 LTS lifecycle.
Not necessarily. Site Sets are most useful for extensions that deliver site-level configuration or reusable integration logic. Extensions focused purely on backend functionality or isolated features may not need them.
Post a Comment
Join over 5000+ T3Planet Community
Big thanks to the author for this detailed blog on TYPO3 v13 Site Sets! It explained everything I needed to know about setting them up and using them effectively. I now feel more confident managing my TYPO3 sites with these new features.