Create a Router

Creating a router allows you to customize how your site handles certain incoming requests. This article shows you how to create a router for your site.

Step 1 | Add the router in the site editor

Whether you're working in the editor, Wix IDE, or your local IDE, in order to add a router to your site you must first set it up in the site editor. If you skip this step, Wix won't create the frontend router pages that are displayed to site visitors, and you won't have another way to add them. Once you create your router in the site editor, you can add the code in your preferred IDE.

The following steps explain how to add a router to your site:

Wix Studio:

  1. Make sure you enable coding on your site.

  2. Click the Pages icon to open the Site Pages panel.

  3. Click the Add New Page icon . Then, click Add under Router.

    Note: You can also add a router from the Page Code section of the code panel. Hover over Main Pages, click the plus icon , and then click Add a Router.

  4. Enter a URL prefix for your router and click Add & Edit Code to add the router to your site. All incoming requests with the specified URL prefix will be sent to your router for handling.

Wix Editor:

  1. In the sidebar, go to Page Code > Main Pages. Click on the icon at the top of the Main Pages section, and choose Add a Router.

  2. Enter a URL prefix for your router and click Add & Edit Code. All incoming requests with the specified URL prefix will be sent to your router for handling.

After you add a router, the following occurs:

If you're working in the editor:

  • Your router's router() and sitemap() functions are added in a routers.js file with sample code for a simple routing scenario. The routers.js file is located in the Backend & Public section of the code panel.
  • A new section called Router Pages is created in the Page Code section of the code panel. Router pages are grouped together under a title based on the prefix you chose earlier. One router page is created to start with. For example, if you named your router "myRouter", a page named myRouter-page is added under the title MyRouter Pages (Router).

If you're working in the Wix IDE:

  • Your router's router() and sitemap() functions are added in a routers.js file with sample code for a simple routing scenario. The routers.js file is located in src/backend.

  • In the site editor, a new section called Router Pages is created in the Page Code section of the code panel. Router pages are grouped together under a title based on the prefix you chose earlier. One router page is created to start with. For example, if you named your router "myRouter", a page named myRouter-page is added under the title MyRouter Pages (Router).

    Add any router pages in the site editor. In the Wix IDE, those pages then appear under src/pages. Note that in the Wix IDE the router pages aren't grouped by router, so if you create more than one router, name each router page clearly to avoid confusion.

If you're working in your local IDE:

  • A modal opens in your site editor containing sample code and instructions on how to add the code to your site. We recommend copying the code to make sure your router and sitemap functions are set up correctly.

  • A new section, Router Pages, is created in Page Code section of the code panel. Router pages are grouped together under a title based on the prefix you chose earlier. One router page is created to start with. This page and any other router pages you create are added to your github repository. You can then pull them to your local repo and write the code in your IDE.

Note: Certain module export formats are not supported in routers.js. For more information, see Module Export Syntax.

Step 2 | Coding the router

Once you add the router to your site, you need to add code for it. The code for the router works the same way no matter which IDE you're working in. All your router logic goes in the routers.js file.

There are four parts to the sample code that's added to the routers.js file:

  1. The import statement: The default code imports some basic router functionality from the Router API, including the ok() and notFound() functions, as well as the WixRouterSitemapEntry object.

    Copy

    Keep this import statement when you customize your code, and use it to add any further functionality from the Router API. You may also need to import additional modules, such as the Wix Data API.

  2. The sample data: The sample code includes an object called peopleData, which is the data the sample router displays on the router page. For your own code, delete or replace this object. You can use the Data API to retrieve data items from a collection, as explained in our router tutorial.

  3. The router() function: Every time you add a router to your site, Wix adds a router() function for it in routers.js. The first router() function added contains sample code like this:

    Copy

    Let's quickly review what the sample code is doing:

    Lines 3-6: The router gets the path from the request parameter, which is a WixRouterRequest object, and searches for it in the peopleData object.

    Lines 8-27: If it finds the requested name, it creates a HeadOptions object that defines what goes in the HTML head of the page we respond to the request with. That object is stored in the seoData variable. The router then passes the data from peopleData and seoData to the ok() function, which renders the requested page to the visitor.

    Line 31: If the person isn't found in peopleData, the router returns a 404 page by using the notFound() function.

    Build off the code above to customize your router() function:

    1. Replace lines 3-6 with your own code to retrieve data from an external source or a collection on your site.

    2. Change the conditional statement to match your own router logic. For example, if you need to display either an index or an item page, build a logical statement that renders one or the other based on the contents of the path parameter.

    3. Change the HeadOptions object to generate your SEO data. You can use any information you want to create the object. For example, the sample code creates title and description properties based on data from peopleData. You can create your own properties from the data you retrieve and populate metaTags with this data as well.

      You also have the option, as in the sample code, to set noIndex to false, meaning search engines should index the page, or add a keywords property to the HeadOptions object with a string containing the page's keywords.

    4. Your router function must return a WixRouterResponse object. This object is responsible for telling the router which page to display on the frontend when a visitor makes a request:

      • Use the ok() function to render a requested page if it exists. Pass three arguments to ok():

        • The name of the router page to render.
        • A data object containing the data to pass to the router page.
        • An object containing SEO data for the router page.

      • Use the notFound() function if the requested page isn't found. You can also use the forbidden(), redirect(), or sendStatus() functions.

  4. The sitemap() function: Along with the router() function, Wix also adds a sitemap() function to routers.js every time you add a router. As with router(), the first sitemap() function added includes sample code that you should replace with your own.

    Let's take a look at the sample code in the sitemap() function:

    Copy

    Lines 3-10: The code takes the keys of the peopleData sample object and uses the JavaScript map() function to create an array of WixRouterSitemapEntry objects, one object for each key. Each entry is given values for the pageName, url, and title properties. Then the array is wrapped in a Promise and returned.

    Replace the sample code with code of your own that generates WixRouterSitemapEntry objects for each page. Then return these objects for SEO to use.

Once you complete these steps, you have a working router. Publish your site and make page requests to test the router.

See also

Did this help?