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.

Short answer: TYPO3 routing builds readable URLs in two layers. Normal pages get their URL from the page slug and the site configuration in config/sites/<site>/config.yaml. Extension parameters need a route enhancer (Simple, Plugin, Extbase or PageType) plus aspects that map IDs to slugs. TYPO3 14.1 and later can also load enhancers from a Site Set.

Key takeaways

• Pages need no enhancer: the slug field and the site configuration create their URLs.
• Use the Extbase enhancer for Extbase plugins such as EXT:news, and restrict it with limitToPages.
• Aspects such as PersistedAliasMapper and StaticRangeMapper turn IDs and numbers into readable, static values and avoid a cHash.
• The PageType decorator maps ?type= output to suffixes like .json or .xml.
• From TYPO3 14.1, route-enhancers.yaml in a Site Set ships routing with an extension; the site configuration always wins.
• Clear caches after every YAML change and test generated and typed URLs.

Tested with / valid for: TYPO3 v13.4 LTS and v14 (14.3 LTS). Updated: November 2026

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

Term	Purpose	Example
Route	Complete URL path	/news/example
Slug	Readable page or record value	example
Placeholder	Variable inside a route	{news-title}
Route enhancer	Defines the route pattern	/news/{news-title}
Aspect	Maps one route value	42 → example
cHash	Validates dynamic cache variations	?cHash=...

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.

What changed in 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. The routing syntax itself (enhancers, aspects, slugs) is the same in both versions.

Version status in November 2026: TYPO3 v14 became the new LTS release in April 2026 and receives bug fixes until December 2027 and security fixes until June 2029. TYPO3 13.4 LTS is still maintained for existing projects. Free support for TYPO3 v12 ended on 30 April 2026, so v12 sites now need ELTS or an upgrade (source: This Month in TYPO3, April 2026). Both 13.4 and 14.3 require PHP 8.2 or higher (get.typo3.org).

Site Sets themselves were introduced in TYPO3 13.1; routing presets inside a Site Set followed in 14.1.

Capability	TYPO3 13.4	TYPO3 14.3
Site-level config.yaml enhancers	Yes	Yes
Site Sets	Yes	Yes
Route enhancers through Site Sets	No	Yes, from 14.1
Dedicated route-enhancers.yaml	No	Yes
Site-level override	Not applicable	Yes

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. The TYPO3 changelog puts it plainly: “Site-level route enhancer configuration always takes precedence over set-defined enhancers” (Feature #107837).

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. Flush 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 do you need a route enhancer?

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.

Scenario	Enhancer needed?	Method
Standard TYPO3 page	No	Page routing
Regular GET parameter	Yes	Simple Enhancer
Namespaced pi-based plugin	Yes	Plugin Enhancer
Extbase plugin	Yes	Extbase Enhancer
RSS, JSON, XML, or suffix	Yes	PageType Decorator
robots.txt	No	Static route

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.

Property	Purpose
type	Selects the enhancer type
limitToPages	Restricts the enhancer to selected page UIDs
extension	Identifies the Extbase extension
plugin	Identifies the registered plugin
routes	Contains the available route definitions
routePath	Defines the readable path pattern
_controller	Connects the route to a controller action
_arguments	Maps placeholders to plugin arguments
defaults	Defines optional default values
requirements	Restricts accepted values
aspects	Maps arguments to readable or static values

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.

Which TYPO3 route enhancer type should you use?

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.

Method	Works in	Best for	Caveat
Page slugs (no enhancer)	v13.4, v14	Normal pages from the page tree	Moving a parent page changes all child URLs
Simple enhancer	v13.4, v14	Plain GET parameters such as ?category=1	Not for namespaced plugin arguments
Plugin enhancer	v13.4, v14	Plugins with one namespace, e.g. tx_myext_pi1[...]	Namespace must match the real request parameters
Extbase enhancer	v13.4, v14	Extbase controller actions and records (news, products)	First matching route wins, so order matters
PageType decorator	v13.4, v14	.json, .xml, RSS suffixes for ?type=	Changing suffixes on a live site needs redirects
route-enhancers.yaml in a Site Set	v14.1+	Routing shipped with an extension or shared across sites	Not available in v13; site config overrides it
Custom enhancer	v13.4, v14	Logic the Core enhancers cannot express	More code to maintain on every upgrade

Source for the enhancer and aspect types: TYPO3 Explained 14.3, Route enhancements and aspects.

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. The Core documentation uses tx_felogin_pi1 as an illustration; copy the namespace from a real request URL of your plugin before you rely on it.

Extbase Plugin Enhancer

Use the Extbase Enhancer when routes must connect to controller actions and records. Most TYPO3 extensions with list and detail views, such as news, events or product catalogues, need this type.

 

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.

Aspect	Purpose	Typical use
StaticValueMapper	Maps fixed values	Categories or months
LocaleModifier	Translates static segments	archive → archiv
StaticRangeMapper	Limits numeric values	Pagination
PersistedAliasMapper	Reads a stored slug	News detail routes
PersistedPatternMapper	Combines record fields	Title plus UID
Custom aspect	Adds custom mapping logic	Project-specific values

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. The official documentation states that for dynamic parameters the cHash “can and should not be removed”, and that it “can be removed by converting dynamic arguments into static arguments”, for example with StaticRangeMapper or StaticValueMapper. A StaticRangeMapper range larger than 1000 is not allowed (TYPO3 Explained).

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	Route
English	/archive/2026
German	/archiv/2026

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

 

In TYPO3 v13, the sitemap route enhancers are configured manually in each site’s config.yaml. From TYPO3 14.1, the SEO extension ships them in the typo3/seo-sitemap site set, so a site that depends on this set gets /sitemap.xml automatically (TYPO3 changelog).

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. Our guide on creating TYPO3 redirects covers the redirect module step by step.

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. For the wider checklist, see our TYPO3 SEO tips.

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.

Why is a TYPO3 route not working? Common problems and fixes

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

Symptom	Likely cause	Fix
Enhancer ignored	Page excluded	Check limitToPages
Old route remains	Cached YAML	Flush TYPO3 caches
cHash remains	Dynamic argument	Add a suitable aspect
Detail page returns 404	Alias unresolved	Check table, slug, and record visibility
Wrong action loads	Route order	Put specific routes first
Plugin parameters remain	Wrong namespace	Match the request namespace
Pagination fails	Incorrect argument mapping	Check _arguments
Language route fails	Missing translation or slug	Review localized records
Duplicate route	Overlapping paths	Add a distinct prefix
Site Set route missing	Site override	Check merge order

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

Extension	Current status
justincase	Supports TYPO3 11–13
content_slug	Supports TYPO3 14 and current v13/v12 releases
my_configurable_routes	Listed for TYPO3 9 only
slug, ig_slug, routes	Verify before retaining

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.

Further reading: TYPO3 routing documentation and the EXT:news routing guide.