About Routers
Wix gives you the ability to display multiple items from your data collection with dynamic pages. In your site editor, you see only one dynamic item page, but visitors to your site see multiple pages with the same design, each rendering a different item from your collection. You can set a unique URL for each of these item pages.
Behind the scenes, Wix creates a router that handles incoming requests to the dynamic page and directs the client to the correct URL. Wix also handles SEO for you in the background. However, if you prefer to handle requests with your own custom logic, you can create your own router.
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 what to do when a request with that prefix is received. 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 users and then display content just for them.
- Return custom HTTP response codes.
In the following sections, we review the important components of creating a router for your site.
Supported IDEs
You can create routers using:
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
When you create the first router on your site, Wix automatically adds a file called routers.js to your site's backend folder. In this file, you write all your logic for handling incoming requests.
routers.js contains two functions that are the entry points to your router. They are named with the following convention:
<router prefix>_Router(request)<router prefix>_Sitemap(sitemapRequest)
Note that if you add any more routers to the site, Wix adds the functions for them in the same file. For example, if you add myRouter1 and myRouter2 to the site, you'll see the following functions in your routers.js file:
myRouter1_Router(request)myRouter1_Sitemap(sitemapRequest)myRouter2_Router(request)myRouter2_Sitemap(sitemapRequest)
You then write the logic for each router in its respective set of functions.
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 Google uses 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 are 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.
Router caching
Router caching can greatly optimize the performance of your site. When a site visitor successfully makes a request on your site, such as navigating to a page, the response is sent using the ok() function. By implimenting caching with the ok() function, you can temporarily store the function's return value, the WixRouterResponse, which includes page data. This reduces the need to fetch data repeatedly each time a visitor makes a request on your site, improving load times and overall site performance. The cache is managed using a Time To Live (TTL) property, which defines how long the data should be stored, and tags, which allow for precise cache invalidation when necessary.
When to use router caching
Router caching is highly beneficial for site pages with high traffic or for pages with dynamic content that doesn't change frequently. For instance, let's say your site includes a department store with several categories where the products are listed. When a site visitor first navigates to the dresses category under clothing/womens-clothing/, the page data is first fetched from the backend server and then cached. The next time a visitor requests that same page, the load time is significantly faster because the data is already stored on Wix's infrastructure.
However, router caching can be less effective in situations where a site visitor's request relies on geolocation or specific filters and search queries. The dynamic and personalized nature of the responses to these types of requests make caching less practical. For example, caching the router response for a daily weather update request for a site visitor in London would be irrelevant for a visitor in California. Similarly, caching responses based on user search terms is inefficient, as the traffic for those exact queries is likely to be minimal.
Invalidating your cache
Cache invalidation is important and essential for keeping your site's data accurate and up-to-date. It clears stored cache and allows for the retrieval of updated content. You should invalidate your cache whenever the content on your page is updated or when your page displays time sensitive information. For example, when you update product listings or prices in your online store.
Your router caches are invalidated when:
- The
invalidateCache()function is called. - The TTL period expires.
- You republish your site with code changes.
To implement cache invalidation, use the invalidateCache() function from the wix-cache-backend module. Use the invalidationMethods parameter to specify the tag identifiers of the cached return values you want to invalidate.
Important:
If you do not specify tags in the invalidationMethods parameter, your caches aren't invalidated unless the TTL expires or you republish your site with a code change.
Learn more about cache invalidation.