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.

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

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.

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

In your root component, import the createRouter() function 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.

Pass RouterConfig into createRouter(), which returns a router instance for use by 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:

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.

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

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

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

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

The Router Module Provider generates a router module based 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.

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

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.

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.

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