AI Assistant
AI Chatbot
AI Search
AI Accessibility
AI Localization
AI Builder
TYPO3 _assets: How to Migrate typo3conf/ext Assets in Composer
Development
TYPO3 Site Sets: What They Are and How to Use Them in v13 and v14
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 introduced Site Sets to unify and modernise site-level configuration.
Site Sets simplify setup, improve dependency management, and create cleaner TYPO3 projects. Alongside this modern configuration approach, the AI Foundation for TYPO3 can provide one shared foundation for AI providers, tools, contexts, and permissions.
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 TYPO3 upgrade from earlier TYPO3 LTS versions.
Short answer: what are TYPO3 Site Sets?
A TYPO3 Site Set is a reusable bundle of site configuration stored in an extension’s Configuration/Sets/ folder. It holds a config.yaml plus optional TypoScript, page TSconfig and settings files. A site activates it by listing the set under dependencies in its config.yaml. Site Sets exist since TYPO3 v13.1 and work in v13.4 LTS and v14 LTS.
Key takeaways
- Only config.yaml is required; setup.typoscript, constants.typoscript, page.tsconfig, settings.definitions.yaml and settings.yaml are optional.
- Dependencies are resolved recursively, ordered and deduplicated, so you no longer manage include order by hand.
- Settings defined in settings.definitions.yaml appear in the backend settings editor and are available in TypoScript as constants.
- A site that uses sets needs no sys_template record. Existing records still load, after the site’s TypoScript.
- TYPO3 v14 adds route enhancers in sets (v14.1) and moves the settings editor to Sites > Setup.
Valid for: TYPO3 v13.4 LTS and v14.3 LTS, checked against the official documentation on docs.typo3.org.
Updated: November 2026
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 replace static templates with Site Sets?
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 in v13.3, Feature #104794) lets editors adjust settings via the backend, reducing the need to dive into YAML files or the database.
Site Sets vs classic static templates: what is the difference?
Site Sets deliver configuration from files per site, while static templates are switched on in a sys_template database record. Both still work in TYPO3 v13 and v14; the TypoScript Reference 14.3 recommends sets for v13 and later.
| Method | Works in | Best for | Caveat |
| Site Set (Configuration/Sets + site dependencies) | v13.1 and later, v13.4 LTS, v14 | New projects, multi-site setups, reusable site packages | Not available in v12; ext_typoscript_setup.typoscript is not loaded |
| Static include in a sys_template record (addStaticFile) | v12, v13, v14 | Existing projects, extensions that must also support v12 | Stored in the database; include order is set by hand per record |
| @import in TypoScript files | v12, v13, v14 | Splitting files inside one set or package | Avoid it for dependencies between sets or extensions |
| ext_typoscript_setup.typoscript | v12, v13, v14 (sites with sys_template records) | Legacy global TypoScript | Ignored when the site gets its TypoScript from sets |
Rule of thumb: use a Site Set on v13 and v14. Add a static include only if an extension must still support v12.
What files does a Site Set contain?
A Site Set is a folder below Configuration/Sets/ in an extension. Only config.yaml is required: it holds the set name, label and dependencies. Optional files next to it auto-load TypoScript, page TSconfig and settings (TYPO3 Explained: Site sets).
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 – Setting values for your set or its dependencies
settings.yaml changes the values of settings that your set or one of its dependencies defines; it never defines a setting itself. In the example, styles.content.defaultHeaderType comes from the Fluid Styled Content set (type int, default 2), so your set needs typo3/fluid-styled-content as a dependency. Since TYPO3 13.4.x the recommended format is a flat map with dotted keys; nested trees are still read (Important #106894).
# EXT:your_extension/Configuration/Sets/YourSet/settings.yaml
# Overrides a setting defined by the set typo3/fluid-styled-content
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
How do you create and apply a Site Set?
Create a folder below Configuration/Sets/ in your extension or site package, add a config.yaml with name and label, add the optional settings and TypoScript files, then list the set name under dependencies in the site’s config.yaml. The six steps below show each file.
1. Define Your Set (config.yaml)
# 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.
Minimal working example: a complete Site Set
The example below is a complete, minimal site package set. It defines one editable setting, uses it in TypoScript and activates the set for one site. File names and keys follow the Site sets chapter of TYPO3 Explained 14.3 and work the same way in v13.4.
Folder structure
my_sitepackage/
└─ Configuration/
└─ Sets/
└─ SitePackage/
├─ config.yaml # required
├─ settings.definitions.yaml # optional: editable settings
├─ setup.typoscript # optional: TypoScript setup
└─ page.tsconfig # optional: page TSconfig
config/sites/main/
├─ config.yaml # site configuration
└─ settings.yaml # values saved by the settings editorconfig.yaml and settings.definitions.yaml
# EXT:my_sitepackage/Configuration/Sets/SitePackage/config.yaml
name: my-vendor/my-sitepackage
label: 'My site package'
dependencies:
- typo3/fluid-styled-content
# EXT:my_sitepackage/Configuration/Sets/SitePackage/settings.definitions.yaml
categories:
MySitePackage:
label: 'My site package'
settings:
MySitePackage.footerText:
label: 'Footer text'
category: MySitePackage
type: string
default: 'Powered by TYPO3'setup.typoscript: use the setting as a constant
Site settings are available in TypoScript with the constants syntax, and in PAGEVIEW templates as {settings} (Site Package Tutorial).
# EXT:my_sitepackage/Configuration/Sets/SitePackage/setup.typoscript
page = PAGE
page.10 = TEXT
page.10.value = {$MySitePackage.footerText}Activate the set for a site
# config/sites/main/config.yaml
base: 'https://example.com/'
rootPageId: 1
dependencies:
- my-vendor/my-sitepackage
# config/sites/main/settings.yaml (map format, written by the settings editor)
MySitePackage.footerText: 'Example GmbH'Flush the caches and run vendor/bin/typo3 site:sets:list (Composer mode) or typo3/sysext/core/bin/typo3 site:sets:list (Classic mode) to confirm that TYPO3 finds the set. The root page needs no sys_template record, because the site itself provides the TypoScript. The frontend now prints “Example GmbH”, and an administrator can change the value in the settings editor.
For a ready-made reference, the T3Karma multipurpose template is a TYPO3 template with Site Sets: its version 14.0.0 (April 2026) moved the theme configuration into Site Sets.
Free guide: Upgrade Playbook for TYPO3
Switching from static includes to Site Sets usually happens during an upgrade to v13 or v14. The free Upgrade Playbook plans that upgrade in four phases, with an Excel worksheet for your extension list.
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.
Sovereign TYPO3 AI
AI Foundation for TYPO3T3AF
The base every extension runs on. Manage providers, prompts, permissions and costs in one place.
How does a Site Set load TypoScript?
Place setup.typoscript and constants.typoscript next to config.yaml and TYPO3 loads them automatically for every site that depends on the set. They are inserted into the site’s TypoScript chain much like a static include, and site settings always overrule set constants (Feature #103439). The folder then looks like this:
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.
How does a Site Set load 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.
How do you edit site settings in the backend?
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: In TYPO3 v13 all site-specific settings are under “Site Management > Settings”. In TYPO3 v14, Site Management is called Sites and the settings editor is part of “Sites > Setup” (Feature #107628).
- Category Organization: Settings can be grouped into categories declared in settings.definitions.yaml.
- Minimal Change Footprint: Only values that differ from the set defaults are written to config/sites/<site>/settings.yaml. In v13.3 the module was available to administrators only (Feature #104794).
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.
What changed for Site Sets in TYPO3 v14?
Site Sets work the same way in TYPO3 v14; the main changes are route enhancers in sets and new backend module names. As of November 2026, get.typo3.org lists TYPO3 v14.3 as the LTS release for new projects and v13.4 LTS with free support until 31 December 2027; both run on PHP 8.2 to 8.5.
- Route enhancers in sets (v14.1): a set can ship a route-enhancers.yaml next to its config.yaml. Enhancers load in dependency order, and the site configuration still wins (Feature #107837). Our TYPO3 routing guide for v13 and v14 explains route enhancers in detail.
- New module names (v14.0): Site Management is now called Sites, and the former Settings module is part of Sites > Setup (Feature #107628).
- settings.yaml as a map (13.4.x and v14): the settings editor writes flat keys such as
foo.bar: 'value'. Nested trees are still read, but sets should use the map format (Important #106894).
For everything else that is new, see our TYPO3 v14 release notes and upgrade guide.
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.
How do you migrate from static templates to Site Sets?
Migrate one site at a time: rebuild the sys_template record as a Site Set, compare the output, then remove the record. Sources: the v13.1 changelog and the TypoScript Reference 14.3.
- List what the root sys_template record contains: static includes, constants, setup and every @import.
- Run
site:sets:listto see which installed extensions already ship sets, for example typo3/fluid-styled-content. - Create a set in your site package and list those extension sets under dependencies instead of the static includes.
- Move setup and constants into setup.typoscript and constants.typoscript of the set. Keep @import only for files inside the same package.
- For constants that editors should change, define a setting with the same name in settings.definitions.yaml; site settings overrule set constants.
- Move page TSconfig into page.tsconfig of the set, and anything from ext_typoscript_setup.typoscript into setup.typoscript.
- Add the set to the site’s dependencies, in config.yaml or in the backend (v13: Site Management > Sites, v14: Sites > Setup).
- Compare the frontend output, then remove the old sys_template record. If it stays, it is applied after the site’s TypoScript and can override it.
Common mistakes and troubleshooting
Most Site Set problems come from naming, missing setting definitions or template scope. Check these first:
- The set is not listed: check that the extension is installed, that name is unique in vendor/name form, and that the set is not hidden with
hidden: trueor the user TSconfig optionoptions.sites.hideSets. - A value in settings.yaml has no effect: the setting needs a definition in settings.definitions.yaml of the set or one of its dependencies.
- Settings are empty in a content element template: {settings} is available in PAGEVIEW templates; FLUIDTEMPLATE-based templates need a data processor.
What are the real-world benefits of 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 legacy patterns. Static includes in sys_template records still work in v13 and v14, but the TypoScript reference recommends sets for v13 and later.
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.
Plan the upgrade that brings Site Sets
Site Sets need TYPO3 v13 or v14. The free Upgrade Playbook for TYPO3 takes you from inventory to go-live, with a worksheet for your extensions.
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.
Sovereign TYPO3 AI: AI Foundation is free and open source, six AI extensions build on it.
Explore TYPO3 AI
Join over 5000+ T3Planet Community
Wolfgang Weber
Brand & Communication LeadWolfgang Weber shapes TYPO3 with passion and expertise. As a TYPO3 enthusiast at T3Planet Shop, he has contributed to TYPO3 projects that make websites faster and more secure. Outside of TYPO3, you’ll probably find him exploring local cafés and enjoying football.
More From Author