Routers and Route Matching

To set up client-side LWR routing, you have to create a router. In this section, you'll learn the basics of routers and how they use route matching to change what users see in the browser.

A router is a piece of code that manages client-side navigation changes. All navigation events flow through a router for processing.

To create a router, you can either:

• use the Router Module Provider to generate a router based on a static JSON file. This method is appropriate for most use cases.

• use the createRouter() API to create and initialize a router based on a JSON configuration object. This method is appropriate for more sophisticated use cases.

The most important part of a router configuration object or file are its route definitions. A router uses route definitions to evaluate incoming navigation events. If an incoming location matches one of its route definitions, the navigation event is accepted, and the browser updates the displayed content. This process is called route matching.

There are two types of route definition objects. The object type depends on which tool you use to configure the router.

A route definition contains a URI and a page reference that both point to the same page of an app.

A URI is a location specified in string form in a browser's address bar. It's captured by the router via the popstate event. Here's an example of a URI:

In this example, view and dark-mode are query parameters. The view parameter has the compact string literal value.

A page reference is a location specified in JSON form. The navigate() API passes navigation events to the router in the form of a PageReference object.

This PageReference object is equivalent to the above URI.

A router uses the following rules to determine whether an incoming location change is a valid match for a route definition.

To successfully match an incoming URI with a route definition's URI:

• The incoming URI has to have all the query parameter names used in the route definition URI.
• The incoming URI has to have all the string literal values for query parameters that are used in the route definiton URI.
  • Case sensitivity only applies to literal query values. Matching can be case insensitive if caseSensitive isn’t specified in the RouteDefinition.
  • Case sensitivity always applies to the query key, regardless of caseSensitive settings.
• The order of the query parameters in the URL doesn’t matter.

For navigating by PageReference, the following rules apply:

• Every property specified must be defined.
• String literal values in the route definition and the PageReference must be identical.
• Every RegEx pattern must be matched.
• Extra state properties are allowed.
• Extra attribute properties are not allowed (and cause the match to fail).

Say you have a recipe website with a page for an apple pie recipe. Here’s an example RouteDefinition for the apple pie page:

This URI and page reference match the page’s RouteDefinition:

This URI and page reference don’t match the RouteDefinition:

What happens after a router matches an incoming location change to a route definition? Check out Route Handler Modules to learn more.