TYPO3 Site Configuration: Guide for v13 and v14

Since TYPO3 v9, every site in a TYPO3 installation has its own site configuration with a dedicated backend module. This step-by-step guide (for beginners to advanced level) covers TYPO3 site config from its start in TYPO3 v9 and v10 up to the current LTS versions TYPO3 v13.4 and v14.

TYPO3 Site Management provides a modern way to manage single or multi-site installations. Available since TYPO3 v9, site configuration defines each site’s entry point, languages, routing, error handling, and other essential settings. For projects that also use AI, the AI Foundation for TYPO3 adds a central backend layer for configuring providers, contexts, permissions, budgets, and AI workflows.

IMHO, TYPO3 site configuration is one of the late but great decisions by the TYPO3 community.

TYPO3 has already had multi-site and multi-language features for 20+ years, but with lots of complicated and unstructured tons of TypoScript, RealURL configuration, Domain records, etc. 

But now, using the TYPO3 site backend module, we have structured and easy-to-use management of the TYPO3 sites.

Are you a beginner or intermediate level at TYPO3 site configuration? Then, get ready to gain in-depth knowledge about TYPO3 site management.

Short answer: TYPO3 site configuration is a YAML file, config/sites/<identifier>/config.yaml, that defines each site’s root page, base URL, languages, error pages, static routes and route enhancers. You edit it in the backend under Site Management > Sites (TYPO3 v13) or Sites > Setup (TYPO3 v14), or directly in the file under version control.

Key takeaways

• Every site needs a root page (rootPageId), a base and at least one language with languageId: 0.
• Since TYPO3 v12.1, site settings live in settings.yaml. A settings block in config.yaml is ignored once that file exists.
• Site Sets (TYPO3 v13.1 and later) bundle settings, TypoScript and page TSconfig. A site activates them under dependencies; since TYPO3 v14.1 sets can also provide route enhancers.
• The language keys typo3Language, iso-639-1 and direction are deprecated since TYPO3 v12.3. TYPO3 derives them from locale.

Tested with / valid for: TYPO3 v13.4 LTS and v14 (14.3 LTS), checked against TYPO3 Explained: Site handling.
Updated: November 2026

The classic way configured domains, languages and error pages with TypoScript, domain records and the RealURL extension. The modern way, available since TYPO3 v9, keeps all of this in one site configuration per site.

For the beginners, It’s important to understand what’s a major difference, how do you manage TYPO3 sites in past and current TYPO3 versions.

In older version of TYPO3, to manage TYPO3 site, you did manage configuration like

TYPO3 v13 added Site Sets and a site settings editor, and TYPO3 v14 renamed the backend modules and merged site settings into the site setup. The core keys of config.yaml (base, rootPageId, languages, errorHandling, routes, routeEnhancers) are documented the same way for both versions.

• Backend module in v13: Site Management > Sites for the site setup, Site Management > Settings for site settings (since v13.3).
• Backend module in v14: Sites > Setup. The former Settings module is part of Setup, and Web > List is now Content > Records (TYPO3 changelog #107628). More changes are in our TYPO3 v14 release notes.
• Site Sets (v13.1+): sets live in Configuration/Sets/<Name>/ of an extension or site package. Read more in What are Site Sets in TYPO3 v13?

Classic vs modern: which method for which job?

Whether your project starts from one of our TYPO3 templates or from a custom site package, the site configuration is where base URL, languages and Site Sets come together. Sources: Site sets (v13.4), Site settings (v12.4).

Minimal config.yaml example

This file defines one site with English as default language and German under /de/. Save it as config/sites/main/config.yaml (Composer mode) and adjust rootPageId and base. The keys typo3Language, iso-639-1 and direction are not needed, TYPO3 derives them from locale.

rootPageId: 12
base: 'https://example.org/'
websiteTitle: Example
languages:
  - title: English
    enabled: true
    languageId: 0
    base: /
    locale: en_US.UTF-8
    navigationTitle: English
    flag: gb
  - title: Deutsch
    enabled: true
    languageId: 1
    base: /de/
    locale: de_DE.UTF-8
    navigationTitle: Deutsch
    flag: de
    fallbackType: strict

Source: Site handling basics (structure checked against the main and 12.4 docs).

Step 4. You can change the Domain-URL into the “Entry Point” field.

That’s it! The whole site’s URL routing will work awesome ;)

One thing, I would like to say “Heartily Thanks to Dmitry Dulepov” for his dedicated work and support for the RealURL TYPO3 extension for a year. EXT:realurl was one of the great TYPO3 extensions and helped all past TYPO3 sites for URL Routing.

TYPO3 stores each site as a YAML file, config/sites/<identifier>/config.yaml in Composer-based installations or typo3conf/sites/<identifier>/config.yaml in Classic mode, and not in database tables. Add this folder to version control.

Good thing is that TYPO3 is one of the fastly accepting modern technologies, Thank God to ignore TypoScript, PHP, etc. For each TYPO3 site configuration, It’s used the most widely used YAML file structure.

About the location of the YAML file, Well depends!

Here is the basic tutorial of TYPO3 config.yaml which is very self-explanatory and easy to understand ;) This minimal example only uses keys documented for TYPO3 v13.4 and v14.

It’s very easy, Either you can directly create a config.yaml OR you can quickly do it with click-n-go from TYPO3 backend.

To manage multi-domain websites, You just need to add multiple sites for your every domain.

Also, the TYPO3 site configuration has an interesting field called “Base Variants” most important for different TYPO3 Context Environment.

Modern TYPO3 developers always set up different TYPO3 environments eg., Local server, Staging server, Production server. So, of course, every TYPO3 context has different URLs. You can easily configure it through baseVariants.

Let’s try to in-depth insight for each configuration and properties of config.yaml

Take a look at your TYPO3 site config file, You will get another language too. 

Of course, for every change you do not require to manually go to the TYPO3 backend site management module, You can simply make changes at config.yaml too.

Route enhancers in the routeEnhancers section of config.yaml turn extension parameters into readable URLs. Since TYPO3 v14.1, a Site Set can also ship them in route-enhancers.yaml; the site configuration still takes precedence (TYPO3 Explained: Site sets).

TYPO3 Route Enhancer - https://news.typo3.com/article/how-to-route-enhancer-for-news

To make better TYPO3 site management, I would like to share a few tips and tricks ;)

From your favorite Terminal command-line tools, For now, you can list and see insight details of each configured TYPO3 site

You can easily access each configuration of your TYPO3 site to our awesome TypoScript ;) Here are some examples;

We can also easily get TYPO3 sites each configuration at your Fluid Templates using “SiteProcessor” Data Processing.

For TYPO3 site configuration, TYPO3 provides a special function to check as TypoScript condition, Let’s see how with a practical example;

Do you want to call TYPO3 site configuration properties to your Extbase/Fluid TYPO3 Extension? Here are some of the examples to get TYPO3 configuration properties to Extbase PHP.

Environment Variables in site configuration allows setting placeholders for configuration options that get replaced by environment variables specific to the current environment.

Yep, you can easily import your custom extension’s YAML configuration to TYPO3 site config, using “import”.

These extensions were written for earlier TYPO3 versions, so check the TER or Packagist entry for TYPO3 v13 and v14 support before you install one. The TYPO3 community offers only a few TYPO3 extensions, but let me list down some of the useful TYPO3 extensions for the TYPO3 site configuration.

One and only Helmut - A great contributor to the TYPO3 community developed a cool TYPO3 solution to make next-level TYPO3 context environment configuration.

Features

• Settings depending on the environment
• Configuration files in other formats
• Configuration files stored in the config folder
• Enhanced site configuration
• Encrypting values in configuration files

Step 1. Install TYPO3-config-handling Package

Step 2. Composer.json

Step 3. Update Composer

Daniel Abplanalp developed EXT:ig_language_detection - Moder way to language detection. Language detection in PSR-15 middleware stack on uri=/. Based on the Accept-Language Header the corresponding site config is chosen. Additional configuration in YAML site configuration is available like aliases and more.

• The language detection is only called when “https://www.yoursite.com” was entered, but all sites have “https://www.yoursite.com/lang-key/”.
• Extra configuration is done in the site YAML config file (e.g. typo3conf/sites/website/config.yaml)
• The language detection is done with an accept header (HTTP_ACCEPT_LANGUAGE) from the browser.

Most site configuration problems come from a base that does not match the requested URL, a language that is disabled or not translated, or a base variant that is active in the wrong context. Check these points first.

404 after changing the base

• Use the full URL with scheme, for example example.org, instead of / or a bare domain.
• Do not use the same rootPageId in two site configurations. TYPO3 then uses the last defined site.
• After editing config.yaml by hand, run vendor/bin/typo3 cache:flush and compare the result with vendor/bin/typo3 site:show <identifier>.

Language not showing in the frontend

• Check enabled: true. A disabled language stays available to editors in the backend but is hidden in the frontend.
• With fallbackType: strict, records without a translation are not rendered. Use fallbackType: fallback with fallbacks: '0' if the default language should fill the gaps (Language configuration).

Wrong base variant is used

• Conditions such as applicationContext == "Development" depend on the application context of the server, usually set with the environment variable TYPO3_CONTEXT.
• Since TYPO3 v13.0, request-dependent functions such as ip() fail in base variant conditions with exception #1686745105. Use applicationContext or getenv() instead (Base variants).

Do I still need a sys_template record in TYPO3 v13 or v14?

No, it is optional since TYPO3 v13.1. A site can load setup.typoscript and constants.typoscript placed next to its config.yaml, plus the TypoScript of the Site Sets in its dependencies. A sys_template record is applied after that. If you keep one, disable its Clear flags, otherwise the TypoScript from the sets is cleared (TYPO3 changelog #103439).

What is the difference between site settings and TypoScript constants?

Site settings are defined per site in settings.yaml and can be read in PHP with $site->getSettings(), in TypoScript and page TSconfig as constants, and in Fluid via the SiteProcessor. Constants in a sys_template record only exist in TypoScript. Since TYPO3 v13.1, settings can have types and defaults in settings.definitions.yaml.

How do I configure robots.txt and sitemap.xml per site?

Add static routes in the routes section of config.yaml. Use type: staticText for robots.txt and type: uri with t3://page?uid=1&type=1533906435 for the XML sitemap of the system extension EXT:seo. Alternatively, map sitemap.xml to that page type with a PageType route enhancer.

Thanks for reading the long TYPO3 article :)

I hope you learn and explore to improve your knowledge in the cool TYPO3 site configuration. Let’s quickly wrap up as below.

• For your upcoming TYPO3 site, whether built on a TYPO3 Template or custom TYPO3 development, never use the Classical approach (eg., TypoScript configuration) work only with the modern approach of TYPO3 site management.
• Keep practice backend TYPO3 site management module with Multi-domain, Multi-lingual, etc features.
• Based on your project, learn routing feature using config.yaml
• As a TYPO3 integrator/developer, well-understand architecture of config.yaml
• You should consider the TYPO3 context environment a good practice TYPO3 project development.
• Check out tips and tricks, as well as available useful 3rd party TYPO3 extensions which help to improve your TYPO3 site config.
• Try to implement intermediate to advanced level custom configuration into config.yaml

Did you get any issues while configuring TYPO3 site management? I’ll be very happy to answer any questions in the comment box.

And if you’d like to see how TYPO3 and AI are shaping the future together, visit the TYPO3 AI Universe for ideas, tools, and inspiration.

Take your site management to the next level with TYPO3 AI automating configurations and optimizing your workflow!

Have a Happy TYPO3 Site Handling :)