About Routers

Wix gives you the ability to display multiple items from data collections with dynamic pages. When using dynamic pages, Wix creates a router behind the scenes that handles incoming requests to the dynamic page and directs the client to the correct page with the correct data. Wix also handles SEO for you in the background.

If you prefer to handle requests with your own custom logic, you can create your own router instead of using dynamic pages. With your own router, you have full control over how your site handles incoming requests, as well as the SEO for dynamic pages.

You set up a router to receive all incoming requests with a specified prefix, and define the logic of how to handle incoming requests with that prefix. You decide what actions to perform, what response to return, where to route the request, and what data to pass to the page.

You might want to use a router to:

• Display a dynamic page using content from any data source
• Customize your URLs to make them more meaningful and yield better SEO results
• Authenticate visitors and then display content just for them
• Return custom HTTP response codes

Supported IDEs

You can create routers using:

• The editor (Wix Studio and Wix Editor)
• The Wix IDE (Wix Studio)
• Your local IDE (Wix Studio and Wix Editor)

URL prefix

When you create a router, you specify a URL path prefix that follows your site's domain name. The prefix is the part of the URL shown in angle brackets in the following examples:

• Premium site: https://domain.com/<prefix>/category/item
• Free site: https://user.wixsite.com/yoursite/<prefix>/category/item

This URL prefix determines which incoming requests your router handles. If your site receives a request with the specified prefix, it sends that request to your router for handling.

The URL prefix is also used as the name for the router functions and pages.

Routing code

Define router logic in a backend file named routers.js. All routers for your site are defined in this single file. You build each router by defining 2 functions named with the following convention:

• <router prefix>_Router(request)
• <router prefix>_Sitemap(sitemapRequest)

These functions often use other functionality from the Router API.

router()

The router() function is where the site sends page requests with the defined prefix. The router receives a WixRouterRequest object containing information about the incoming request, such as the full URL used to reach the router, and where the request came from. The function then decides what to do with the request and returns the appropriate WixRouterResponse. Typically, the router() function will decide which page to show (if any) and what data to pass to the page. The response is then sent using the forbidden(), notFound(), ok(), redirect(), or sendStatus() functions.

sitemap()

Your sitemap is what search engines use to find your site's pages. Pages on your site that don't belong to a router are automatically added to your sitemap for you. However, since you control what pages are available through your router, you need to create your own sitemap for these router pages. The router sitemap contains all possible URLs that are connected to your router's prefix, so that Google can find each router page.

The sitemap() function handles the SEO and sitemap requests for your router. In the code for your sitemap() function, you need to create and return a WixRouterSitemapEntry object for each router page. This ensures search engines can find the links to your router's pages.

As with SEO for regular pages, you can define the page title, description, and social network images for router pages. The difference is that since router pages don't contain static data, their SEO information must be set dynamically, so they reflect the real content they will hold when they're viewed.

Each WixRouterSitemapEntry includes information about a page, such as its URL, title, and name. You can also add additional information about each page, such as how often its content changes, when the last change was, and its relative priority within your site. Google uses the sitemap entries to discover all the pages in your router.

The sitemap() function is also used to populate the items preview widget when you're previewing or editing your site, allowing you to switch between dynamic item pages.

Router data

Your router() function may send data to the pages it routes to. You can access that data in the frontend page code using the getRouterData() function of the wix-window-frontend module.

Using the SDK with routers

While router handlers themselves must use Velo syntax, you can call SDK functions from in your router functions:

This hybrid approach allows you to leverage both the routing architecture and modern SDK APIs for data operations and business logic.

See also

• Create a router
• About SEO and routing
• Tutorial: Create dynamic pages with a custom router
• About Router Caching
• Router API