Server-Side Routing in LWR on Node.js
You use the
lwr.config.json project configuration file to set server-side routes for your app with LWR. Server-side routes can be specified in
lwr.config.json by providing either:
- a static path for each page
Both static and dynamic server-side routes can also have route handler functions, which let you customize the page response at runtime.
Read on for details. We start with a basic static routing example.
Let’s add a page to our site and do some basic (and fast!) routing.
- Now that you’ve got your
StaticSiteproject, make a copy of the
about.mdfile. Keep the new file in the
contentdirectory and name the file explore.md.
- Edit the
explore.mdfile. You can change the first line from
# About LWRto
# Explore LWR. Save the file.
- Open the
main_layout.njkfile. On a new line, add
<li><a href="/explore">Explore</a>under the
aboutline. Save the file.
- Finally, open the
lwr.config.jsonfile. Copy the entire block of code for
about, including the curly brackets, and paste it below the
explorethroughout, and don’t forget to add the comma after the closing bracket in the
aboutblock. Save the file.
- If you're still in the
StaticSitedirectory from when you first made your site, just type
npm run startin the terminal to see your changes. Your updated
StaticSiteproject runs at http://localhost:3000/, with a new Explore LWR page and a working Explore button.
What just happened is that you:
- created a Markdown page (
explore.md) and gave it new heading text ("Explore LWR")
- updated the site navigation in the Nunjucks layout (
main_layout.njk) file to include a new Explore button
- updated the JSON routing configuration file (
lwr.config.json) to let LWR know how to route to the new page
- you gave an
idfor the page (
- you provided the
pathfor the page (
- you provided a
contentTemplatefor the page (
- you told LWR the
layoutTemplateto use for the page; in this case, you used
main_layout.njk, which is the same as for other pages in this example, though that’s not required
- you gave an
Static server-side routes can also have route handler functions, which let you customize the page response at runtime.
routes object in an
lwr.config.json file includes some of these properties:
id: The unique identifier for the route. Required.
path: The unique URI path from which the route is served. Required.
layoutTemplate: The path to a static template that renders the page layout.
contentTemplate: The path to a static template that renders the page content.
rootComponent: The top-level Lightning web component that LWR bootstraps into the HTML output for the route. Each route must have either a
contentTemplate, but not both. (If you do use a
rootComponent, LWR applies a default
contentTemplateto render it.)
properties: A JSON object that can be passed to the templates as context.
routeHandler: A path to a route handler function configured for the route.
cache: The cache settings for the routing, including:
bootstrap: The bootstrap object contains client options that determine how an application page is loaded.
syntheticShadow: Set to
trueto turn on LWC synthetic shadow, default is
services: An array of LWC modules to run on page load.
Here’s an example of an
lwr.config.json file that includes several routing properties:
You can set up routes that LWR serves if a
500 error is encountered during the bootstrap of a route. Error routes take a
status code value, instead of a
This is an advanced topic.
Set the location of a configuration hook in your
lwr.config.json file at the root of your project:
The following is an example of a configuration hook:
Additionally, dynamic server-side routes can use route handler functions to customize the page response at runtime.
This is an advanced topic.
Route handler functions are part of the LWR context object. They’re a server-side way to alter the current route and customize the page response. You can use route handler functions with both static and dynamic server-side routing.
Route handler functions, which are used in LWR's server-side routing, aren’t the same as route handler modules, which are used in client-side routing.
There are a couple of differences between configuration hooks and route handler functions that are worth noting:
- A configuration hook is called once on server startup, while a route handler is triggered with each incoming page request.
- A configuration hook applies to your entire app, whereas each route handler applies only to its specified path.
You provide the path to a route handler function in the
lwr.config.json project configuration file.
A route handler function has this form:
Things to note:
- Cache size. All the
ViewDefinitionResponse.viewParamsare added to the cache key for a page view response. To control cache size, monitor the number of items added.
- Static route properties. The
ViewDefinitionResponse.viewParamsreplace the static route properties, so if the static route properties are needed, you must merge them into the
viewParamsin the route handler function.
- Markdown. The dynamic
ViewDefinitionResponse.viewParamsare available in Markdown content templates. This is notable because in general context isn't passed into Markdown templates, unless you use a custom route handler.
- View. LWR merges the
bootstrapvalues from the current route.
- Time-to-live. The
CacheResponse.ttlis a number, in seconds, or a time string to use as the
Customized Page Response Example
The following is an example of using a route handler function to customize a page response. The LWR server constructs the page response from this function.
Overridden Page Response Example
The following is an example of using a route handler function to completely override a page response. The LWR server constructs the page response from this function.