TYPO3 Routing in v13 & v14: Complete Guide

TYPO3 routing turns page paths and extension parameters into clean, readable URLs. Standard pages use Site Configuration and page slugs, while extension arguments rely on route enhancers and aspects to map dynamic values into meaningful paths.

Before:
/index.php?id=13&tx_news_pi1[news]=42

After:
/news/example-article

From TYPO3 14.1, extensions and site packages can also provide reusable route enhancers through Site Sets. This guide covers setup, YAML examples, multilingual routing, cHash, redirects, and troubleshooting for TYPO3 v13 and v14. RealURL is now relevant only for legacy migrations.

TYPO3 Routing Basics

TYPO3 routing maps incoming URLs to pages or extension actions and turns technical parameters into clear, structured paths. It combines page routing with route enhancers and aspects for more complex extension URLs.

Speaking URLs

Technical URL: /index.php?id=13
Speaking URL: /news/

Extension parameters can also become readable paths:

Before: ?tx_news_pi1[news]=42
After: /news/example-article

Page and Extension Routing

Standard page URLs come from the TYPO3 Site Configuration and page slugs. Route enhancers are needed when extension records, pagination, filters, plugin arguments, or controller actions should appear in the URL.

Core Terminology

A route enhancer defines the URL structure, while an aspect converts an individual value. For example, PersistedAliasMapper can replace a news record UID with its stored slug.

Modern TYPO3 versions include routing in the Core. RealURL and CoolUri are only relevant when migrating older projects and preserving legacy URLs.

TYPO3 Routing in v13 and v14

TYPO3 v13 keeps route enhancers in the site configuration, while TYPO3 14.1 adds reusable routing presets through Site Sets.

TYPO3 v13

Route enhancers remain inside:

config/sites/your-site/config.yaml

Existing enhancers, aspects, and YAML imports can continue working without restructuring.

TYPO3 v14.1

Extensions and site packages can provide reusable enhancers through:

EXT:my_extension/Configuration/Sets/MySet/route-enhancers.yaml

TYPO3 merges these presets according to Site Set dependency order. Values defined directly in the website’s Site Configuration take priority.

Use config.yaml or imported YAML files in TYPO3 v13. Use route-enhancers.yaml in TYPO3 14.1+ when routing should be shared across sites or delivered with an extension.

TYPO3 Routing Prerequisites

Clean URLs depend on a correct Site Configuration, language setup, web-server rewrites, document root, and cleared caches.

Site Configuration

Create the site under Sites → Setup and connect it to the correct root page.

config/sites/your-site/config.yaml

The file defines the base URL, root page, languages, error handling, static routes, and route enhancers.

Base URL and Root Page

base: ‘https:// www. example. com/’

rootPageId: 1

The rootPageId must match the site’s page-tree root. Incorrect values can cause broken links, redirects, or unresolved routes.

Site Languages

Every site needs a default language with languageId: 0.

languages:
 - title: English
   enabled: true
   languageId: 0
   base: /
   locale: en_US.UTF-8
   hreflang: en-US

Additional languages need unique IDs, URL bases, locales, and hreflang values.

Web-Server Rewrites

Apache must have mod_rewrite enabled and allow TYPO3’s .htaccess rules:

AllowOverride Indexes FileInfo

NGINX must forward unmatched requests to TYPO3:

location / {
   try_files $uri $uri/ /index.php$is_args$args;
}

IIS requires the Microsoft URL Rewrite module and a valid web.config.

Document Root and Cache

Composer installations normally  use public/ as the document root. Non-public configuration and dependency files must not be exposed.

Flush TYPO3 caches after changing routing or language configuration:

vendor/bin/typo3 cache:flush

With DDEV:

ddev typo3 cache:flush

Routing Readiness Checklist

• Site Configuration is linked to the correct root page.
• The base URL and protocol are correct.
• A default language is configured.
• Clean URLs reach TYPO3 through the web server.
• The document root points to public/.
• Page slugs exist.
• Caches were cleared after configuration changes

Page-Based Routing in TYPO3

Page-based routing converts the TYPO3 page tree into clean URLs. Once the Site Configuration and page slugs are correct, standard pages do not need a custom route enhancer.

Create the Site

Go to Sites → Setup, create the Site Configuration, and connect it to the correct root page.

TYPO3 stores the settings in:

config/sites/example/config. yaml

Each website root should belong to one Site Configuration to avoid conflicting routes.

Configure the Site and Languages

The site-level base defines the main domain, while each language can use its own path prefix or domain.

base: 'https:// example. com/'
languages:
 - title: English
   enabled: true
   languageId: 0
   base: /
   locale: en_GB.UTF-8
   hreflang: en-GB

Every site needs a default language with languageId: 0. Additional languages can use paths such as /de/ or separate domains.

Generate and Edit Page Slugs

TYPO3 builds page URLs from the slug field in Page Properties. Editors can adjust the slug when the page title does not create the desired path.

Page tree: Home → News → Example Article

Slugs: / /news /example-article

URL: /news/example-article

Slugs should remain readable, lowercase, and unique within the site.

Understand Inherited Paths

Child-page URLs usually include their parent paths. Changing or moving a parent page can therefore affect every URL below it.

Before changing an established slug, review the affected child pages and confirm that redirects will preserve the old URLs.

Prevent Duplicate Routes

Two pages should not resolve to the same path. Use distinct slugs where pages have similar titles, especially across branches that could generate identical URLs.

Test the Final URLs

After saving the Site Configuration and page slugs:

1. FlThis example is suitable for TYPO3 13.4 and 14.3:
   ush TYPO3 caches.
2. Open the generated frontend URL.
3. Confirm that the correct page loads.
4. Check language variants and redirects.
5. Verify the HTTP status using browser tools or curl.

Annotated config.yaml

This example is suitable for TYPO3 13.4 and 14.3:

# config/sites/example/config.yaml
base: 'https://example.com/'   # Main website domain
rootPageId: 1                  # UID of the page-tree root
websiteTitle: 'Example Website'
languages:
 - title: English
   enabled: true
   languageId: 0
   base: /
   locale: en_GB.UTF-8
   hreflang: en-GB
   navigationTitle: English
   flag: gb
errorHandling:
 - errorCode: '404'
   errorHandler: Page
   errorContentSource: 't3://page?uid=99'
routes:
 - route: robots.txt
   type: staticText
   content: |
     User-agent: *
     Allow: /
routeEnhancers: {}

• base defines the website entry point.
• rootPageId connects the site to the correct page-tree root.
• languages controls language availability and URL prefixes.
• errorHandling defines responses such as a custom 404 page.
• routes creates fixed paths such as robots.txt.
• routeEnhancers is only needed when extension arguments must become readable URL segments.

When a Route Enhancer Is Needed

Route enhancers are used when extension arguments or output types need to become part of a readable URL. Standard TYPO3 pages already use page-based routing and require no additional enhancer.

Route Enhancer Structure

A route enhancer extends an existing page route, maps request arguments to placeholders, and connects the resulting path to the correct plugin action.

The following current EXT:news example creates a speaking detail URL:

# config/sites/example/config.yaml

routeEnhancers:
 News:
   type: Extbase
   limitToPages:
     - 13
   extension: News
   plugin: Pi1
   routes:
     - routePath: '/article/{news-title}'
       _controller: 'News::detail'
       _arguments:
         news-title: news
   aspects:
     news-title:
       type: NewsTitle

Before:
/news?tx_news_pi1[news]=42

After:
/news/article/example-article

limitToPages ensures that this configuration applies only to the page containing the News detail plugin. The route path defines the visible URL structure, _arguments connects the placeholder to the News record, and the NewsTitle aspect resolves its optimized path segment. Current EXT:news documentation recommends using either limitToPages or a clear prefix such as /article/ to reduce routing conflicts.

When several Extbase routes could match the same parameters, TYPO3 uses the first matching configuration. Place specific routes before broader ones, then clear all caches and test both generated links and manually entered URLs.

TYPO3 Route Enhancer Types

TYPO3 provides different enhancers for plain parameters, namespaced plugins, Extbase actions, and page output formats. Choosing the correct type keeps routes predictable and prevents unresolved parameters.

Simple Enhancer

Use the Simple Enhancer for non-namespaced parameters such as filters or categories.

routeEnhancers:
 Category:
   type: Simple
   limitToPages: [13]
   routePath: '/category/{category}'
   aspects:
     category:
       type: StaticValueMapper
       map:
         news: 1
         events: 2

Before: ?category=1
After: /category/news

Use a Plugin or Extbase Enhancer instead when parameters belong to a plugin namespace.

Plugin Enhancer

Use the Plugin Enhancer for pi-based plugins with namespaced arguments.

routeEnhancers:
 Login:
   type: Plugin
   limitToPages: [25]
   namespace: tx_felogin_pi1
   routePath: '/login/{action}'
   requirements:
     action: ‘login|forgot|reset’

The namespace must match the actual request parameters. Otherwise, TYPO3 may retain the original query string.

Extbase Plugin Enhancer

Use the Extbase Enhancer when routes must connect to controller actions and records.

routeEnhancers:
 News:
   type: Extbase
   limitToPages: [13]
   extension: News
   plugin: Pi1
   routes:
     - routePath: '/article/{news-title}'
       _controller: 'News::detail'
       _arguments:
         news-title: news
   defaultController: 'News::list'
   aspects:
     news-title:
       type: PersistedAliasMapper
       tableName: tx_news_domain_model_news
       routeFieldName: path_segment

Before: ?tx_news_pi1[news]=42
After: /article/example-news-title

TYPO3 evaluates Extbase routes in order, so place specific routes before broader patterns.

PageType Decorator

Use the PageType Decorator for readable output formats and suffixes.

routeEnhancers:
 PageTypeSuffix:
   type: PageType
   default: ''
   map:
     '.json': 100
     '.xml': 200
     'feed.rss': 9818

This converts ?type=100 into .json. Apply suffixes consistently, especially on established websites where URL changes may require redirects.

Custom Enhancers

Create a custom enhancer only when the full route needs behaviour that TYPO3 Core does not provide. If only one placeholder needs special mapping, a custom aspect is usually simpler and safer.

TYPO3 Routing Aspects and cHash

Aspects map individual route values. They can replace IDs with slugs, translate fixed segments, or limit values to a known range.

An enhancer defines the route pattern, while an aspect maps one placeholder inside it.

routePath: '/news/{news-title}'

Here, PersistedAliasMapper can convert {news-title} from a record UID into its stored slug.

Common Aspect Examples

# Fixed values
aspects:
 month:
   type: StaticValueMapper
   map:
     january: 1
     february: 2

# Localized segment
aspects:
 archive:
   type: LocaleModifier
   default: archive
   localeMap:
     - locale: 'de_.*'
       value: archiv

# Pagination
aspects:
 page:
   type: StaticRangeMapper
   start: '1'
   end: ‘100’

# Database slug
aspects:
 news-title:
   type: PersistedAliasMapper
   tableName: tx_news_domain_model_news
   routeFieldName: path_segment

Use PersistedPatternMapper when a route value must combine several record fields. Create a custom aspect only when none of the built-in mappers can handle the required conversion.

cHash Behaviour

cHash remains when TYPO3 still treats one or more arguments as dynamic. A route enhancer alone does not guarantee its removal.

Aspects and supported static values help TYPO3 recognise predictable arguments. A regex requirement only restricts what can match the route and should not be treated as a universal cHash-removal method.

Keep cHash when dynamic parameters genuinely create different cacheable content.

Route Enhancers in TYPO3 v14 Site Sets

TYPO3 14.1 allows reusable route enhancers to be delivered through Site Sets.

Use site-level routing for one website:

config/sites/my-site/config.yaml

Use a Site Set when routes should be shared across projects or shipped with an extension:

EXT:my_extension/Configuration/Sets/MySet/
├── config.yaml
└── route-enhancers.yaml

routeEnhancers:
 ProductCategory:
   type: Simple
   routePath: ‘/category/{category}’

Site Set routes are merged by dependency order. Later Sets can override earlier values, while configuration defined directly at site level has final priority.

TYPO3 v13 does not support the dedicated route-enhancers.yaml file. Keep enhancers in config.yaml or import separate YAML files

Practical TYPO3 Routing Examples

These examples show how routing converts common parameters into readable paths.

Simple Parameter

routeEnhancers:
 Category:
   type: Simple
   routePath: ‘/category/{category}’

Before: ?category=12
After: /category/12

Extbase Detail Route

routeEnhancers:
 Products:
   type: Extbase
   limitToPages: [20]
   extension: Products
   plugin: List
   routes:
     - routePath: '/{product}'
       _controller: 'Product::show'
       _arguments:
         product: product
   aspects:
     product:
       type: PersistedAliasMapper
       tableName: tx_products_domain_model_product
       routeFieldName: slug

Before: ?tx_products_list[product]=42
After: /example-product

Pagination

routes:
 - routePath: '/page-{page}'
   _controller: 'News::list'
   _arguments:
     page: currentPage
aspects:
 page:
   type: StaticRangeMapper
   start: '1'
   end: ‘100’

Before: ?currentPage=2
After: /page-2

After changing any route enhancer, clear TYPO3 caches and test both generated links and manually entered URLs.

Slugs and Multilingual Routing

Slugs create readable page and record paths, while language configuration controls translated URLs.

Page slugs come from the page tree. Record slugs belong to extensions such as news, products, or events.

languages:
 - title: English
   languageId: 0
   base: /

 - title: German
   languageId: 1
   base: /de/

Use LocaleModifier for translated static segments:

Language-switching 404 errors usually come from missing translations, hidden pages, invalid slugs, or strict fallback settings.

Static Routes, Sitemaps and Redirects

Static routes handle fixed paths such as robots.txt, favicons, and sitemap URLs.

routes:
 - route: robots.txt
   type: staticText
   content: |
     User-agent: *
     Allow: /

Use a PageType decorator for formats such as RSS or JSON:

routeEnhancers:
 PageType:
   type: PageType
   map:
     feed.xml: 9818
     data.json: 100

TYPO3 v13 commonly uses manual sitemap routing. TYPO3 14.1 can provide sitemap routes through the SEO Site Set.

When slugs change, EXT:redirects can create redirects automatically. Keep temporary redirects for temporary moves and use permanent redirects only when the URL change is final. Avoid redirect chains by pointing old URLs directly to the final destination.

TYPO3 Routing SEO Best Practices

Stable, consistent routes help search engines crawl the correct URLs and prevent avoidable duplication.

Stable URLs and Unique Slugs

Avoid changing established paths without a migration plan. Use readable, unique slugs and prevent route patterns that could resolve the same request differently.

Route Scope and Pagination

Apply limitToPages so enhancers run only where needed. Keep pagination, category, tag, and filter routes predictable, and avoid generating unlimited parameter combinations.

Canonicals, Languages and Sitemaps

When typo3/cms-seo is active, TYPO3 can generate canonical and hreflang links. Verify that these point directly to the final routed URLs in every language. Sitemap entries should also use the canonical URL rather than a redirect or parameter-based variation.

Deployment Checklist

• Test canonical and hreflang destinations.
• Check pagination and filter URLs.
• Confirm sitemap URLs return 200.
• Crawl for redirect chains and 404s.
• Monitor Google Search Console after launch.

Common TYPO3 Routing Problems and Fixes

Most routing failures come from cached configuration, incorrect route scope, mismatched arguments, or unresolved slugs.

Debug incoming requests in PageRouter, outgoing Extbase URLs in ExtbasePluginEnhancer, and test responses with:

curl -I https:// example(.)com/ news/ example

A 404 indicates that no valid page or enhanced route resolved. A redirect status means TYPO3 matched a redirect before reaching the final page.

Legacy Migration and Optional Extensions

Modern TYPO3 uses Core routing, so RealURL and CoolUri are not required for current projects. EXT:news documentation also confirms that Core enhancers and aspects replace these older URL-rewriting extensions.

Migrating from RealURL

Preserve the old RealURL tables until the slug migration wizard has finished. Generate and review page slugs, map important legacy paths, create redirects, and crawl the migrated website before removing old routing data.

Extension Compatibility Checked June 2026

Final TYPO3 Routing Checklist

Use this checklist before deploying new or updated routing configuration.

• Site Configuration has been created.
• The base URL and rootPageId are correct.
• Page and record slugs are valid and unique.
• The correct route enhancer type has been selected.
• Enhancers are restricted with limitToPages where appropriate.
• Every route placeholder has the correct argument mapping.
• Suitable aspects are configured for slugs, ranges, and fixed values.
• cHash behaviour has been tested.
• All configured languages and translated routes work correctly.
• Redirects point directly to their final destinations.
• Canonical and hreflang URLs use the final routed paths.
• Sitemap URLs return the expected content and status code.
• TYPO3 caches have been cleared after YAML changes.
• Generated links and manually entered URLs have both been tested.
• Routing YAML has been verified in TYPO3 13.4 and 14.3.

Conclusion

TYPO3 routing becomes much easier once page routes, enhancers, aspects, slugs, and static routes are treated as separate parts of the same system. Start with a correct Site Configuration, add only the routes your extensions need, keep patterns predictable, and test every language and redirect before deployment.

Need support with complex extension routes, multilingual URLs, or a legacy RealURL migration? Explore T3Planet’s TYPO3 solutions or connect with the team for practical implementation guidance.

Have a Happy TYPO3 Routing!