How to migrate from Mask to Content blocks in TYPO3
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 fancy new 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.
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.
The Why: Goodbye, 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 sys_template records is eliminated for many common scenarios.
- No More Manual @import: The load order is handled by the sets themselves, so you don’t have to do it by hand.
- No More Global TSconfig: Page TSconfig can now be delivered per site, making multi-site setups simpler.
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.
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.
Step-by-Step: Creating and Applying a Site Set
1. Define Your Set (config.yaml)
Every Site Set starts with a config.yaml file. Here’s a basic example:
# 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: A descriptive name visible in the TYPO3 backend.
- dependencies: Other sets that need to be loaded first, ensuring proper load order.
2. Add Settings Definitions (settings.definitions.yaml)
If your Site Set offers configurable options (e.g., a max number of sliders), define them here. This ensures your settings have labels, descriptions, and predefined data types.
# 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)
If you need to override default settings—either your own or those of a dependency—place those overrides in settings.yaml:
# EXT:your_extension/Configuration/Sets/YourSet/settings.yaml
yourVendor.yourSet.maxSliderItems: 3
yourVendor.yourSet.enableAdvancedMode: true4. Automatically Load TypoScript
By placing setup.typoscript or constants.typoscript next to config.yaml, TYPO3 automatically includes them. No more fiddling with “Include Static TypoScript” in the Template module or @import statements.
# 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
Similarly, page.tsconfig in the same folder is automatically applied to all pages within any site using this set:
# EXT:your_extension/Configuration/Sets/YourSet/page.tsconfig
TCEFORM.tt_content {
imageorient.disabled = 1
}6. Apply the Set to a TYPO3 Site
In your site’s YAML file:
# config/sites/your-site/config.yaml
base: 'https://your-domain.com/'
rootPageId: 1
dependencies:
- your-vendor/your-setTYPO3 will now load your set (and its dependencies) whenever it initializes this site.
No More Static Include TypoScript, @import, Page TSconfig
TypoScript dependencies can now be included via set dependencies, which is more effective than previous methods like static_file_include or manual @import statements. Sets automatically handle ordering and deduplication.
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, you can completely bypass @import statements or the “Include Static TypoScript” method in the sys_template record. The Site Set system handles ordering and deduplication, eliminating conflicts when multiple sets load the same snippet.
Automatic Page TSconfig
Similar to TypoScript, Page TSconfig is now site-scoped. By simply placing a page.tsconfig file next to your config.yaml, all pages belonging to that site will inherit these TSconfig settings. This allows fine-grained control and avoids 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.
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.
Real-World Benefits of Including TYPO3 v13 Site sets
- Time-Saving: No more scattered templates or manual import statements.
- Consistency: All site configurations follow a uniform structure, making multi-site setups more manageable.
- Less Global Overreach: Page TSconfig, TypoScript, and settings are scoped exactly where needed (i.e., per site), minimizing conflicts.
- Editor Empowerment: The Site Settings Editor provides a clear interface, reducing developer overhead and mistakes.
- Future-Ready: The TYPO3 core is set to further optimize Site Sets, meaning your projects stay aligned with upcoming TYPO3 features and best practices.
Key Takeaways
- Clean Configuration: Bundling TypoScript, TSconfig, and settings into sets reduces clutter and confusion.
- Dependency Management: Load order is automatically handled, preventing duplication and conflicts.
- Editor-Friendly: Thanks to the Site Settings Editor, custom settings become easily tweakable by non-developers.
- Future-Proof: The official TYPO3 roadmap indicates continued enhancements, so adopting Site Sets now sets you up for future improvements in v13 and beyond.
Conclusion
TYPO3’s introduction of Site Sets marks a major leap forward in how we organize and manage site configurations. By bundling TypoScript, TSconfig, and extension settings into self-contained sets, the platform provides a more intuitive, scalable, and conflict-free system. Whether you’re an editor who wants consistent, well-documented features or a developer who values maintainable architectures, Site Sets offer a modern solution that evolves with future TYPO3 releases.
If you’re upgrading to TYPO3 v13, exploring Site Sets should be one of your top priorities. Embrace this new approach, reduce manual overhead, and get ready for even more features in upcoming TYPO3 sprint releases. Happy coding and site building!
Post a Comment
Join over 4300+ TYPO3 Subscribers
Sanjay Chauhan
CTO at T3Planet & NITSANSanjay Chauhan, Co-Founder of NITSAN (Award winning TYPO3 agency) and Pioneer of T3Planet (first-ever TYPO3 Shop).
A true TYPO3 fanatic since 2010. I bring strong TYPO3 experience in building customer-business…
More From Author