--- title: "Site sets" manual: "TYPO3 Explained" version: "13.4" permalink: "https://docs.typo3.org/permalink/t3coreapi:site-sets@13.4" source: "ApiOverview/SiteHandling/SiteSets.rst" rendered: "2026-09-23T17:02:48+00:00" --- # Site sets {#site-sets} Site sets have been introduced. Site sets ship parts of the site configuration as composable pieces. They are intended to deliver [settings](https://docs.typo3.org/permalink/t3coreapi:sitehandling-settings@13.4), [TypoScript](https://docs.typo3.org/m/typo3/reference-typoscript/13.4/en-us/Index.html#start) and [page TSconfig](https://docs.typo3.org/m/typo3/reference-typoscript/13.4/en-us/UsingSettingTSconfig/PageTSconfig.html#include-static-page-tsconfig-per-site) for the scope of a site. Extensions can provide multiple sets in order to ship presets for different sites or subsets (think of frameworks) where selected features are exposed as a subset (example: `typo3/seo-xml-sitemap`). **Table of content** - [Site set definition](https://docs.typo3.org/permalink/t3coreapi:site-set-definition@13.4) - [Using a site set as dependency in a site](https://docs.typo3.org/permalink/t3coreapi:using-a-site-set-as-dependency-in-a-site@13.4) - [Settings definitions](https://docs.typo3.org/permalink/t3coreapi:settings-definitions@13.4) - [Override site settings defaults by subsets](https://docs.typo3.org/permalink/t3coreapi:override-site-settings-defaults-by-subsets@13.4) - [TypoScript provider](https://docs.typo3.org/permalink/t3coreapi:typoscript-provider@13.4) - [Page TSconfig provider](https://docs.typo3.org/permalink/t3coreapi:page-tsconfig-provider@13.4) - [Analyzing the available site sets via console command](https://docs.typo3.org/permalink/t3coreapi:analyzing-the-available-site-sets-via-console-command@13.4) - [Example: Using a set within a site package](https://docs.typo3.org/permalink/t3coreapi:example-using-a-set-within-a-site-package@13.4) - [Example: Providing a site set in an extension](https://docs.typo3.org/permalink/t3coreapi:example-providing-a-site-set-in-an-extension@13.4) - [Site Set PHP API](https://docs.typo3.org/permalink/t3coreapi:site-set-php-api@13.4) ## Site set definition {#site-sets-definition} A site set definition contains the configuration for site settings, TypoScript and PageTSConfig and can be assigned to one or more sites via the site module. Site set definitions are created in the `Configuration/Sets/` directory and separated from each other by a sub-folder with any name. In this way, it is also possible to create several site set definitions per extension. Each of these sub-folders must have a [`config.yaml`](../../ExtensionArchitecture/FileStructure/Configuration/Sets/Index.md#file-set-config-yaml) that assigns at least a unique `name` and preferably also a unique `label` to the site set definition. **EXT:my_extension/Configuration/Sets/MySet/config.yaml** ```yaml name: my-vendor/my-set label: My Set settings: website: background: color: '#386492' dependencies: - my-vendor/my-other-set - other-namespace/fancy-carousel optionalDependencies: - typo3/form ``` - **Line 1: `name: my-vendor/my-set`** Site Set Name Similar to the package name of Composer: `[Vendor]/[Package]` Is required to uniquely identify the site set and to resolve dependencies to other site sets. This name does NOT reflect an extension, but only the provider of an extension through the vendor name. There are NO conclusions from the name here as to which extension provided the site set definition. - **Line 2: `label: My Set`** This label will be used in the new select box of the site module. Should be as unique as possible to avoid duplication in the site module. - **Line 3-6: Settings** Define settings for the website. **Never** nest settings with a dot! e.g. `website.background.color` Otherwise the new settings definitions will not work later. If a setting value contains special characters or spaces, it is recommended to wrap the value in single quotes. You can also define settings in a separate file `settings.yaml`. See section below. - **Line 7: Dependencies** Load `setup.typoscript`, `constants.typoscript`, `page.tsconfig` and `config.yaml` from the site set definitions of this or other extensions. These dependencies are loaded before your own site set. For example a dependency to a site set definition in your own site package and/or a dependency to a site set definition from another provider (vendor). A non-existing dependency makes the whole site set report failures. - **Line 10: Optional dependencies** The files `setup.typoscript`, `constants.typoscript`, `page.tsconfig` and `config.yaml` from the site set definitions of this or other extensions are loaded only if the providing extension is installed. Otherwise, the site set is loaded simply without these and no errors are reported (in contrast to `dependencies`). ### Hidden site sets {#site-sets-hidden} Sets may be hidden from the backend set selection in **Site Management > Sites** and the console command `bin/typo3 site:sets:list` by adding a `hidden` flag to the [`config.yaml`](../../ExtensionArchitecture/FileStructure/Configuration/Sets/Index.md#file-set-config-yaml) definition: **EXT:my_extension/Configuration/Sets/MyHelperSet/config.yaml** ```yaml name: my-vendor/my-helperset label: A helper Set that is not visible inside the GUI hidden: true ``` Integrators may choose to hide existing sets from the list of available sets for backend users via user TSconfig, in case only a curated list of sets shall be selectable: **EXT:my_extension/Configuration/user.tsconfig** ```typoscript options.sites.hideSets := addToList(typo3/fluid-styled-content) ``` ## Using a site set as dependency in a site {#site-sets-usage} Sets are applied to sites via `dependencies` array in site configuration, optional dependencies listed in `optionalDependencies`: **config/sites/my-site/config.yaml** ```yaml base: 'https://example.com/' rootPageId: 1 dependencies: - my-vendor/my-set optionalDependencies: - typo3/form ``` Site sets can also be added to a site via the backend module **Site Management > Sites**. ## Settings definitions {#site-sets-settings-definition} Settings can be defined in a file called [`settings.definitions.yaml`](../../ExtensionArchitecture/FileStructure/Configuration/Sets/Index.md#file-set-settings-definitions-yaml) in a set, for example [`EXT:my_extension/Configuration/Sets/MySet/settings.definitions.yaml`](../../ExtensionArchitecture/FileStructure/Configuration/Sets/Index.md#file-set-settings-definitions-yaml). Read more about [Site settings definitions](https://docs.typo3.org/permalink/t3coreapi:site-settings-definition@13.4). Settings have a default value that can be [overridden within a set](https://docs.typo3.org/permalink/t3coreapi:site-sets-settings@13.4). ## Override site settings defaults by subsets {#site-sets-settings} Settings for subsets (for example to configure settings in declared dependencies) can be shipped via [`settings.yaml`](../../ExtensionArchitecture/FileStructure/Configuration/Sets/Index.md#file-set-settings-yaml) when placed next to the set file [`config.yaml`](../../ExtensionArchitecture/FileStructure/Configuration/Sets/Index.md#file-set-config-yaml). Note that default values for settings provided by the set do not need to be defined here, as defaults are to be provided within [`settings.definitions.yaml`](../../ExtensionArchitecture/FileStructure/Configuration/Sets/Index.md#file-set-settings-definitions-yaml). Here is an example where the setting `styles.content.defaultHeaderType` as provided by `typo3/fluid-styled-content` is configured via `settings.yaml`: **EXT:my_extension/Configuration/Sets/MySet/settings.yaml** ```yaml styles.content.defaultHeaderType: 1 ``` The settings in settings.yaml are stored as map instead of tree.Important: #106894 - Site settings.yaml is now stored as a map This setting will be exposed as site setting whenever the set `my-vendor/my-set` is applied as dependency to a site configuration. ## TypoScript provider {#site-sets-typoscript} TypoScript dependencies can be included via set dependencies. This mechanism is much more effective than the previous [static includes](https://docs.typo3.org/m/typo3/reference-typoscript/13.4/en-us/UsingSetting/AddTypoScriptWithExtensions.html#extdev-static-includes) or manual `@import` statements. TypoScript dependencies via sets are automatically ordered and deduplicated. Set-defined TypoScript can be shipped within a set. The files [`setup.typoscript`](../../ExtensionArchitecture/FileStructure/Configuration/Sets/Index.md#file-set-setup-typoscript) and [`constants.typoscript`](../../ExtensionArchitecture/FileStructure/Configuration/Sets/Index.md#file-set-constants-typoscript) (placed next to the [`config.yaml`](../../ExtensionArchitecture/FileStructure/Configuration/Sets/Index.md#file-set-config-yaml) file) will be loaded, if available. They are inserted (similar to `static_file_include`) into the TypoScript chain of the site TypoScript. Set constants will always be overruled by site settings. Since site settings always provide a default value, a constant will always be overruled by a defined setting. This can be used to provide backward compatibility with TYPO3 v12 in extensions, where constants shall be used in v12, while v13 will always prefer defined site settings. In contrast to `static_file_include`, dependencies are to be included via sets. Dependencies are included recursively. This mechanism supersedes the previous include via `static_file_include` or manual `@import` statements as sets are automatically ordered and deduplicated. That means TypoScript will not be loaded multiple times, if a shared dependency is required by multiple sets. Dependencies can also be optional, see [Defining the site set with an optional EXT:form dependency](https://docs.typo3.org/permalink/t3coreapi:site-sets-example-site-package-set-optional@13.4). > [!NOTE] > `@import` statements are still fine to be used for local > includes, but should be avoided for cross-set/extensions dependencies. > [!WARNING] > **Attention** > > If the website uses a mixed setup consisting of a TypoScript template (`sys_template`) > and site sets, it is important to uncheck the "Clear" flag for constants and > setup in the TypoScript template. If the "Clear" flag is checked (default), > TypoScript settings from site sets are cleared and do therefore not apply. ## Page TSconfig provider {#site-sets-page-tsconfig} Page TSconfig is loaded from a file [`page.tsconfig`](../../ExtensionArchitecture/FileStructure/Configuration/Sets/Index.md#file-set-page-tsconfig), if placed next to the site set configuration file [`config.yaml`](../../ExtensionArchitecture/FileStructure/Configuration/Sets/Index.md#file-set-config-yaml) and is scoped to pages within sites that depend on this set. Therefore, extensions can ship page TSconfig without the need for database entries or by polluting global scope when registering page TSconfig globally via [`ext_localconf.php`](../../ExtensionArchitecture/FileStructure/ExtLocalconf.md#file-extension-ext-localconf-php) or [`Configuration/TCA/Overrides/pages.php`](../../ExtensionArchitecture/FileStructure/Configuration/TCA/Index.md#file-extension-configuration-tca-overridessomefile-php). Dependencies can be expressed via sets, allowing for automatic ordering and deduplication. ## Analyzing the available site sets via console command {#site-sets-cli} A list of available site sets can be retrieved with the console command `bin/typo3 site:sets:list`: **Composer-based installation** ```bash vendor/bin/typo3 site:sets:list ``` **Classic mode installation (No Composer)** ```bash typo3/sysext/core/bin/typo3 site:sets:list ``` ## Example: Using a set within a site package {#site-sets-example-site-package} You can see an example of using a set within a site package in the extension [t3docs/site-package (Source on GitHub)](https://github.com/TYPO3-Documentation/TYPO3CMS-Tutorial-SitePackage-Code). The site package example extension has the following file structure: - Configuration - Sets - SitePackage - config.yaml - constants.typoscript - page.tsconfig - settings.yaml - setup.typoscript - ... - Resources - ... - [`composer.json`](../../ExtensionArchitecture/FileStructure/ComposerJson.md#file-extension-composer-json) - ... ### Defining the site set with an EXT:fluid_styled_content dependency {#site-sets-example-site-package-set} As our example site package only contains one site set the name of that set is the same as the Composer name of the site package. The site package depends on [EXT:fluid_styled_content](https://docs.typo3.org/c/typo3/cms-fluid-styled-content/13.4/en-us/Index.html#start). Therefore the two sets provided by that system extension are included as dependencies: **EXT:site_package/Configuration/Sets/SitePackage/config.yaml** ```yaml name: t3docs/site-package label: 'Site Package' dependencies: - typo3/fluid-styled-content - typo3/fluid-styled-content-css ``` If you need additional dependencies, you can find all available sets with the console command [bin/typo3 site:sets:list](https://docs.typo3.org/permalink/t3coreapi:site-sets-cli@13.4). ### Defining the site set with an optional EXT:form dependency {#site-sets-example-site-package-set-optional} Site sets can also have optional dependencies, a bit like how `suggest` works in `composer.json` files (see [Properties](https://docs.typo3.org/permalink/t3coreapi:ext-composer-json-properties@13.4)): An optional dependency will only load the listed definitions in case the mentioned site set is available. If a listed site set is not installed, no error will be reported and the listed dependency is simply not loaded. In this example, the `typo3/form` dependency would be loaded based on the availability of the `EXT:form` extension: **EXT:site_package/Configuration/Sets/SitePackage/config.yaml** ```yaml name: t3docs/site-package label: 'Site Package with optional dependency' dependencies: - typo3/fluid-styled-content - typo3/fluid-styled-content-css optionalDependencies: - typo3/form ``` > [!TIP] > **Hint** > > If you include optional dependencies, be sure to make all other code > (PHP, Fluid, ...) also operate gracefully on this condition, and be > sure to list the extension in the composer's `suggest` key. ### Using the site set as dependency of a site {#site-sets-example-usage} After the example site package is installed, you can include the site set in your site configuration: **config/sites/\/config.yaml | typo3conf/sites/\/config.yaml** ```yaml base: 'https://site-package.ddev.site' dependencies: - t3docs/site-package rootPageId: 1 ``` ### Loading TypoScript via the site package's set {#site-sets-example-typoscript} The example site package also loads its TypoScript by placing the files `constants.typoscript` and `setup.typoscript` into the folder of the site set. These files use `@import` statements to import third party TypoScript files into this extension's directory `Configuration/Sets/SitePackage/TypoScript`: **EXT:site_package/Configuration/Sets/SitePackage/setup.typoscript** ```typoscript @import './TypoScript/*.typoscript' @import './TypoScript/Navigation/*.typoscript' ``` Dependant TypoScript is included by the dependant sets and not by TypoScript imports. ### Using the site set to override default settings {#site-sets-example-settings} The settings in settings.yaml are stored as map instead of tree.Important: #106894 - Site settings.yaml is now stored as a map In this example the file [`EXT:site_package/Configuration/Sets/SitePackage/settings.yaml`](../../ExtensionArchitecture/FileStructure/Configuration/Sets/Index.md#file-set-settings-yaml) is used to override default settings made by the set of [EXT:fluid_styled_content](https://docs.typo3.org/c/typo3/cms-fluid-styled-content/13.4/en-us/Index.html#start): **EXT:site_package/Configuration/Sets/SitePackage/settings.yaml** ```yaml styles.templates.layoutRootPath: EXT:my_site_package/Resources/Private/ContentElements/Layouts styles.templates.partialRootPath: EXT:my_site_package/Resources/Private/ContentElements/Partials styles.templates.templateRootPath: EXT:my_site_package/Resources/Private/ContentElements/Templates styles.content.textmedia.maxW: 1200 styles.content.textmedia.maxWInText: 600 styles.content.textmedia.linkWraplightboxEnabled: true styles.content.textmedia.lightboxCssClass: lightbox ``` ## Example: Providing a site set in an extension {#site-sets-example-extension} Non site-package extensions can also provide site sets. These can be used by sites or site sets to include dependant TypoScript and settings. The example extension [`t3docs/blog-example`](https://packagist.org/packages/t3docs/blog-example) offers one main site set and several site sets for special use-cases. It has the following file structure: - Classes - ... - Configuration - Sets - BlogExample - config.yaml - constants.typoscript - page.tsconfig - setup.typoscript - DefaultStyles - config.yaml - setup.typoscript - RssFeed - config.yaml - constants.typoscript - setup.typoscript - ... - Resources - ... - composer.json - ... ### Multiple site sets to include separate functionality {#site-sets-example-extension-multiple-sets} The main site set of the extension has the same name as the Composer name: **EXT:blog_example/Configuration/Sets/BlogExample/config.yaml** ```yaml name: t3docs/blog-example label: Blog example set ``` The other two sets depend on this set being loaded and therefore declare it as dependency: **EXT:blog_example/Configuration/Sets/DefaultStyles/config.yaml** ```yaml name: t3docs/blog-example-styles label: Blog example default styles dependencies: - t3docs/blog-example ``` **EXT:blog_example/Configuration/Sets/RssFeed/config.yaml** ```yaml name: t3docs/blog-example-rss label: Blog example RSS feed dependencies: - t3docs/blog-example ``` The additional site sets provide TypoScript configuration that depends on the base site set. They do not use `@include` statements to include the base TypoScript. The dependencies defined in the site set take care of the correct loading order of the TypoScript. ## Site Set PHP API {#site-sets-php-api} ### Site {#site-sets-php-api-site} The site settings can be read out via the site object: ```php $color = $site->getSettings()->get('website.background.color'); ``` If a settings definition exists for this setting, the returned value has already been validated, converted and, if not set, the default value is used. ### SetRegistry {#site-sets-php-api-setregistry} The `\TYPO3\CMS\Core\Site\Set\SetRegistry` retrieves the site sets found in an ordered sequence, as defined by `dependencies` in `config.yaml`. Please preferably use the site object to access the required data. However, if you need to query one or more site set definitions in order as defined by dependencies, then `\TYPO3\CMS\Core\Site\Set\SetRegistry` is the right place to go. To read all site set definitions, please use `\TYPO3\CMS\Core\Site\Set\SetCollector`. #### getSets {#site-sets-php-api-setregistry-getsets} Reads one or more site set definitions including their dependencies. ```php $sets = $setRegistry->getSets('my-vendor/my-set', 'my-vendor/my-set-two'); ``` #### hasSet {#site-sets-php-api-setregistry-hasset} Checks whether a site set definition is available. ```php $hasSet = $setRegistry->hasSet('my-vendor/my-set'); ``` #### getSet {#site-sets-php-api-setregistry-getset} Reads a site set definition WITHOUT dependencies. ```php $set = $setRegistry->getSet('my-vendor/my-set'); ``` #### SetCollector {#site-sets-php-api-setcollector} TYPO3 comes with a new `ServiceProvider`, which goes through all extensions with the first instantiation of the `\TYPO3\CMS\Core\Site\Set\SetCollector` and reads all site set definitions found. ```php public function __construct( #[Autowire(lazy: true)] protected SetCollector $setCollector, ) {} ``` However, this is not the official way to access the site set definitions and their dependencies. Please access the configuration via the site object. Alternatively you can also use the `\TYPO3\CMS\Core\Site\Set\SetRegistry` as only this manages the site sets in the order declared by the dependency specification. Only use the `\TYPO3\CMS\Core\Site\Set\SetCollector` if you need to read all site set definitions. Dependencies are not taken into account here.