Custom URL routing lets a developer intercept requests to a chosen set of URLs on a site and decide what happens next, such as rendering a particular page with attached data, redirecting elsewhere, or returning a specific HTTP status code. The mechanism for doing this differs by development path.
On Wix sites, custom URL routing is handled by routers. A router is a backend function that owns every URL under a declared prefix on a site's domain. When a visitor requests a path beginning with that prefix, the platform invokes the router function with a request object describing the URL and the caller. The function returns a response object that tells the platform what to do next, such as render a page with attached data, redirect to a different URL, or return an HTTP status code like 404 or 403.
Wix sites also offer dynamic pages, a built-in editor feature that connects a data collection to a page design and generates a router automatically. Writing a router yourself is the alternative when you need routing logic the built-in feature doesn't provide.
A few properties distinguish routers from other backend execution models on the platform:
- URL-prefix scoped: A router claims every URL under its prefix and is invoked for browser navigation to those paths. Requests outside the prefix follow the site's standard page routing. Routers are intended for browser navigation rather than for API traffic, which belongs in an HTTP function.
- Drives page rendering, not API responses: Unlike a web method that returns data to the frontend, or an HTTP function that returns data to an external caller, a router's response tells the platform what to render, where to redirect the visitor, or which HTTP status code to send. The same router function can produce different outcomes for different URLs under its prefix.
- Routes URLs to page designs with attached data: A router can hand any URL under its prefix to a page design built in the editor, attaching different data to each request. The page reads that data at runtime, so one design can serve many URLs without each needing its own page in the editor. This covers dynamic content pages, personalized pages, gated content, and any other case where the URL determines what data the page sees.
- Not cached by default: Unlike regular site pages, router pages aren't cached automatically, because their content depends on the requested URL. A router can opt into caching a response when the rendered result is stable enough to reuse.
- SEO is declared separately: Because router pages render dynamic data rather than static content, the platform can't infer the site's URL inventory from the editor. Each router declares a companion sitemap function that lists every routable URL under its prefix along with the metadata search engines need, and the platform uses that function to populate the site's sitemap and the editor's page preview.
The development path determines how custom URL routing works:
- Sites: Declare routers in the site's backend code. Each router is a function whose name encodes the URL prefix it owns, paired with a sitemap function for SEO. The router runs on the published site. Routers currently require Velo syntax even on sites where the rest of the backend code is written with the SDK. For the file conventions, naming, and how to attach dynamic data to a rendered page, see About Routers in Extend Websites, or the equivalent About Routers in Velo. For deeper reference, see About Router Caching in Extend Websites, and the
wix-router module and getRouterData() in the Velo API Reference. For implementation, see Create a Router and Tutorial: Create Dynamic Pages with a Custom Router in Extend Websites.
- Wix-managed headless projects: Don't define Wix routers. A Wix-managed headless project is a standalone frontend project, Astro-based by default, so URL routing is handled in the project's own framework rather than by a Wix routing layer. The matched routes can still call Wix APIs through the SDK.
- Self-managed headless projects: Run their frontend on infrastructure the developer manages, so URL routing is whatever the chosen framework supports, such as Next.js dynamic routes, Remix routes, or an Express router. There's no Wix layer involved in matching URLs to handlers, although the matched handlers can still call Wix APIs through the SDK or REST.
- Wix-managed apps: Don't define Wix routers. The Wix CLI's backend-extensions surface doesn't include URL routing on the installing site. Apps that need to add pages to a site do so through site-page extensions, which integrate into the site's existing slug-based page routing rather than intercepting URLs of their own.
- Self-managed apps: Run their frontend on infrastructure the developer manages, so URL routing is whatever the chosen framework supports, such as Next.js dynamic routes, Remix routes, or an Express router. There's no Wix layer involved in matching URLs to handlers, although the matched handlers can still call Wix APIs through the SDK or REST.
- Blocks apps: Can't define routers because the
wix-router API isn't supported in Blocks.
- For the related concept of exposing backend code at a public URL for backend-to-backend traffic rather than browser navigation, see Exposing APIs in this section.
- For the related concept of running backend logic in response to a platform event rather than an incoming URL, see Events in this section.