Taming Multi‑Domain TYPO3 with YAML Site Configuration

Running several domains off one TYPO3 installation used to mean juggling domain records, page IDs, and a tangle of TypoScript conditions. The Site Configuration module changed that: each site is described by a single YAML file, and TYPO3’s routing layer reads those files to decide which page tree answers a request. If you manage more than one domain, this is the piece of TYPO3 worth understanding properly.

What Site Configuration actually replaces

Before Site Configuration (introduced in TYPO3 v9 and refined since), multi‑domain setups relied on legacy domain records attached to root pages, plus TypoScript conditions like [globalString = ENV:HTTP_HOST=…] to switch behavior per domain. That worked, but it scattered the definition of “what is a site” across the database and template code.

Site Configuration centralizes this. Each site gets a directory under config/sites/<identifier>/ containing a config.yaml file. The file declares the entry point (base URL), the root page ID, available languages, and — critically for routing — route enhancers that map clean URLs to page IDs and parameters. TYPO3 compiles and caches this configuration, so request routing stays fast.

A worked example: two domains, one installation

Say you run a corporate site at example.com and a campaign microsite at promo.example.org, both from one TYPO3 instance. Each has its own root page in the page tree (IDs 1 and 42 in this example — substitute your own).

Create config/sites/main/config.yaml:

rootPageId: 1
base: 'https://example.com/'
languages:
  -
    title: English
    enabled: true
    languageId: 0
    base: /
    locale: en_US.UTF-8
    navigationTitle: English
routeEnhancers:
  NewsPlugin:
    type: Extbase
    extension: News
    plugin: Pi1
    routes:
      -
        routePath: '/article/{news-title}'
        _controller: 'News::detail'
        _arguments:
          news-title: news
    aspects:
      news-title:
        type: PersistedAliasMapper
        tableName: tx_news_domain_model_news
        routeFieldName: path_segment

And config/sites/promo/config.yaml:

rootPageId: 42
base: 'https://promo.example.org/'
languages:
  -
    title: English
    enabled: true
    languageId: 0
    base: /
    locale: en_US.UTF-8
    navigationTitle: English

Two things to note. First, the base value is what ties an incoming HTTP host to a page tree — TYPO3 matches the request against these bases and picks the winning site. Second, the route enhancer only exists on the main site, so /article/my‑post resolves there while the promo domain keeps plain page‑path URLs.

You can edit these files directly on the filesystem (they’re just YAML, so they live happily in version control) or through the backend’s Site Management module, which writes the same files. Direct editing requires write access to the config/sites/ directory on the server; the backend module requires an admin user.

Where things go wrong

Three failure modes are worth knowing before you start:

• YAML indentation. YAML is whitespace‑sensitive. A single tab character or a misaligned key will produce a parsing exception, and depending on context the whole site configuration may fail to load. Use spaces, validate after editing, and check the system log (Admin Tools → Log) if the backend module shows nothing.
• Overlapping routes. If two route enhancers can match the same URL path, the result depends on evaluation order and can silently route to the wrong page. Keep route paths distinct, and test ambiguous cases explicitly.
• Stale caches. Site configuration is cached. After editing YAML by hand, flush caches (Admin Tools → Maintenance → Flush, or vendor/bin/typo3 cache:flush from the project root with CLI access) before concluding your change didn’t work.

The trade‑off: files versus database

Moving site definition into files is mostly a win — configuration becomes diffable, deployable, and reviewable in pull requests. The cost is that the YAML and the database must agree: rootPageId points at a real page, route enhancers reference real tables and fields, and deleting a page without updating the config leaves a broken site. On multi‑environment setups, page IDs can differ between development and production databases, which means either keeping IDs stable across environments or templating the YAML during deployment. Neither is hard, but both require a deliberate decision.

Also note this describes TYPO3 v9 through v12 behavior; the core concepts are stable, but verify route enhancer syntax against the documentation for your exact version before relying on it.

Verify before you ship

After writing or editing a site configuration, do three checks: open the Site Management backend module and confirm both sites appear with the correct domains; visit a routed URL (like the news article path above) in a browser and confirm it resolves to the right page; and grep the system log for YAML errors. If all three pass, your multi‑domain setup is on solid ground — and next time someone asks “which page tree serves this domain?” the answer is one file away.