Create a Router

To create a router, you can either:

use the createRouter() API to create and initialize a router. It accepts a JSON object as an argument. This method is appropriate for more sophisticated use cases.
use the Router Module Provider to generate a router based on a static JSON file. This method is appropriate for most use cases.

createRouter()

The createRouter() API takes a configuration object, RouterConfig, as an argument. To initialize a router with createRouter(), follow these steps.

1. Set the Root Component of Your Application

Open your app’s lwr.config.json file and specify a rootComponent value in a routes object. For more information on how to set routing properties, see the route reference page.

The routes defined in lwr.config.json are server-side. They differ from the RouteDefinition array that you set up in the next step for the client-side router.

Note

Here’s an example of a routes object inside an lwr.config.json file.

1{
2  "lwc": { "modules": [{ "dir": "$rootDir/src/modules" }] },
3  "routes": [
4    {
5      "id": "app",
6      "path": "/",
7      "rootComponent": "example/app"
8    }
9  ]
10}

2. Configure createRouter()

In your root component, import the createRouter() function from lwr/router.

1import { LightningElement } from 'lwc';
2import { createRouter } from 'lwr/router';

createRouter() takes a RouterConfig object. RouterConfig has to contain an array of RouteDefinition objects.

Here’s an example RouterConfig. It contains an array with two routes, and it customizes the basePath, sets an i18n locale, and enables case sensitive URI processing. namedPageHandler is a route handler module.

1const routerConfig = {
2  routes: [
3    {
4      id: 'home',
5      uri: '/',
6      handler: () => import('example/homePageHandler'),
7        page: {
8            type: 'home',
9        },
10    },
11    {
12        id: 'namedPage',
13        uri: '/:pageName',
14        handler: () => import('example/namedPageHandler'),
15        page: {
16            type: 'namedPage',
17            attributes: {
18                pageName: ':pageName',
19            },
20        },
21    },
22  ],
23  basePath: '/my-site',
24  i18n: {
25    locale: 'es',
26    defaultLocale: 'en-US'
27  },
28  caseSensitive: true
29}

Pass RouterConfig into createRouter(), which returns a router instance for use by lwr/routerContainer.

1import { LightningElement } from 'lwc';
2import { createRouter } from 'lwr/router';
3
4const routerConfig = {
5  routes: [
6    {
7      id: 'home',
8      uri: '/',
9      handler: () => import('example/homePageHandler'),
10        page: {
11            type: 'home',
12        },
13    },
14    {
15        id: 'namedPage',
16        uri: '/:pageName',
17        handler: () => import('example/namedPageHandler'),
18        page: {
19            type: 'namedPage',
20            attributes: {
21                pageName: ':pageName',
22            },
23        },
24    },
25  ],
26  basePath: '/my-site',
27  i18n: {
28    locale: 'es',
29    defaultLocale: 'en-US'
30  },
31  caseSensitive: true,
32}
33
34export default class SimpleRoutingApp extends LightningElement {
35    router = createRouter(routerConfig);
36
37    homeReference = { type: 'home' }; // Home page reference for the page-link
38}

3. Attach the router to lwr/routerContainer

You have to attach the router to a router container. In your root component’s html file, attach the router instance to lwr/routerContainer like this:

1<template>
2  <lwr-router-container router={router}> // router instance attachment point
3    <example-page-link label="Home" page-reference={homeReference}></example-page-link>
4    <lwr-outlet>
5      <div slot="error">This content failed to display.</div>
6    </lwr-outlet>
7  </lwr-router-container>
8</template>

Router Module Provider

The Router Module Provider generates a router based on a static JSON file. Static configurations can be easier to author and to maintain than a JavaScript module.

This module provider (@lwrjs/router/module-provider) is included in all projects by default.

Optional: Register the Router Module Provider

In lwr.config.json, you can configure the directory location of your router JSON files.

1{
2  "moduleProviders": [
3    ["@lwrjs/router/module-provider", { "routesDir": "$rootDir/config/router" }],
4    "@lwrjs/app-service/moduleProvider",
5    "@lwrjs/lwc-module-provider",
6    "@lwrjs/npm-module-provider"
7  ]
8}

If you don’t specify a configuration, it uses this configuration by default:

1{
2  "routesDir": "$rootDir/src/routes"
3}

Optional: Register client-side routes

To automatically register client-side routes with the server, specify them as subRoutes in lwr.config.json and point to their route JSON file.

1{
2    "routes": [
3        {
4            "id": "spa",
5            "path": "/site",
6            "rootComponent": "my/spa",
7            "subRoutes": "$rootDir/src/routes/client.json"
8        }
9    ]
10}

The LWR server takes client-side routes as uri strings from static router configuration files. It registers path strings from them as follows:

`uri`	Resulting `path`
`/`	`/site`
`/about`	`/site/about`
`/:id`	`/site/:id`

1. Configure the Router JSON

The Router Module Provider generates a router module based on the JSON configuration of LwrRouterConfig, which contains an array of route definitions in the form of LwrConfigRouteDefinition objects.

Here’s an example of a static JSON config file for LwrRouterConfig.

1{
2  "routes": [        // array of LwrConfigRouteDefinition objects
3    {
4      "id": "home",
5      "uri": "/",
6      "component": "examples/home",
7      "page": {
8        "type": "home"
9      },
10      "metadata": {
11        "title": "Home"
12      }
13    },
14    {
15      "id": "namedPage",
16      "uri": "/:pageName",
17      "handler": "examples/namedPageHandler",
18      "page": {
19        "type": "namedPage",
20        "attributes": {
21          "pageName": ":pageName"
22        }
23      }
24    }
25  ],
26  "caseSensitive": "true",
27  "i18n": {
28        "defaultLocale": "en-US",
29        "locales": [{ "id": "en-US" }]
30    }
31}

For LwrConfigRouteDefinition, the handler and component properties are string references. Because LwrConfigRouteDefinition is pure JSON, it can’t contain any functions.

2. Import and Use the Generated Router

After you’ve specified the JSON configurations, you can import and use the generated router. Make sure to attach the router to a router container, too.

1import { LightningElement } from "lwc";
2import { createRouter } from "@lwrjs/router/my-config-file";
3
4export default class MyApp extends LightningElement {
5  router = createRouter();
6}

1<template>
2    <lwr-router-container router={router}>
3        <lwr-outlet></lwr-outlet>
4    </lwr-router-container>
5</template>

The generated router module specifier is @lwrjs/router/<name of the JSON config file>. It provides a createRouter() function that’s nearly identical to the static createRouter() function. Unlike the static createRouter(), the generated function doesn’t take a routes array because the routes are configured in the JSON configuration file instead.

If basePath or caseSensitive is specified in both the static JSON configuration file and the generated createRouter() call, the latter takes precedence.

Next Steps

Ready to configure navigaton rules for your new router? Check out Simple Routing Example to get started.

Developer Preview Feature

Feature is available as a developer preview. Feature is not generally available unless or until Salesforce announces its general availability in documentation or in press releases or public statements. All commands, parameters, and other features are subject to change or deprecation at any time, with or without notice. Do not implement functionality developed with these commands or tools.