# developer Lightning Web Runtime (lwr-node) - Full Documentation

<!-- document id=caa54184c13ab4b67cffe06dba1cc4a768cd8f6c63e9746926bc1f2823057f8d url=/developer/current/en-us/lwr-node/lwr/guides/lwr-i18n.md -->

# @lwrjs/i18n

The [i18n API](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Internationalization) lets you add internationalization support to your Lightning Web Runtime on Node.js (LWR-JS) application. Based on a user's locale, you can use this package to:

- Translate strings into different languages
- Load different content on a page
- Translate user-inputted text

## Set Supported Locales in lwr.config.json

For LWR-JS, you have to format your locales as [UTS Locale Identifiers](https://www.unicode.org/reports/tr35/tr35-59/tr35.html#Identifiers). A locale identifier has the structure `language-region-script`. The `language` value is required while `region` and `script` are optional.

For example, the `en-US` identifier refers to English (`en`) spoken in the United States (`US`). The `en` identifier only refers to English without a specific geographical region.

To set which locales your application supports, create an `i18n` section in `lwr.config.json` and add a subsection called `locales`. To set the default locale for your site's content, create a `defaultLocale` subsection and set it to a single locale.

```
{
    "i18n": {
        // These are all the locales you want to support in your application
        "locales": [{ "id": "en-US" }, { "id": "fr" }, { "id": "nl-NL", "fallback": "fr" }],
        // This is the default locale you want to be used when visiting
        // a non-locale prefixed path e.g. `/hello`
        "defaultLocale": "en-US"
    }
}
```

## Handle Locales with URI Patterns

To implement the locale rules that you created in [Set Supported Locales in lwr.config.json](#set-supported-locales-in-lwrconfigjson), you have to set up a URI pattern for handling locales. With LWR-JS, you can choose from path prefix routing and custom routing.

### Routing with Path Prefixes

Path prefix routing adds locale information to the user's URL. To use path prefix routing in your site, add `"uriPattern": "path-prefix"` to the `i18n` section of `lwr.config.json`.

For example, let's say the site `MyExampleSite` uses the following `i18n` configuration.

```
{
    "i18n": {
        // Supported locales: en-US, fr, nl-NL
        "locales": [{ "id": "en-US" }, { "id": "fr" }, { "id": "nl-NL", "fallback": "fr" }],
        "defaultLocale": "en-US",
        // Use path prefix routing
        "uriPattern": "path-prefix"
    },
    "routes": [
        {
            "id": "blog",
            "path": "/blog",
            "rootComponent": "demo/blog"
        }
    ]
}
```

This site's URL is `https://myexamplesite.com`. It has the route `/blog`, which supports these URLs.

- `https://myexamplesite.com/blog`
- `https://myexamplesite.com/fr/blog`
- `https://myexamplesite.com/nl-nl/blog`

Although the `MyExampleSite` website registers each route with the default locale prefix, users that try to access those URLs (like `https://myexamplesite.com/en-us/blog`) get redirected to that URL without the prefix (`https://myexamplesite.com/blog`).

### Custom Locale Routing

If you don't set `uriPattern` in `lwr.config.json`, you have to use the `:locale` token in your `routes` configuration to define how URLs represent localized pages.

Here's an example of a config file for a site with a `/blog` route that uses custom URI routing.

```
{
    "i18n": {
        // Supported locales: en-US, fr, nl-NL
        "locales": [{ "id": "en-US" }, { "id": "fr" }, { "id": "nl-NL", "fallback": "fr" }],
        "defaultLocale": "en-US"
        // "path-prefix" isn't set
    },
    "routes": [
        {
            "id": "blog",
            "path": "/blog",
            "rootComponent": "demo/blog"
        },
        // `blog-localized` sets up URL path for a dynamic locale value
        {
            "id": "blog-localized",
            "path": ":locale/blog",
            "rootComponent": "demo/blog"
        }
    ]
}
```

## Access Locales with API Calls

If you want your API calls to have access to locale information, the following objects have a `locale` property that you can reference.

### page

The page information object (`page`) includes a locale property that you can use in your [template](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-templates.md).

```
<script>
    const userLang = '{{page.locale}}';
    // Redirect if we support the desired locale
    const supportedLocales = ['fr', 'nl-NL'];
    if (supportedLocales.includes(userLang) && !window.location.pathname.startsWith(`/${userLang}`)) {
        window.location.href = `/${userLang}${window.location.pathname}`;
    }
</script>
```

### SsrRequestContext

The `SsrRequestContext` object also contains the `locale` property.

When a component is server-side rendered (SSRed), LWR-JS calls the [`getServerData()`](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-enable-ssr-site.md#load-data-during-ssr) hook. This function returns public properties to the component.

```
export async function getServerData(context: SsrRequestContext): Promise<SsrDataResponse> {
    // This is called to fetch data when the component is SSRed
    const topic = context.params.topic;
    const locale = context.locale;
    const response = await fetch(
        `https://www.googleapis.com/books/v1/volumes?q=subject:${topic}&langRestrict=${locale}`,
    );
    const data = await response.json();
    return { props: { data, ...context.params } };
}
```

### lwr/environment

Only in LWR-JS, the `lwr/environment` module contains the current locale in the `locale` value. `locale` doesn't get populated within the Salesforce platform, but you can import it like this:

```
import { locale } from 'lwr/environment';
```

<!-- https://github.com/salesforce-experience-platform-emu/lwr-recipes/blob/d9d09529e2346a07cb18877a73db9f0d4f9900e9/packages/internationalization/README.md -->

<!-- document id=73d2545dd9cb44a520a5e6b89ce1b81f0a2fd2e93b1d672f4691b6b33fdcf84a url=/developer/current/en-us/lwr-node/lwr/guides/lwr-security.md -->

# @lwrjs/security

[HTTP security headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers#security) guard your site against malicious code injections and cross-site scripting (XSS) attacks. You can implement security headers for your LWR site on a route-by-route basis using the `@lwrjs/security` package.

`@lwrjs/security` exposes a [default route handler](#default-route-handler) and a [security wrapper](#security-wrappers), both of which apply a set of default security headers. To customize these headers, modify the corresponding header configuration objects.

## Usage

To add this package to your project, run `npm install @lwrjs/security` on the command line. Implement this package for a route via the default handler or a security wrapper.

## Default Route Handler

The `@lwrjs/security` route handler matches the [RouteHandlerFunction](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-routing-server.md#route-handler-functions) interface.

```
type RouteHandler = (ViewRequest, HandlerContext) => Promise<ViewResponse>;
```

It's exposed as the default export.

```
export { default } from '@lwrjs/security';
```

To use the default handler for a route, set `@lwrjs/security` as the route handler in `lwr.config.json`.

```
{
    "routes": [
        {
            "id": "home",
            "path": "/",
            "rootComponent": "examples/example",
            "routeHandler": "@lwrjs/security",
        },
    ]
}
```

To modify a security header in the default route handler, set the corresponding header configuration object in the `routeHandler` section. You can disable a header by setting its configuration object to `false`. For more information about default headers and header configuration, skip ahead to [Headers](#headers).

```
"routeHandler": ["@lwrjs/security", {
    "contentSecurityPolicy": "default-src 'self'&semi;base-uri 'self'&semi; script-src 'self'",
    "referrerPolicy": false,
    "xXSSProtection": false
    }]
```

## Security Wrappers

The `@lwrjs/security` route handler wrapper `secure()` applies security headers to an existing route handler. The wrapper is exposed as a named export. It takes a route handler as an argument and returns a promise.

```
type RouteHandlerWrapper = (RouteHandlerFunction) => Promise<RouteHandlerReturnType>;
```

`RouteHandlerReturnType` can be a `ViewResponse` or `ViewDefinitionResponse`. Each type of promise applies headers as follows:

- **ViewDefinitionResponse** - applies the default security headers with inline resource hashing.
- **ViewResponse** (HTML content) - applies the default security headers without resource hashing.
- **ViewResponse** (non-HTML content) - doesn't apply headers.

For example, this `routeHandler.ts` file passes the `routeHandler` into `secure()`. Since the `headers` section is empty, only the default headers are used.

```
import type { ViewDefinitionResponse } from '@lwrjs/types';
import { secure } from '@lwrjs/security';

function routeHandler(): ViewDefinitionResponse {
    return {
        // programmatically define the view configuration
        view: {
            rootComponent: 'example/home'
        },
        // set response headers
        headers: {},
    };
}

export default secure(routeHandler);
```

To modify a header for the default handler, configure the corresponding header configuration object in the route handler file. You can disable a header by setting its configuration object to `false`.

```
headers: {
    "contentSecurityPolicy": "default-src 'self'&semi;base-uri 'self'&semi; script-src 'self'",
    "referrerPolicy": false,
    "xXSSProtection": false
},
```

## Headers

The default route handler and security wrapper automatically enable the following security headers.

### Content-Security-Policy

The `Content-Security-Policy` header directs your site to load content from only approved sources. For a list of acceptable formats for source values, see [CSP Source Values](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/Sources#sources).

These are the default directives for the `Content-Security-Policy` header.

| Directive                   | Description                                                                                                                                                                                                         | Default Source Value            |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| `default-src`               | Set the default source value for all directives that don't have a value.                                                                                                                                            | `'self'`                        |
| `base-uri`                  | Set approved sources that load content in the page's `<base>` element.                                                                                                                                              | `'self'`                        |
| `font-src`                  | Set approved sources that provide fonts.                                                                                                                                                                            | `'self' https: data:;`          |
| `form-action`               | Set approved sources that a form can send information to.                                                                                                                                                           | `'self'`                        |
| `frame-ancestors`           | Set approved sources that can embed your page (the current frame) into a container like `<frame>` on their site.                                                                                                    | `'self'`                        |
| `img-src`                   | Set approved sources of images and icons.                                                                                                                                                                           | `'self' data:;`                 |
| `object-src`                | Set approved sources of `<object>` and `<embed>` elements.                                                                                                                                                          | `'none'`                        |
| `script-src`                | Set approved sources of JavaScript code for elements like `<script>`. You can set the value of this directive to a hash, like `'sha256-hash_value'`.                                                                | `'self'`                        |
| `script-src-attr`           | Set approved sources of only JavaScript inline event handlers.                                                                                                                                                      | `'none'`                        |
| `style-src`                 | Set approved sources of stylesheets.                                                                                                                                                                                | `'self' https: 'unsafe-inline'` |
| `upgrade-insecure-requests` | When this directive is declared in a `Content-Security-Policy` header, it upgrades HTTP requests (insecure) to HTTPS requests (secure). If an HTTP request is not available as an HTTPS request, the request fails. |                                 |

#### Customize the `Content-Security-Policy` Header

There are two ways to modify the `Content-Security-Policy` header.

```
contentSecurityPolicy?: ContentSecurityPolicy | string | boolean;
```

You can set `contentSecurityPolicy` to a [`ContentSecurityPolicy`](https://developer.salesforce.com/docs/platform/lwr/references/packages-reference/contentsecuritypolicy.html) configuration object that contains your custom directives and options for the header. This object overwrites the default values, so you set the directives from scratch.

Alternatively, you can conveniently set `contentSecurityPolicy` to a string of directive-value pairs. When your input is a string, `useDefault` is automatically set to `false` and `resourceHashing` is automatically set to `true`. This overwrites the default values, so you set the directives from scratch.

```
// The string:
"contentSecurityPolicy": "default-src 'self';base-uri 'self'; script-src 'self'"

// is parsed into this ContentSecurityPolicy object:
"contentSecurityPolicy":
    {
        "useDefault": false,
        "resourceHashing": true,
        "directives": "default-src 'self';base-uri 'self'; script-src 'self'"
    }
```

### Cross-Origin-Embedder-Policy

The `Cross-Origin-Embedder-Policy` header controls how a page loads cross-origin resources.

The default policy is `require-corp`. To configure this header, set the `crossOriginEmbedderPolicy` object to one of the following values in string format.

- `unsafe-none`
- `require-corp`
- `credentialless`

For information about these directives, see [MDN Web Docs: Cross-Origin-Embedder-Policy Directives](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Embedder-Policy#directives).

### Cross-Origin-Opener-Policy

The `Cross-Origin-Opener-Policy` header separates a top-level browser instance of a page (like a window) from different page contexts, like pop-ups and other browser tabs.

The default policy is `same-origin`. To configure this header, set the `crossOriginOpenerPolicy` object to one of the following values in string format.

- `same-origin`
- `same-origin-allow-popups`
- `unsafe-none`

For information about these directives, see [MDN Web Docs: Cross-Origin-Opener-Policy Directives](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Opener-Policy#directives)

```
"crossOriginOpenerPolicy": "unsafe-none"
```

### Cross-Origin-Resource-Policy

The `Cross-Origin-Resource-Policy` header controls whether external websites can access and load content from your site.

The default policy is `same-origin`. To configure this header, set the `crossOriginResourcePolicy` object to one of the following values in string format.

- `same-origin`
- `same-origin-allow-popups`
- `unsafe-none`

For information about these directives, see [MDN Web Docs: Cross-Origin-Resource-Policy Directives](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Resource-Policy)

```
"crossOriginResourcePolicy": "unsafe-none"
```

### Origin-Agent-Cluster

The `Origin-Agent-Cluster` header controls whether or not the browser creates same-origin groups of pages. For more information about same-origin versus cross-origin pages, see [Understanding "same-site" and "same-origin"](https://web.dev/articles/same-site-same-origin#origin).

The default value for the `originAgentCluster` object is the boolean `?1`.

```
"originAgentCluster": "?1"
```

For more information about this header and accepted values, see [MDN Web Docs: Origin-Agent-Cluster](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Origin-Agent-Cluster).

### Strict-Transport-Security

The `Strict-Transport-Security` header forces the browser to access a site with HTTPS. Attempts to access the site with HTTP are automatically converted to HTTPS requests. If an HTTP request is not available as an HTTPS request, the request fails.

These are the default directives for this header.

| Directive           | Directive Description                                                        | Default Value |
| ------------------- | ---------------------------------------------------------------------------- | ------------- |
| `max-age`           | Duration (in seconds) that the browser should only load the site with HTTPS. | `15552000`    |
| `includeSubDomains` | Applies header settings to all subdomains.                                   |               |

#### Customize the Strict-Transport-Security Header

There are two ways to modify the `Strict-Transport-Security` header.

```
strictTransportSecurity?: StrictTransportSecurity | string | boolean;
```

You can set `strictTransportSecurity` to a [`StrictTransportSecurity`](https://developer.salesforce.com/docs/platform/lwr/references/packages-reference/stricttransportsecurity.html) configuration object that contains your custom directives and options for the header. This object overwrites the default values, so you set the directives from scratch.

Alternatively, you can conveniently set `strictTransportSecurity` to a string of directive-value pairs. When your input is a string, it overwrites the default values and only uses your input.

```
// The string:
"strictTransportSecurity": "max-age=15552000&semi; preload"

// is parsed into this StrictTransportSecurity object:
"strictTransportSecurity":
    {
        "maxAge": 15552000,
        "preload": true
    }
```

### Referrer-Policy

The `Referrer-Policy` header controls what information is shared with different types of browser requests.

The default policy is `no-referrer`. To configure this header, set the `referrerPolicy` object to one of the following values in string format.

- `no-referrer`
- `no-referrer-when-downgrade`
- `origin`
- `origin-when-cross-origin`
- `same-origin`
- `strict-origin`
- `strict-origin-when-cross-origin`
- `unsafe-url`

For information about these directives, see [MDN Web Docs: Referrer-Policy Directives](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy#directives)

```
"referrerPolicy": "same-origin"
```

### X-Content-Type-Options

The `X-Content-Type-Options` header controls browser requests based on the request destination type and the MIME type.

The default policy is [`no-sniff`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Content-Type-Options#directives). You can either disable this header or keep the `no-sniff` configuration.

### X-DNS-Prefetch-Control

The `X-DNS-Prefetch-Control` header controls [DNS prefetching](https://developer.mozilla.org/en-US/docs/Web/Performance/dns-prefetch).

The default policy is `off`, which disables prefetching. To configure this header, set the `xDNSPrefetchControl` object to one of the following values in string format.

- `off`
- `on`

For information about these directives, see [MDN Web Docs: X-DNS-Prefetch-Control Directives](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-DNS-Prefetch-Control#directives).

### X-Download-Options

The `X-Download-Options` header controls whether content is executed in the browser or downloaded onto a local machine.

The default policy is `"noopen"`, which prevents content from executing in the browser. You can either disable this header or keep the `noopen` configuration.

### X-Frame-Options

The `X-Frame-Options` header determines whether or not the browser can load the page in a frame.

The default value is `sameorigin`. To configure this header, set the `xFrameOptions` object to one of the following values in string format.

- `sameorigin`
- `deny`

For information about these directives, see [MDN Web Docs: X-Frame-Options Directives](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options#directives).

### X-Permitted-Cross-Domain-Policies

The `X-Permitted-Cross-Domain-Policies` header controls how resources are shared with cross-domain sites.

The default value is `none`. To configure this header, set the `xPermittedCrossDomainPolicies` object to one of the following values in string format.

- `none`
- `masteronly`
- `bycontenttype`
- `byftpfilename`
- `all`

### X-XSS-Protection

The `X-XSS-Protection` header controls XSS filtering.

The default value is `0`. To configure this header, set the `xXssProtection` object to one of the following boolean values.

- `0`
- `1`

For information about these directives, see [MDN Web Docs: X-XSS-Protection](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-XSS-Protection).

**See Also**

- [Reference: @lwrjs/security](https://developer.salesforce.com/docs/platform/lwr/references/packages-reference/lwrjs-security.html)

<!-- document id=5279b099889edf7532068d8d8aeb0b7ce315a9df80774ce496b19faeec820f95 url=/developer/current/en-us/lwr-node/lwr/references/packages-reference/lwrjs-security.md -->

# @lwrjs/security

You can customize security headers from the `@lwrjs/security` package using the following configuration objects.

- [ContentSecurityPolicy](https://developer.salesforce.com/docs/platform/lwr/references/packages-reference/lwrjs-security/contentsecuritypolicy.md)
- [StrictTransportSecurity](https://developer.salesforce.com/docs/platform/lwr/references/packages-reference/lwrjs-security/stricttransportsecurity.md)

**See Also**

- [Guide: @lwrjs/security](https://developer.salesforce.com/docs/platform/lwr/guides/lwr-security.md)

<!-- document id=bfc1f63926a1a9a587300dbed2c8e8d5b910a4195c27bab6a3591a82e21d68ea url=/developer/current/en-us/lwr-node/lwr/guides/lwr-portable-best-practices.md -->

# Best Practices for SSRed Components

The following sections describe how to maintain portable components for server-side rendering (SSR).

## Block Access to General Browser APIs

Rendering components on the server means you don’t have access to general browser APIs like `window`, `document`, and `querySelector`. If you’re performing these operations during any component lifecycle events that execute during SSR, you need to revise your code so that it becomes portable.

To prevent non-portable code from running during SSR, use the `import.meta.env.SSR` boolean. For example, this `connectedCallback()` doesn't run `window.addEventListener()` if `App` gets SSRed.

```
export default class App extends LightningElement {
    connectedCallback() {
        // guard usage of the window object so it does not throw during SSR
        if (!import.meta.env.SSR) {
            window.addEventListener('error', (evt) => {
                console.error(`⚠️ Uncaught error: ${evt.message}`);
            });
        }
    }
}
```

## Use globalThis for Feature Detection

[Feature detection](https://developer.mozilla.org/en-US/docs/Learn/Tools_and_testing/Cross_browser_testing/Feature_detection) ensures that code only runs in supported browsers. [Optional chaining](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining) causes failed expressions to return `undefined` instead of an error. This works best when the return value of the browser-only function isn't needed by the component.

To enable feature detection via optional chaining, use the `globalThis` property.

```
connectedCallback() {
// "globalThis" exists in all JavaScript environments
    globalThis.addEventListener?.('keydown', (e) => {...});
}
```

You can't use the [`window`](https://developer.mozilla.org/en-US/docs/Web/API/Window) object because it's `undefined` on the server.

```
connectedCallback() {
    // the global "window" object is undefined on the server
    window.addEventListener('keydown', (e) => {...});
}
```

## Adjust Slotting Behavior for Built-In Events

Slotted content refers to anything contained in a `<slot>` element that you pass into a slot. This content renders as expected during SSR. However, native browser built-in events like `slotchange` can’t fire during SSR because they’re rendered outside of a browser context. As a result, you might observe changes to `slotchange` behavior in your components.

For example, a `slotchange` event determines the number of elements to display in this carousel component. The carousel is outlined in blue, and a pagination component is outlined in pink. The pagination component acts as a control for the number of images being displayed, and it shows a count of three in this example.

![A basic carousel component with three cards.](https://developer.salesforce.com/docs/media/basic-carousel.png)

The pagination component logic runs during the `slotchange` event. Since the `slotchange` event doesn’t happen during an SSR flow, the first initial render only shows a count of 1.

When the component is rendered in the browser, the `slotchange` event fires and hydration updates the count to three.

When these browser-specific events occur, the webpage can sometimes display a small “flash” effect or layout shift. You can reduce the visibility of these effects by adding placeholders or loading messages to your code. This approach is useful when logic takes a long time to run on the client, like a REST or GraphQL data fetch.

## Dynamically Import Non-Portable Modules

To ensure that non-portable modules don't get processed on the server, import them dynamically in your components.

For example, this component imports a portable and a non-portable module.

<!-- prettier-ignore -->
```javascript
import { portableApi } from 'my/library';
import { nonPortableApi } from 'some/library';
export default class Cmp extends LightningElement {
    connectedCallback() {
        portableApi();
        nonPortableApi();
    }
}
```

To import these modules dynamically, the component can use an async/await function, like this. Remember to [guard non-portable code](#block-access-to-general-browser-apis) using the `import.meta.env.SSR` boolean.

<!-- prettier-ignore -->
```javascript
import { portableApi } from 'my/library';
export default class Cmp extends LightningElement {
    async connectedCallback() {
        if (import.meta.env.SSR) {
            portableApi(); // executed during SSR
        } else {
            const { nonPortableApi } = await import('some/library');
            nonPortableApi(); // NOT reachable during SSR
        }
    }
}
```

## Remove Host Element Mutations

Mutating the host element in `connectedCallback()` isn't supported in SSR and CSR.

SSR hydration validates that the virtual DOM exactly matches the `HTMLElement`. For validation to succeed, each virtual DOM attribute has to have an equivalent `HTMLElement` counterpart. If a mutation occurs in a component's `connectedCallback()`, changes that may appear in `HTMLElement` don't appear in the virtual DOM.

For example, this `connectedCallback()` uses the `classList` anti-pattern to try to add class names to the host element. However, directly mutating the `HTMLElement` means the `container` class never appears in the virtual DOM.

```
connectedCallback() {
    this.classList.add('container');
}
```

To correctly add the `container` class to the host, use a semantic element in your `<template>` instead.

```
<template>
    <form class='container'></form>
</template>
```

You can pass a class from a parent component to a child component by wrapping the child in a `<div>` with a dynamic value for the `class` property. Then, implement the corresponding getter in the parent component's JavaScript.

```
<template>
    <div class={classForChild}>
      <x-child></x-child>
   </div>
</template>
```

The parent component's JavaScript uses the `fromOutside` property to set `<c-parent from-outside="parent-class">`. The getter ensures that the child component renders the `my-child-needs-parent-class` value on the `class` attribute.

```
import { api, LightningElement } from 'lwc';

export default class Cmp extends LightningElement {
    @api fromOutside;
    get classForChild() {
        return `my-child-needs-${this.fromOutside}`;
    }
}
```

## Use Supported Lightning Base Components

You can speed up app development by using the LWC versions of base components, which are out-of-the-box building blocks for user interfaces like Lightning Web Runtime (LWR) sites.

Only the following base components are supported for SSR. For more information about the Lightning base components, see the [Component Library](https://developer.salesforce.com/docs/component-library).

|                                |                               |                                          |                                          |
| ------------------------------ | ----------------------------- | ---------------------------------------- | ---------------------------------------- |
| lightning-accordion            | lightning-dynamic-icon        | lightning-layout-item                    | lightning-spinner                        |
| lightning-accordion-section    | lightning-file-upload         | lightning-lookup-address                 | lightning-tab                            |
| lightning-alert                | lightning-formatted-address   | lightning-menu-divider                   | lightning-tabset                         |
| lightning-avatar               | lightning-formatted-date-time | lightning-menu-item                      | lightning-textarea                       |
| lightning-badge                | lightning-formatted-email     | lightning-menu-subheader                 | lightning-tile                           |
| lightning-breadcrumb           | lightning-formatted-location  | lightning-modal                          | lightning-toast                          |
| lightning-breadcrumbs          | lightning-formatted-name      | lightning-modal-body                     | lightning-toast-container                |
| lightning-button               | lightning-formatted-number    | lightning-modal-footer                   | lightning-tree                           |
| lightning-button-group         | lightning-formatted-phone     | lightning-modal-header                   | lightning-tree-item                      |
| lightning-button-icon          | lightning-formatted-rich-text | lightning-pill                           | lightning-vertical-navigation            |
| lightning-button-icon-stateful | lightning-formatted-text      | lightning-pill-container                 | lightning-vertical-navigation-item       |
| lightning-button-menu          | lightning-formatted-time      | lightning-progress-bar                   | lightning-vertical-navigation-item-badge |
| lightning-button-stateful      | lightning-formatted-url       | lightning-progress-indicator             | lightning-vertical-navigation-item-icon  |
| lightning-card                 | lightning-helptext            | lightning-progress-ring                  | lightning-vertical-navigation-overflow   |
| lightning-checkbox-group       | lightning-icon                | lightning-progress-step                  | lightning-vertical-navigation-section    |
| lightning-click-to-dial        | lightning-input               | lightning-prompt                         |                                          |
| lightning-combobox             | lightning-input-address       | lightning-radio-group                    |                                          |
| lightning-confirm              | lightning-input-location      | lightning-rich-text-toolbar-button       |                                          |
| lightning-datatable            | lightning-input-rich-text     | lightning-rich-text-toolbar-button-group |                                          |
| lightning-dual-listbox         | lightning-layout              | lightning-select                         |                                          |
|                                |                               |                                          |                                          |

SSR can impact your existing style rules for base components on your site. To learn how to adapt your styles for SSR, see [Update Lightning Base Components Styling](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-lbc-styling.md).

## Next Steps

Now that your components can opt-into SSR, we recommend testing them with the SSR playground and test runner to catch and correct unexpected behavior. To learn more, follow the instructions in [Test Your Components](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-ssr-components-test.md).

<!-- document id=4e75dd61daa8c22f10dbcb9ca09c14f6681775b2870559a3e8b470aac7625749 url=/developer/current/en-us/lwr-node/lwr/references/csr-reference.md -->

# Client-Side Routing

Configure client-side routing for your web app with these resources.

- [LWR Navigation Data Types](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/csr-reference/nav-data-types.md)
- [LWR Navigation Methods](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/csr-reference/nav-methods.md)
- [RouteHandler Interface](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/csr-reference/routehandler-interface.md)
- [NavigationMixin](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/csr-reference/navigationmixin.md)
- [LWR Navigation Wires](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/csr-reference/lwr-navigation-wires.md)
- [Lightning Web Components for LWR Navigation](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/csr-reference/lwc-for-lwr-navigation.md)

<!-- document id=053cbae6087452e9a4ee2246221dbf297b068fdfa6a4d13153b4fc5306ffdcce url=/developer/current/en-us/lwr-node/lwr/guides/lwr-routing-client-overview.md -->

# Client-Side Routing in LWR on Node.js

You can use client-side routing (CSR) in LWR on Node.js for sophisticated control over your web application's routing and navigation behavior.

- To learn the essential concepts, architecture, and steps for using CSR, start on this page: [Routers and Route Matching](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-routers-route-matching.md).
- Ready to [Create a Router](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-create-router.md)? This page outlines how to use the createRouter() API and the Router Module Provider.
- The [Simple LWR Client-Side Routing](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-routing-example-simple.md) example shows the process of creating a single-page LWR application (SPA) with client-side routing.
- For details about the APIs, interfaces, wires, and Lightning web components that support LWR's client-side routing, visit the [LWR Client-Side Routing Reference](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/csr-reference.html).

<!-- document id=f9ed9596edeed6f2687e6eca90e976c6c5b13959354bd1ce8975e85f94cd8a50 url=/developer/current/en-us/lwr-node/lwr/references/cli-reference.md -->

# Command Line Interface

Use these commands to build or preview your static site.

- [`lwr build`](https://developer.salesforce.com/docs/platform/lwr/references/cli-reference/lwr-build.md)
- [`lwr dev`](https://developer.salesforce.com/docs/platform/lwr/references/cli-reference/lwr-dev.md)
- [`lwr start|preview`](https://developer.salesforce.com/docs/platform/lwr/references/cli-reference/lwr-start-lwr-preview.md)

These commands are available via the [npm Registry](https://npmjs.com/package/lwr).

<!-- document id=facfad6f1703657804980cc2dd99a688b91c0034bdc6ebfb4e5ab11062340c56 url=/developer/current/en-us/lwr-node/lwr/guides/lwr-compile-data.md -->

# Compile-Time Data in LWR on Node.js

After you understand the basics about [templating and layouts](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-templates.md) with LWR, you can use the various data provided by LWR for more complex scenarios. The place to start is with **context objects**.

## Understand Context Objects

LWR uses a [route’s](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-routing.md) templates and context to render the response for a page request.

The context object that LWR passes into HTML and Nunjucks templates contains data from several locations. This data is merged into a single object in this order:

- [Global Data](#global-data)

- [Front Matter](#front-matter)

- [Page Information](#page-information)

- [Markdown Metadata](#markdown-metadata)

- [Static Route Properties](#static-route-properties)

- [Route Handlers](#route-handlers)

- [LWR Properties](#lwr)

**note:** When it comes to context objects, Markdown templates are a little different from HTML and Nunjucks templates. Context isn't passed into Markdown templates unless you use a route handler, which is a way of customizing the page response. ["Route Handler Functions"](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-routing-server.md#route-handler-functions) in [Server-Side Routing in LWR](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-routing-server.md) discusses this advanced topic.

## Global Data

From the file system, you can pass any static global context data into your app's content and layout templates. This data is available to all HTML or Nunjucks templates within your application. It is not available to component HTML templates, however.

```cli
src/
  └── data/     // global template context data
      ├── site/
      │   └── navbar.json
      └── global.json
```

```json
// $rootDir/src/data/global.json
{
  "siteTitle": "LWR Docs"
}
```

```json
// $rootDir/src/data/site/navbar.json
[
  {
    "id": "guide",
    "name": "Guide",
    "url": "/guide/introduction"
  },
  {
    "id": "recipes",
    "name": "Recipes",
    "url": "/recipes"
  }
]
```

This global data is then added to the context.

```json
// context object
{
  "global": {
    "siteTitle": "LWR Docs"
  },
  "site": {
    "navbar": [
      {
        "id": "guide",
        "name": "Guide",
        "url": "/guide/introduction"
      },
      {
        "id": "recipes",
        "name": "Recipes",
        "url": "/recipes"
      }
    ]
  }
}
```

## Front Matter

LWR reads any front matter out of a template and adds it to the [context object](#understand-context-objects). Front matter values are local to the template.

LWR uses the [gray-matter](https://www.npmjs.com/package/gray-matter) parser to process front matter. This allows you to use YAML, JSON, TOML, or CoffeeScript to format front matter, or you can even [set custom delimiters](https://www.npmjs.com/package/gray-matter#optionsdelimiters). The following is a YAML front matter example:

```html
---
custom: 9000
someText: Good to meet you
immutable: false
layoutTemplate: $layoutsDir/main_layout.njk
---

{# $rootDir/src/content/home.njk #}
<p>{{someText}}</p>
<p>{{custom}}</p>
It is now {{ now | date('dddd, MMMM Do YYYY, h:mm:ss a') }}
```

```html
---
custom: 9000
someText: Good to meet you
immutable: false
layoutTemplate: $layoutsDir/main_layout.njk
---

{# $rootDir/src/content/home.njk #}
<p>{{someText}}</p>
<p>{{custom}}</p>
It is now {{ now | date('dddd, MMMM Do YYYY, h:mm:ss a') }}
```

LWR has predefined the following front matter variables:

| Variable         | Supported Template Languages | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ---------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `layoutTemplate` | HTML, Nunjucks, Markdown     | Sets the layout template inside a content template. This value is overridden by the `layoutTemplate` set on the route.                                                                                                                                                                                                                                                                                                                                                                                           |
| `immutable`      | Nunjucks                     | Set this variable to `false` if the template contents are mutable; the default is `true`. Nunjucks templating allows mutable constructs to be embedded in a template's content, for example, [random](https://mozilla.github.io/nunjucks/templating.html#random) and [cycler](https://mozilla.github.io/nunjucks/templating.html#cycler-item1-item2-itemn). Due to this capability, templates that use these features must mark the template as mutable so LWR can modify the cacheability of the page response. |

## Page Information

LWR can pass information about the page from the current route and request.

- `id`: `route.id`
- `title`: set to the first defined value of the following:
  - `properties.title` from the route or `viewParams.title` from the route handler
  - filename from `route.contentTemplate`
  - "LWR App"
- `url`: the request URL, relative to the origin

Example 1: When the current browser location is `http://localhost:3000/` and the route is:

```json
// route in lwr.config.json
{
  "id": "home_page",
  "path": "/",
  "contentTemplate": "$contentDir/home.html",
  "layoutTemplate": "$layoutsDir/main_layout.njk"
}
```

Then, the page information is:

```json
// context object
{
  "page": {
    "id": "home_page",
    "title": "home",
    "url": "/"
  }
}
```

Example 2: When the current browser location is `http://localhost:3000/recipes?sort=desc` and the route is:

```json
// route in lwr.config.json
{
  "id": "recipes",
  "path": "/recipes",
  "contentTemplate": "$contentDir/recipes.md",
  "properties": {
    "title": "Recipes Repository"
  }
}
```

Then, the page information is:

```json
// context object
{
  "page": {
    "id": "recipes",
    "title": "Recipes Repository",
    "url": "/recipes?sort=desc"
  }
}
```

The object is accessible via the page context variable in the HTML/Nunjucks templates:

```html
{# $layoutsDir/layout.njk shows the page title and a logo on the home page #}
<!DOCTYPE html>
<html>
  <head>
    <title>{{page.title}}</title>
  </head>
  <body>
    {% if page.id === 'home_page' %}
    <img src="$assetsDir/images/logo.svg" alt="logo" />
    {% endif %}{{ body | safe }}{{ lwr_resources | safe }}
  </body>
</html>
```

## Markdown Metadata

Markdown content templates produce context on their headings, which can be accessed from an HTML or Nunjucks layout template. Information on each heading starting with two or more `#` is included. For example, this Markdown:

```markdown
## Topic 1

### Sub-Topic

#### Grandchild
```

Produces this context object:

```json
// context object
{
  "headings": [
    {
      "text": "Topic 1",
      "slug": "topic-1"
    },
    {
      "text": "Sub-Topic",
      "slug": "sub-topic"
    },
    {
      "text": "Grandchild",
      "slug": "grandchild"
    }
  ]
}
```

The object is accessible via the `headings` context property in HTML/Nunjucks layout templates:

```json
{# $layoutsDir/partials/nav.njk shows a link for each heading #}
<ul>
    {% for mdHeading in headings %}
        <li><a href="#{{mdHeading.slug}}">{{mdHeading.text}}</a></li>
    {% endfor %}
</ul>
```

## Static Route Properties

You can pass static context into HTML/Nunjucks templates from a route via its `properties`:

```json
// route with properties in lwr.config.json
{
  "id": "about",
  "path": "/about",
  "contentTemplate": "$contentDir/about.html",
  "properties": {
    "someText": "Lorem ipsum dolor sit amet"
  }
}
```

```html
<!-- $contentDir/about.html shows the route property -->
<h2>About</h2>
<p>{{someText}}</p>
```

## Route Handlers

Context objects can optionally contain route handlers. Route handlers are functions that allow you to customize the page response for a route. ["Route Handler Functions"](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-routing-server.md#route-handler-functions) in [Server-Side Routing in LWR](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-routing-server.md) discusses this advanced topic.

## LWR

LWR automatically passes two context object properties:

- `body`: Available in layout templates, a string containing the rendered page content that is output from the route's `contentTemplate` or `rootComponent`.
- `lwr_resources`: A string containing all the scripts required to run your application, such as the Lightning Web Component library and LWR client resources. If this string is excluded from the page response, embedded Lightning web components don't render.
  - **Note**: The `lwr_resources` property is optional. If you have purely static HTML content (no Lightning web components, module resolution, or other LWR features), you don't require LWR resources in your layout. In the static site you created as your first project, the `main_layout.njk` file doesn't include `lwr_resources`.

Here are examples of HTML and Nunjucks layout templates that use both LWR properties:

**HTML:**

```html
<!-- $layoutsDir/main.html -->
<!DOCTYPE html>
<html>
  <head></head>
  <body>
    <!-- triple braces prevents HTML escaping -->
    {{{body}}} {{{lwr_resources}}}
  </body>
</html>
```

**Nunjucks:**

```html
{# $layoutsDir/main.njk #}
<!DOCTYPE html>
<html>
  <head></head>
  <body>
    {# the "safe" filter prevents HTML escaping #} {{ body | safe }}{{lwr_resources | safe }}
  </body>
</html>
```

<!-- document id=79da98a4215c1dfd17d44f8d3ae3fa33f77d7d48563a5ce4015bbc6408f6daad url=/developer/current/en-us/lwr-node/lwr/guides/lwr-configure-component-ssr.md -->

# Configure Components for Server-Side Rendering (SSR)

To successfully render a component on the server side, it has to meet all of the following criteria:

1. The functions that execute during SSR must be **portable**.
2. The functions that execute during SSR must be **synchronous**.
3. The component uses **light DOM** (recommended) or **native shadow DOM**.

Follow these steps (in order) to make components SSRable.

## 1. Make Components Portable

A component is **portable** if it can run without browser APIs. Your components can’t have any dependencies on browser APIs because the server isn’t a browser.

During SSR, the Lightning Web Components (LWC) framework executes only these functions for each of your components and all of their imported dependencies:

- `constructor`
- `connectedCallback()`
- getters
- setters
- any other functions called by these functions

Components with non-portable code will break your site. If a component uses browser APIs, you have to modify it to ensure it doesn't assume that those APIs are always available.

For example, you should remove the following non-portable code and objects from components that you want to SSR.

- `window`
- `document`
- selector functions (such as `querySelector` and `querySelectorAll`)
- JavaScript eventing

### Detect Non-Portable Code with the ESLint Plugin

The LWC [ESLint Plugin](https://github.com/salesforce/eslint-plugin-lwc/tree/master) helps you determine if your components follow best practices for API or method usage. The plugin's [SSR preset](https://github.com/salesforce/eslint-config-lwc?tab=readme-ov-file#salesforceeslint-config-lwcssr-configuration), `@salesforce/eslint-config-lwc/ssr`, lets you identify non-portable components.

You can configure the plugin with rules from [this list](https://github.com/salesforce/eslint-plugin-lwc/blob/master/README.md#lwc). For example, here are a few rules you should enable to identify non-portable components.

- Disallow access to global browser APIs during SSR (`lwc/no-restricted-browser-globals-during-ssr`)
- Disallow access to unsupported properties on `this` during SSR (`lwc/no-unsupported-ssr-properties`)
- Disallow usage of `process.env.NODE_ENV` in SSR (`lwc/no-node-env-in-ssr`)

Additionally, the plugin can help you identify non-portable utilities and libraries. If a library isn't portable, your page won't load correctly during SSR.

### Avoid Certain Salesforce Scoped Modules

The following Salesforce scoped modules are deprecated during SSR:

- `@salesforce/user/Id`
- `@salesforce/user/isGuest`
- `@salesforce/userPermission/*`
- `@salesforce/customPermission/*`

For LWR Node apps, we recommend using the [`getServerData` hook](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-enable-ssr-site.md#load-data-during-ssr) to fetch information from these modules instead.

If a component has to use one of these scoped modules on the server side, render a placeholder to avoid negatively impacting [web vitals](https://web.dev/articles/vitals).

If a component must use one of these scoped modules on the client side, [dynamically import](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-portable-best-practices.md#dynamically-import-non-portable-modules) the module after hydration. We don't recommend this approach.

### Use Portable Styling

To style components and set image URLs, use code that's executed on both the server and the client. Styling only on the client side can cause UI shifting and hydration warnings.

LWC logs a hydration warning if an SSRed component's HTML doesn't match the output of its first rendering cycle on the client. Hydration warnings cause unexpected UI shifting while the LWC framework recovers from the mismatch.

To avoid hydration warnings, make sure that component template updates are triggered only by asynchronous actions, like user interaction, data updates, and [eventing](https://developer.salesforce.com/docs/platform/lwc/guide/events.html).

```
import { LightningElement, api } from 'lwc';
import basePath from '@salesforce/community/basePath';

export default class Logo extends LightningElement {
    static renderMode = 'light';
    @api highlight = false;
    @api borderWidth = '1';

    renderedCallback() {
        // this code only runs on the client
        const image = this.querySelector('img.logo');
        image?.setAttribute('src', getLogoUrl(basePath));
        if (this.highlight) image?.classList.add('highlight');
        image?.style.setProperty('border-width', `${this.borderWidth}px`);
    }
}
```

```
<!-- before -->
<template>
    <img src="" class="logo" />
</template>
```

```
import { LightningElement, api } from 'lwc';
import basePath from '@salesforce/community/basePath';

export default class Logo extends LightningElement {
    static renderMode = 'light';
    @api highlight = false;
    @api borderWidth = '1';

    // this code works on both the server and client
    // this component is now static and no longer requires hydration
    get url() {
        return getLogoUrl(basePath);
    }
    get className() {
        return this.highlight ? 'logo highlight' : 'logo';
    }
    get borderStyle() {
        return `border-width:${this.borderWidth}px`;
    }
}
```

```
<template>
    <img src="{url}" class="{className}" style="{borderStyle}" />
</template>
```

## 2. Refactor Asynchronous Code

Since the SSR process for Lightning web components (LWCs) runs in one synchronous pass, you should only have synchronous code in server-rendered pages and components.

Server-side asynchronous code executes but doesn't complete during SSR. The resulting page won't break, but it can render unexpected content that's difficult to debug.

Asynchronous code includes:

- [`Promise` objects](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)
- [`async/await` keywords](https://www.w3schools.com/js/js_async.asp)
- [dynamic imports](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import)

However, server-rendered pages and components can include asynchronous code that doesn't execute on the server. For example, you can include asynchronous code in `renderedCallBack()` or event handlers, but you can't add it to `connectedCallback()` or getters. To test if asynchronous code is unsafe, use the [ESLint plugin](#detect-non-portable-code-with-the-eslint-plugin).

## 3. Enable Light DOM or Native Shadow DOM

By default, server-rendered components are rendered in native shadow DOM. However, we recommend using light DOM instead.

### Light DOM

[Light DOM](https://developer.salesforce.com/docs/platform/lwc/guide/create-light-dom.html) eases third-party integrations (like Google Analytics) and global styling. Enabling light DOM ensures that LWC renders regular HTML markup instead of creating a native web component. The markup is also referred to as light DOM since it isn’t contained within a shadow root.

To enable light DOM on your Lightning web component, use the `renderMode` static property.

```
import { LightningElement } from 'lwc';
export default class Heading extends LightningElement {
  static renderMode = 'light';
  @api text;
}
```

In your template, use the `lwc:render-mode` directive.

```
<template lwc:render-mode="light">
  <h2 class="global-style">{text}</h2>
</template>
```

### Shadow DOM

Shadow DOM encapsulates a component's internals and styling. Server-rendered components can use native shadow DOM instead of light DOM.

Synthetic shadow DOM is **not** supported due to [limitations on browser API usage](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-portable-best-practices.md#protect-your-code-from-accessing-general-browser-apis).

## Next Steps

After you've configured a component for SSR, make sure it follows the [Best Practices for Portable Components](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-portable-best-practices.md).

**See Also**

- [Test Your Components](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-ssr-components-test.md)
- [Lightning Web Components: Light DOM](https://developer.salesforce.com/docs/component-library/documentation/en/lwc/lwc.create_light_dom)

<!-- document id=89617606f24d0ea4906462919094f4ceec67c2e196d90e2a6698973f3ffc4118 url=/developer/current/en-us/lwr-node/lwr/guides/lwr-templates.md -->

# Content and Layout Templates in LWR on Node.js

When LWR renders the response for a page request, it uses content and layout templates. You can individually configure the content and layout templates for each [route](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-routing.md) in an application with LWR.

If your site doesn't have a layout template already, you should create one in your project's `src/layouts` directory. To see a sample layout template in the context of a working LWR site, we recommend that you complete the StaticSite project described in [Quick Start: LWR on Node.js](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-get-started.md).

LWR supports the following languages for templating:

- [HTML](https://en.wikipedia.org/wiki/HTML)
- [Markdown](https://www.markdownguide.org/)
- [Nunjucks](https://mozilla.github.io/nunjucks/)

## Templates in Your StaticSite Project

Let's review the files you created in [your first static site project](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-get-started.md).

In `lwr.config.json`, there are content and layout template files specified with the `Home` route `id`. LWR uses the [route's](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-routing.md) templates along with the [context](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-compile-data.md) to render the response.

```json
// route with templates in lwr.config.json
{
  "id": "Home",
  "path": "/",
  "contentTemplate": "$contentDir/home.md",
  "layoutTemplate": "$layoutsDir/main_layout.njk"
}
```

Let's first examine the **content templates** in `/src/content`. In this example, they're written in Markdown. Each of these files (for example, `about.md`) contains a heading and the body content for a page on your site. Content templates are fairly self-explanatory, so we don't spend much time discussing them.

Next, in the `/src/layouts` directory of your project, there's a **layout template**: `main_layout.njk`. Layout templates can get fairly complex, but let's start with the simple one that LWR generated for your project.

When you examine the following code sample, you find that the `main_layout.njk` file is mostly doing things you might encounter elsewhere:

- telling LWR the location of the CSS style sheet for the site
- describing the logo to draw at the top of each page
- setting up the labels and destinations for the top navigation buttons

But when you get all the way down to `<main>`, there’s something that’s probably new: `{{ body | safe }}`.

Here `body` is an LWR [**context object**](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-compile-data.md#lwr) property that’s available in layout templates. It's essentially a string containing the rendered page content from the route's `contentTemplate` or `rootComponent`. Applying the `safe` filter to `body` prevents HTML escaping.

And that’s it. Keep reading for more on the resources you can use in your LWR templates.

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
    <title></title>
    <link rel="stylesheet" href="$assetsDir/css/main.css" />
  </head>

  <body>
    <div class="wrapper">
      <header>
        <svg class="logo" viewBox="0 0 64 64">
          <path fill="#00a1e0" d="M23 6h22l-8 18h11L20 58l6-26H16l7-26z"></path>
          <path
            fill="#032e61"
            d="M20 60a2 2 0 0 1-1.95-2.45L23.5 34H16a2 2 0 0 1-1.93-2.52l7-26A2 2 0 0 1 23 4h22a2 2 0 0 1 1.83 2.81L40.08 22H48a2 2 0 0 1 1.54 3.27l-28 34A2 2 0 0 1 20 60zm-1.4-30H26a2 2 0 0 1 1.95 2.45l-4.1 17.72L43.76 26H37a2 2 0 0 1-1.83-2.81L41.92 8h-17.4z"
          ></path>
          <path
            fill="#fff"
            d="M26 26a2 2 0 0 1-1.93-2.53l3-11a2 2 0 1 1 3.86 1.05l-3 11A2 2 0 0 1 26 26z"
          ></path>
        </svg>
      </header>
      <nav>
        <ul>
          <li><a href="/">Home</a></li>
          <li><a href="/about">About</a></li>
          <li><a href="/explore">Explore</a></li>
          <li>
            <a href="//developer.salesforce.com/docs/platform/lwr/overview"> Learn LWR </a>
          </li>
        </ul>
      </nav>
      <main>{{ body | safe }}</main>
    </div>
  </body>
</html>
```

## Template Resources

You can use the following resources in your LWR templates when creating dynamic content.

- [**Asset references**](#template-and-asset-references)
- [**Context objects**](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-compile-data.md)
- Embedded [**Lightning web components**](https://lwc.dev/)

**warning:** If you want to include Lightning web components in your content or layout templates, the `lwr_resources` context object is required. See [LWR Compile-Time Data](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-compile-data.md) for more about `lwr_resources`.

The following snippets in LWR’s various templating languages provide examples of using each of these resource types. In each example, the code adds an asset reference to a logo file, then embeds the `c/info` Lightning web component. The HTML and Nunjucks example also uses the `someText` context object property.

```html
<h1>Some Topic</h1>

<img src="$assetsDir/images/logo.svg" alt="logo" />
<c-info message="{{someText}}"></c-info>
```

Unlike the HTML and Nunjucks example above, the following Markdown example doesn't include the `someText` [context object](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-compile-data.md) property. Context objects aren't available in Markdown templates unless you use a custom route handler. Route handlers are an advanced topic, so for now know that a route handler is a function that is configured for a route.

```html
# Some Topic

![logo]($assetsDir/images/logo.svg "logo")
<c-info message="static string"></c-info>
```

## Template and Asset References

You can configure the directory locations of templates, global context data, and static assets in your `lwr.config.json` file:

- `contentDir`: The content templates directory. The default is `"$rootDir/src/content"`.
- `layoutsDir`: The layout templates directory. The default is `"$rootDir/src/layouts"`.
- `globalDataDir`: The directory of [global data](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-compile-data.md#global-data) for templating. The default is `"$rootDir/src/data"`.
- `assets`: You can configure one or more files or directories to serve static assets. For each file or directory, include these properties:
  - `alias`: A name for this path to use in content or layout templates.
  - `dir` or `file`: The file system path containing the asset.
  - `urlPath`: The URI path that serves the asset.

Here's an example:

```
{
    "contentDir": "$rootDir/templates",
    "layoutsDir": "$rootDir/layouts",
    "globalDataDir": "$rootDir/src/context",
    "assets": [
        {
            "alias": "imageDir",
            "dir": "$rootDir/src/images",
            "urlPath": "/images"
        }
        {
            "file": "$rootDir/logo.png",
            "urlPath": "/logo"
        }
    ]
}
```

After you set up an asset reference, you can use the static assets in LWC content or layout templates using either the `alias` or the `urlPath` value:

By `alias`:

```html
<!-- /src/layouts/main.html -->
<html>
  <head>
    <link rel="icon" href="$imageDir/logo.svg" />
    <title>My Website</title>
  </head>
  <body>
    <!-- ... -->
  </body>
</html>
```

By `urlPath`:

```html
<!-- /src/modules/my/component/component.html -->
<template>
  <img src="/logo" alt="logo" />
  <img src="/images/home.png" alt="home" />
</template>
```

## Next Steps

Curious about routing in LWR? [Find out more now](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-routing.md).

<!-- document id=e28c0e78f086a5fc1f064271e1d19202acc40e4608249cd1f2a725717f179a6b url=/developer/current/en-us/lwr-node/lwr/references/packages-reference/lwrjs-security/contentsecuritypolicy.md -->

# ContentSecurityPolicy object

Use `ContentSecurityPolicy` to configure the [`Content-Security-Policy`](https://developer.salesforce.com/docs/platform/guides/lwr-security.md#content-security-policy) header.

## Syntax

```
interface ContentSecurityPolicy {
    useDefaults: boolean;
    reportOnly: boolean;
    resourceHashing: boolean;
    directives: { [key: string]: string[] };
}
```

## Options

| Option            | Description                                                                                                                    | Default Value               |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------- |
| `useDefaults`     | When `true`, it merges the default header directives with any custom directives you pass in via the `directives` object.       | `false`                     |
| `reportOnly`      | Set this option to one or more policy directives. For example: `default-src https:; report-to /csp-violation-report-endpoint/` | `'content-security-policy'` |
| `resourceHashing` | When `true`, inline scripts are hashed for the header.                                                                         | `true`                      |
| `directives`      | In this section, you can configure directives for the `Content-Security-Policy` header.                                        |

## Directives

You can customize these directives for a `Content-Security-Policy` header. Set values for them in the `directives` section of a `ContentSecurityPolicy` object.

- [`default-src`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/default-src)
- [`base-uri`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/base-uri)
- [`child-src`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/child-src)
- [`connect-src`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/connect-src)
- [`font-src`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/font-src)
- [`form-action`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/form-action)
- [`frame-ancestors`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors)
- [`frame-src`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-src)
- [`img-src`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/img-src)
- [`manifest-src`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/manifest-src)
- [`media-src`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/media-src)
- [`object-src`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/object-src)
- [`prefetch-src`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/prefetch-src)
- [`sandbox`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/sandbox)
- [`script-src`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src)
- [`script-src-attr`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src-attr)
- [`script-src-elem`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src-elem)
- [`style-src`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/style-src)
- [`style-src-attr`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/style-src-attr)
- [`style-src-elem`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/style-src-elem)
- [`upgrade-insecure-requests`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/upgrade-insecure-requests)
- [`worker-src`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/worker-src)

## Example

For example, this `ContentSecurityPolicy` object tells the `Content-Security-Policy` header to use the `media-src 'self'` directive in addition to to the default directives.

```
"contentSecurityPolicy":
    {
        "useDefault": true,
        "resourceHashing": false,
        "directives": "media-src 'self';"
    }
```

This `ContentSecurityPolicy` has `useDefaults: false`, which removes all the default directives and values. It only defines a value for the `media-src` directive, so all other directives accept content from any source.

```
"contentSecurityPolicy":
    {
        "useDefault": false,
        "resourceHashing": false,
        "directives": "media-src 'self';"
    }
```

**See Also**

- [Guide: @lwrjs/security](https://developer.salesforce.com/docs/platform/guides/lwr-security.md)

<!-- document id=8c77a43d9f8015e4edf1bf3e95953e45672a5155d1310cb3dede644144e40e01 url=/developer/current/en-us/lwr-node/lwr/guides/lwr-create-router.md -->

# Create a Router

To create a [router](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-routers-route-matching.md), you can either:

- use the [`createRouter()` API](#createrouter) 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](#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`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/routerconfig.html), 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](https://developer.salesforce.com/docs/platform/lwr/references/ss-routing-reference/route.html).

**note:** The routes defined in `lwr.config.json` are server-side. They differ from the [`RouteDefinition`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/routedefinition.html) array that you set up in the next step for the client-side router.

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

```
{
  "lwc": { "modules": [{ "dir": "$rootDir/src/modules" }] },
  "routes": [
    {
      "id": "app",
      "path": "/",
      "rootComponent": "example/app"
    }
  ]
}
```

### 2. Configure createRouter()

In your root component, import the [`createRouter()`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/createrouter.html) function from `lwr/router`.

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

`createRouter()` takes a [`RouterConfig`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/routerconfig.md) object. `RouterConfig` has to contain an array of [`RouteDefinition`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/routedefinition.html) 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](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-route-handler-modules.html).

```
const routerConfig = {
  routes: [
    {
      id: 'home',
      uri: '/',
      handler: () => import('example/homePageHandler'),
        page: {
            type: 'home',
        },
    },
    {
        id: 'namedPage',
        uri: '/:pageName',
        handler: () => import('example/namedPageHandler'),
        page: {
            type: 'namedPage',
            attributes: {
                pageName: ':pageName',
            },
        },
    },
  ],
  basePath: '/my-site',
  i18n: {
    locale: 'es',
    defaultLocale: 'en-US'
  },
  caseSensitive: true
}
```

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

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

const routerConfig = {
  routes: [
    {
      id: 'home',
      uri: '/',
      handler: () => import('example/homePageHandler'),
        page: {
            type: 'home',
        },
    },
    {
        id: 'namedPage',
        uri: '/:pageName',
        handler: () => import('example/namedPageHandler'),
        page: {
            type: 'namedPage',
            attributes: {
                pageName: ':pageName',
            },
        },
    },
  ],
  basePath: '/my-site',
  i18n: {
    locale: 'es',
    defaultLocale: 'en-US'
  },
  caseSensitive: true,
}

export default class SimpleRoutingApp extends LightningElement {
    router = createRouter(routerConfig);

    homeReference = { type: 'home' }; // Home page reference for the page-link
}
```

### 3. Attach the router to `lwr/routerContainer`

You have to attach the router to a [router container](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-router-containers.md). In your root component’s html file, attach the router instance to `lwr/routerContainer` like this:

```
<template>
  <lwr-router-container router={router}> // router instance attachment point
    <example-page-link label="Home" page-reference={homeReference}></example-page-link>
    <lwr-outlet>
      <div slot="error">This content failed to display.</div>
    </lwr-outlet>
  </lwr-router-container>
</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.

```
{
  "moduleProviders": [
    ["@lwrjs/router/module-provider", { "routesDir": "$rootDir/config/router" }],
    "@lwrjs/app-service/moduleProvider",
    "@lwrjs/lwc-module-provider",
    "@lwrjs/npm-module-provider"
  ]
}
```

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

```
{
  "routesDir": "$rootDir/src/routes"
}
```

### 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.

```
{
    "routes": [
        {
            "id": "spa",
            "path": "/site",
            "rootComponent": "my/spa",
            "subRoutes": "$rootDir/src/routes/client.json"
        }
    ]
}
```

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`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/lwrrouterconfig.html), which contains an array of route definitions in the form of [`LwrConfigRouteDefinition`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/lwrconfigroutedefinition.html) objects.

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

```
{
  "routes": [        // array of LwrConfigRouteDefinition objects
    {
      "id": "home",
      "uri": "/",
      "component": "examples/home",
      "page": {
        "type": "home"
      },
      "metadata": {
        "title": "Home"
      }
    },
    {
      "id": "namedPage",
      "uri": "/:pageName",
      "handler": "examples/namedPageHandler",
      "page": {
        "type": "namedPage",
        "attributes": {
          "pageName": ":pageName"
        }
      }
    }
  ],
  "caseSensitive": "true",
  "i18n": {
        "defaultLocale": "en-US",
        "locales": [{ "id": "en-US" }]
    }
}
```

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](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-router-containers.md), too.

```
import { LightningElement } from "lwc";
import { createRouter } from "@lwrjs/router/my-config-file";

export default class MyApp extends LightningElement {
  router = createRouter();
}
```

```
<template>
    <lwr-router-container router={router}>
        <lwr-outlet></lwr-outlet>
    </lwr-router-container>
</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](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-routing-example-simple.md) to get started.

<!-- document id=dc9ea10079a447a581fca991e3d2a34df6cbfdee2049dc357d2ff4a11141b803 url=/developer/current/en-us/lwr-node/lwr/references/csr-reference/createrouter.md -->

# createRouter()

Creates and initializes an LWR router.

## Properties

| Method Input | Type                  | Required/Optional | Description                                                                                                                                                            |
| ------------ | --------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `config`     | `RouterConfig` object | Optional          | Pass in the [`RouterConfig`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/routerconfig.md) object you want to create a router for. If you don't specify a `RouterConfig`, LWR creates a router with default values. |

**note:** We recommend that you specify a `RouterConfig` for `createRouter()`. If you don't pass in a value for `RouterConfig.routes`, the router can't match any locations.

## Syntax

```javascript
import { createRouter } from 'lwr/router';

createRouter(config?: RouterConfig
    ): Router<PageReference>
```

## Returns

- A router object that you can pass to a [router container component](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/lwr-router-container.md).

**See Also**

- [Create a Router: createRouter()](https://developer.salesforce.com/docs/platform/lwr/guides/lwr-create-router.md#createrouter)
- [Routers and Route Matching](https://developer.salesforce.com/docs/platform/lwr/guides/lwr-routers-route-matching.md)
- [Simple Client-Side Routing](https://developer.salesforce.com/docs/platform/lwr/guides/lwr-routing-example-simple.md#create-a-router)

<!-- document id=7d45405f270a1d0c6dfd7418a950b3e0aa92179c00f54bfc3a68f312c3dc8ed4 url=/developer/current/en-us/lwr-node/lwr/references/csr-reference/currentpagereference.md -->

# CurrentPageReference

Gets the current page reference from the router container. This wire is also [available in Lightning Experience](https://developer.salesforce.com/docs/platform/lwc/guide/use-navigate-add-params-url.html).

## Properties

None

## Syntax

```javascript
import { LightningElement, wire } from "lwc";
import { CurrentPageReference } from "lightning/navigation";

export default class Example extends LightningElement {
  @wire(CurrentPageReference)
  propertyOrFunction;
}
```

## Returns

- A [`PageReference`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/pagereference.md) object containing a reference to the current page.

## Example

```javascript
import { LightningElement, wire } from "lwc";
import { CurrentPageReference } from "lightning/navigation";

export default class Example extends LightningElement {
  // Subscribe to page reference updates
  @wire(CurrentPageReference)
  printPageName(pageRef) {
    console.log(`Page name: ${pageRef ? pageRef.attributes.name : ""}`);
  }
}
```

<!-- document id=d9255f02f3d74a3d5d95159ca034ff83818635b415496e4ea39b418ddc23f34e url=/developer/current/en-us/lwr-node/lwr/references/csr-reference/dispose.md -->

# dispose()

Cleans up a route handler module.

**note:** [Route handler **modules**](https://developer.salesforce.com/docs/platform/lwr/guides/lwr-route-handler-modules.md), which are used in client-side routing, aren’t the same as [route handler **functions**](https://developer.salesforce.com/docs/platform/lwr/guides/lwr-routing-server.md#route-handler-functions), which are used in server-side routing.

## Properties

None

## Syntax

```javascript
dispose(): void {
        // perform cleanup tasks
    }
```

## Signature

```javascript
public void dispose()
```

## Returns

- None

**See Also**

- [Route Handler Modules](https://developer.salesforce.com/docs/platform/lwr/guides/lwr-route-handler-modules.md#dispose)
- [Simple Routing Example: Create a Route Handler](https://developer.salesforce.com/docs/platform/lwr/guides/lwr-routing-example-simple.md#create-a-route-handler)

<!-- document id=1339b0d7e07a8d09f836758bb814935f0e00be19b348223ab003b28d3770e9a3 url=/developer/current/en-us/lwr-node/lwr/guides/lwr-enable-ssr-site.md -->

# Enable SSR for LWR Apps

Learn how to activate SSR in your LWR app.

**note:** You have to enable SSR for an app before you can configure [islands architecture](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-understanding-islands.md).

## Opt-in to SSR

SSR is activated on a per-route basis. To enable SSR for a route, set `bootstrap.ssr` to `true` in `lwr.config.json`. Configure this property for every page that you want to render on the server-side.

```
{
    "routes": [
        {
            "id": "ssr-page",
            "path": "/category/:category",
            "contentTemplate": "$contentDir/page.html",
            "bootstrap": {
                "ssr": true
            }
        }
    ]
}
```

When a route with `bootstrap.ssr` is requested, LWR uses the LWC `renderComponent()` function to SSR every root component on that page, regardless of whether the page is generated at runtime or pre-built using `generateStaticSite`.

LWR automatically passes root component attributes from a template as [public properties](https://developer.salesforce.com/docs/platform/lwc/guide/reactivity-public.html) during SSR. For example, the following code prompts LWR to pass the public property `{ limit: '10' }` to `my/root`.

```
<section>
    <!-- "limit" is a template attribute -->
    <my-root limit="10"></my-root>
</section>
```

## SSR Detection

To determine where component code is running, use a script to check the `import.meta.env.SSR` flag. If code runs on the server-side, the flag is `true`. If it runs on the client-side, the flag is [`falsy`](https://developer.mozilla.org/en-US/docs/Glossary/Falsy).

You can use this flag to control where your code runs. For example, this code uses an if-else statement that lets you pivot the runtime environment on the SSR flag.

```
export default class App extends LightningElement {
    connectedCallback() {
        if (import.meta.env.SSR) {
            // run code on the server
        } else {
            // run code on the client
        }
    }
}
```

<!-- When using Typescript, LWR augments the global `ImportMeta interface in the `@lwrjs/types` package.

```javascript
declare global {
    interface ImportMeta {
        readonly env: {
            SSR: boolean;
        };
    }
}
``` -->

## Load Data During SSR

To fetch server-side data for components that rely on external data and resources, use LWR's `getServerData` hook. `getServerData` is only available for **LWR on Node.js-only sites**. During SSR, LWR calls `getServerData()` for every **root component**. Then, the `props` returned by the hook get passed to the root component as public properties during SSR **and** on the client.

Data in `markup` is serialized into the page document as HTML. LWR adds each `markup.link` returned by `getServerData()` to the `<head>` section of the page document.

For example:

```
export default class BookDetails extends LightningElement {
    // These public properties are bound to the "props" returned by getServerData() below
    @api data?: Book;
    @api bookId?: string;
}

export async function getServerData(context: SsrRequestContext): Promise<SsrDataResponse> {
    // This is called to fetch data before the root component is SSRed
    const bookId = context.params.bookId; // The "bookId" path param is declared in lwr.config.json
    const response = await fetch(`https://www.googleapis.com/books/v1/volumes/${bookId}`);
    const data = await response.json();
    return {
        props: { data, bookId }, // Return public properties for the BookDetails component
        cache: { ttl: '60s' }, // Cache the page for 1 minute
        markup: {
            links: [
                {
                    // The thumbnail for the book is important, so the page will preload the image
                    href: data.volumeInfo.imageLinks.thumbnail,
                    as: 'image',
                    rel: 'preload',
                    fetchpriority: 'high',
                },
            ],
        },
    };
}
```

### Time-to-Live

`getServerData()` can return a time-to-live (TTL) for a page in `PageDataResponse.cache.ttl`. To prevent your data from becoming stale, LWR uses `ttl` to set the `max-age` of the [`Cache-control`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#max-age) header on the page. LWR uses the shortest TTL from all sources to set `max-age`.

### `getServerData()` Considerations

- In LWR, the SSR process runs in a secure sandbox. The sandbox supports `globalThis.fetch`, which lets you use `fetch` in `getServerData()` hooks as if the module executes in a browser.
  - Even within `getServerData()` context, your code still has to be portable.
- If `getServerData()` throws an error, the page fails to render and the server returns an HTTP 500 error for the page request. To prevent this, address any errors thrown while fetching data and return default values from `getServerData`.
- The `getServerData()` hook can choose to merge the properties from `SsrRequestContext.props` into its return object, or it can ignore/discard them.
- The author of `getServerData()` is responsible for validating the params and query from `SsrRequestContext` before using them.
- The same props returned by `getServerData()` are passed to the component during server rendering and client hydration.

## Next Steps

Want to implement SSR with more granular control over how specific components on a page get rendered? Take a look at [Understanding Islands](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-understanding-islands.md) to learn more.

<!-- document id=4390f5c47d56bb5023e4a78f4fb883647e7ffd864505b24a7fded5aafd77b5f9 url=/developer/current/en-us/lwr-node/lwr/references/csr-reference/generateurl.md -->

# generateUrl()

Generates a URL for a specified page reference.

## Properties

| Method Input    | Type   | Required/Optional | Description                                                                                                                                                                                      |
| --------------- | ------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `context`       | String | Required          | The ID of the parent router container nearest to the component that's generating a URL. A `ContextId` is an opaque value that you get from the [`NavigationContext`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/navigationcontext.md) wire. |
| `pageReference` | String | Required          | The [`PageReference`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/pagereference.md) value for which to generate a URL.                                                                                                                       |

## Syntax

```javascript
import { LightningElement, api, wire } from 'lwc';
import { NavigationContext, generateUrl } from 'lwr/navigation';
import type { ContextId, PageReference } from 'lwr/navigation';

generateUrl(
    context: ContextId,
    pageReference: PageReference
    ): string | null
```

## Returns

- If `pageReference` is valid, `generateUrl()` returns a string with the generated URL for the specified route.
- If `pageReference` is invalid, it returns `null`.
- If `context` is invalid, `generateUrl()` fails.

**See Also**

- [Simple Client-Side Routing: Navigate](https://developer.salesforce.com/docs/platform/lwr/guides/lwr-routing-example-simple.md#navigate)

<!-- document id=901fc7ecb6fd15452d3322ffa063a478a7dfa82bcc89ef43ab6a793c576b2ccb url=/developer/current/en-us/lwr-node/lwr/guides/lwr-intro.md -->

# Get Started with Lightning Web Runtime on Node.js

With Lightning Web Runtime (LWR) on Node.js, you can develop digital experiences that meet the high scale, security, and performance demands of modern web applications. LWR is a non-opinionated way to configure and load the modules, services, and dependency providers you need to build a JavaScript app. We actually built this site, [developer.salesforce.com](http://developer.salesforce.com/), with LWR.

**note:** This developer guide covers LWR **on Node.js**, which is separate from other LWR-based tools offered by Salesforce.

[LWR powers Experience Cloud](https://developer.salesforce.com/docs/atlas.en-us.exp_cloud_lwr.meta/exp_cloud_lwr/intro.htm), which provides fully managed solutions for customers who want to build websites, portals, and commerce projects. Experience Cloud provides a generally available version of LWR, for customers who don’t want or need to fully manage their own LWR solution.

[Lightning Out 2.0](https://developer.salesforce.com/docs/platform/lwc/guide/lightning-out-intro.html) is also built on LWR.

Web development with LWR is:

- **Performant**&mdash;Thanks to page generation at build time, not runtime, our bar is set at subsecond full-page loads.
- **Frictionless**&mdash;An enjoyable local development experience.
- **Powerful**&mdash;Use the power of [Lightning Web Components](https://developer.salesforce.com/developer-centers/lightning-web-components) and the Salesforce platform with your LWR apps.

LWR describes any configurable aspects of an application in a well-defined, portable format. Its flexible deployment model lets you run applications in a variety of environments, from a local Node.js runtime to a standalone Heroku instance.

LWR on Node.js is available in developer preview as an NPM package. You can bring your own tooling and code to build static websites, single-page applications, and more - on and off Salesforce. Experience flexible, scalable, and performant web development with LWR and the Salesforce platform.

**tip:** To get started, choose a path that's right for you.

- [Quick Start](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-get-started.md)
- [Project Configuration](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-configure-project.md)
- [Packages and Modules](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-packages-modules.md)
- [Use Salesforce Lightning Design System with LWR on Node.js](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-slds.md)
- [Use Lightning Base Components with LWR on Node.js](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-lwc.md)

We love hearing your comments or questions! To share feedback with us, post it in the [LWR on Node](https://trailhead.salesforce.com/trailblazer-community/topics/lwrnode) Trailblazer community topic.

Keep checking back for more details on how to use the flexibility of LWR to build web apps, blogs, as well as deploy to different hosting environments. LWR is just getting started, and we're excited that you are on this journey with us.

<!-- document id=26288c12f38b8a3c9d68e76d213a7dd679eaef103db3fbdc45af498d04d18422 url=/developer/current/en-us/lwr-node/lwr/guides/lwr-ssr-hydration-experience-cloud.md -->

# Hydration Capabilities for Islands (Experience Cloud)

**important:** Experience Delivery (Beta) is being discontinued in October 2026. For more information, see [Experience Delivery (Beta)](https://developer.salesforce.com/docs/atlas.en-us.exp_cloud_lwr.meta/exp_cloud_lwr/experience_delivery.htm).

**important:** This feature is not generally available and is being piloted with certain Customers subject to additional terms and conditions. It is not part of your purchased Services. This feature is subject to change, may be discontinued with no notice at any time in Salesforce’s sole discretion, and Salesforce may never make this feature generally available. Make your purchase decisions only on the basis of generally available products and features. This feature is made available on an AS IS basis and use of this feature is at your sole risk.

For **Experience Cloud sites**, set up SSR and Islands Architecture using **hydration capabilities**. LWR automatically converts capabilities into [hydration directives](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-ssr-islands-implementation.md#opt-into-islands-with-lwrhydrate).

Islands implementation is different for LWR on Node.js-only sites. For information, see [Implement SSR Using Islands](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-ssr-islands-implementation.md).

## Prepare a Page for Islands Architecture

To enable SSR with islands architecture for a page, its theme layout component has to include the `lightning__ServerRenderable` capabilities tag. In the default pages of the Build Your Own (LWR) template, this capability is enabled by default on all standard pages.

If you create a custom theme that doesn't include this capability, the entire page of the route is client-side rendered. To learn more about creating a custom theme for an Experience Cloud page, see [Custom Theme Layouts and Theme Layout Components](https://help.salesforce.com/s/articleView?id=experience.community_builder_theme.htm).

## Audit Your Component Trees for SSR

Lightning Web Runtime (LWR) creates islands for a page by processing the hydration capabilities of the page’s components. For island creation to succeed, your nested components have to follow these rules.

- Client-side rendering (CSR)-only components can contain any type of component.
- Hydrated components contain SSR-only components or other hydrated components.
- SSR-only components contain other SSR-only components.

To quickly check if your components follow these rules, use the `lwr audit` command on the LWR command line interface (CLI). You can specify which components to audit on the command line.

```
# audit all components in an SFDX project
ls force-app/main/default/lwc | xargs lwr audit --components

# audit all components for a given namespace in a LWC or LWR project
ls src/modules/<namespace> | xargs lwr audit --namespace <namespace> --components
# see the list of supported options for the audit command
lwr audit --help
```

For each specified component and all the components in its component tree, `lwr audit` prints the capability assigned to each component and whether or not it’s valid for the tree.

![Screenshot of the CLI for a component tree that passed lwr audit tests.](https://developer.salesforce.com/docs/media/valid-capabilities.png)

If a component fails the SSR audit, review the failure message printed on the command line and assign a valid capability to it.

![Screenshot of the CLI for a component tree that failed lwr audit tests.](https://developer.salesforce.com/docs/media/invalid-capabilities.png)

## Enable SSR with Islands for a Component

Once you enable islands architecture for a page, you can configure which root components create islands. Experience Cloud sites on LWR support the following configurations of islands architecture for components.

**note:** If a template contains any child components that aren’t portable, then the parent component is also not portable. Don’t include these capabilities on a non-portable component, as the entire page will fail to render with a 500 error from the server.

### SSR with Hydration

To enable SSR with hydration for a custom component, add the `lightning__ServerRenderableWithHydration` capabilities tag to the component’s configuration file.

```
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
   <apiVersion>60.0</apiVersion>
   <capabilities>
       <capability>lightning__ServerRenderableWithHydration</capability>
   </capabilities>
</LightningComponentBundle>
```

In the following diagram, the `c/interactive` component has the `lightning__ServerRenderableWithHydration` capability. It creates a hydrated island nested inside the static layout.

| view metadata components                                                                                                                           | Resulting page HTML                                                                                                                       |
| -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| ![view metadata components for an example of the SSR with hydration capability](https://developer.salesforce.com/docs/media/ssr-hydration-metadata.png '{"class": "image-xs"}') | ![Resulting page HTML for an example of the SSR with hydration capability](https://developer.salesforce.com/docs/media/ssr-hydration-html.png '{"class": "image-xs"}') |

### SSR only

To enable only SSR for a custom component, add the `lightning__ServerRenderable` capabilities tag to the component’s configuration file. Use this capability only if you don't expect any updates or interactivity from your components after they're rendered.

```
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
   <apiVersion>60.0</apiVersion>
   <capabilities>
       <capability>lightning__ServerRenderable</capability>
   </capabilities>
</LightningComponentBundle>
```

In the following diagrams, the page doesn't contain any islands, so the component outputs static HTML.

| view metadata components                                                                                                            | Resulting page HTML                                                                                                        |
| ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| ![view metadata components for an example of the SSR only capability](https://developer.salesforce.com/docs/media/ssr-only-metadata.png '{"class": "image-xs"}') | ![Resulting page HTML for an example of the SSR only capability](https://developer.salesforce.com/docs/media/ssr-only-html.png '{"class": "image-xs"}') |

### CSR only

CSR is the default capability, so it doesn't require a tag. Components using dynamic component visibility are considered CSR-only, regardless of the capability tag in the component metadata. Expressions used for dynamic data aren’t considered when calculating island boundaries or capabilities.

| view metadata components                                                                                                            | Resulting page HTML                                                                                                        |
| ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| ![view metadata components for an example of the CSR only capability](https://developer.salesforce.com/docs/media/csr-only-metadata.png '{"class": "image-xs"}') | ![Resulting page HTML for an example of the CSR only capability](https://developer.salesforce.com/docs/media/csr-only-html.png '{"class": "image-xs"}') |

## Nested Components and Precedence

For certain parent-child relationships between nested components, the configuration of one component overrules the configuration of the other. Islands capability is determined by the least SSR-capable component within the island boundary. An island boundary is determined by the first component encountered on the page that isn't SSR only.

The following precedence rules only apply to components on **Experience Cloud LWR sites**.

### Server-Rendered with Hydrated Parent

If a parent component is configured for SSR with hydration and its child component is configured for SSR-only, the child component gets hydrated.

In this example, the `c/a` child component rolls up into a single hydrated island with its parent, `c/banner`.

| view metadata components                                                                                                                                         | Resulting page HTML                                                                                                                                     |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ![view metadata components for an example of a hydrated parent component taking precedence](https://developer.salesforce.com/docs/media/hydrated-parent-metadata.png '{"class": "image-xs"}') | ![Resulting page HTML for an example of a hydrated parent component taking precedence](https://developer.salesforce.com/docs/media/hydrated-parent-html.png '{"class": "image-xs"}') |

### Client-Rendered Parent

If a parent component is rendered on the client-side and has **no** SSR capability, all of its child components also render on the client-side.

In this example, the `c/a` and `c/b` child components roll up into a single CSR-only island with their parent, `c/list`.

| view metadata components                                                                                                                                 | Resulting page HTML                                                                                                                             |
| -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| ![view metadata components for an example of a CSRed parent component taking precedence](https://developer.salesforce.com/docs/media/csr-parent-metadata.png '{"class": "image-xs"}') | ![Resulting page HTML for an example of a CSRed parent component taking precedence](https://developer.salesforce.com/docs/media/csr-parent-html.png '{"class": "image-xs"}') |

### Client-Rendered Child

If a parent component is configured for SSR with hydration, and it contains a child component with **no** SSR capability, the parent component also gets rendered on the client side.

In this example, the `c/banner` parent component is a CSR-only island to accommodate its child component, `c/c`.

| view metadata components                                                                                                                               | Resulting page HTML                                                                                                                           |
| ------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| ![view metadata components for an example of a CSRed child component taking precedence](https://developer.salesforce.com/docs/media/csr-child-metadata.png '{"class": "image-xs"}') | ![Resulting page HTML for an example of a CSRed child component taking precedence](https://developer.salesforce.com/docs/media/csr-child-html.png '{"class": "image-xs"}') |

## Non-Portable Children

If a template contains any child components that aren't portable, each child's parent component also isn't portable.

Don't include these hydration capabilities in a non-portable component. A component with an incompatible capability prevents the entire page from rendering and causes the server to throw a 500 error. To learn how to quickly evaluate your components for incompatible capabilities, see [Audit Your Component Trees for SSR](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-configure-component-ssr.md#1-audit-your-component-trees-for-ssr).

## Islands Architecture Considerations

- During SSR, all data requests are made as if the user hasn’t logged in. As a result, authentication-related scoped modules and data are resolved in a guest user context. Authenticated data is fetched during hydration, so a component only updates with authenticated data on the client side.
- Components that use dynamic component visibility are considered CSR-only, regardless of the capability tag in their component metadata.
- You can use [expressions](https://developer.salesforce.com/docs/atlas.en-us.exp_cloud_lwr.meta/exp_cloud_lwr/advanced_expressions.htm) to add dynamic data to your LWR site. However, these expressions aren't considered when island boundaries and capabilities are calculated.

## Scoped Modules Limitations

Scoped modules provide functionality specific to users, sites, or orgs. For more information about Salesforce scoped modules, see [Lightning Web Components Developer Guide: `@salesforce` Modules](https://developer.salesforce.com/docs/platform/lwc/guide/reference-salesforce-modules.html).

The following limitations only affect Experience Cloud LWR sites.

### Org- and Site-Specific Modules

Org- and site-specific modules are frozen, which means that their values are immutable at publishing time.

These Salesforce scoped modules are frozen:

- `@salesforce/apex/*`
- `@salesforce/client/formFactor`
- `@salesforce/community/Id`
- `@salesforce/contentAssetUrl/*`
- `@salesforce/i18n/*`
- `@salesforce/label/*`
- `@salesforce/messageChannel/*`
- `@salesforce/resourceUrl/*`
- `@salesforce/schema/*`

This scoped module is frozen and can require another publish if you change its value.

- `@salesforce/community/basePath`

#### Form Factor

The [`@salesforce/client/formFactor` value](https://developer.salesforce.com/docs/platform/lwc/guide/create-client-form-factor.html) defaults to "Large" during SSR, regardless of the hardware which made the request. To avoid UI shifting on page load, use [CSS media queries](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries) instead. For images, consider using [Responsive Images](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images) to embed the appropriate image source for different form factors.

```js
// before
import FORM_FACTOR from "@salesforce/client/formFactor";
export default class Sample extends LightningElement {
  classes = "";
  connectedCallback() {
    this.classes = FORM_FACTOR === "small" ? "mobile" : "";
  }
}
```

```html
<!-- before -->
<template>
  <div class="{classes}">
    <div class="col-3"><!-- ... --></div>
    <div class="col-6"><!-- ... --></div>
    <div class="col-3"><!-- ... --></div>
  </div>
</template>
```

```css
/* before */
.col-3 {
  width: 25%;
}
.col-6 {
  width: 50%;
}
.mobile .col-3 {
  width: 100%;
}
.mobile .col-6 {
  width: 100%;
}
```

```js
// after
export default class Sample extends LightningElement {}
```

```html
<!-- after -->
<template>
  <div>
    <div class="col-3"><!-- ... --></div>
    <div class="col-6"><!-- ... --></div>
    <div class="col-3"><!-- ... --></div>
  </div>
</template>
```

```css
/* after */
.col-3 {
  width: 25%;
}
.col-6 {
  width: 50%;
}

/* mobile */
@media (max-width: 768px) {
  [class*="col-"] {
    width: 100%;
  }
}
```

### User-Specific Modules

User-specific modules include:

- `@salesforce/user`
- `@salesforce/userPermission`
- `@salesforce/customPermission`

These modules are evaluated on the client without any server calls. They're considered "live scoped modules" because they're mutable and can change independently of publishing. They generally can't be cached, and they default to guest-only values for SSR — so when a user authenticates, the values are re-fetched on the client.

If you import `@salesforce/user/isGuest`, it resolves to `true` during SSR, regardless of the actual authentication status. However, when the page is hydrated on the client, it resolves to the correct value.

Rendering as a guest on the server and rehydrating as an authenticated user on the client can cause rendering issues. For example, SSRing content as a guest on the server can display something completely different than the page displayed for the authenticated user. If you use modules that require personalized content, we recommend following these guidelines so that your content renders and hydrates successfully.

- During SSR, render an empty placeholder element. Then, render something more appropriate during client-side rendering (CSR).
- Use a CSR-only island to render only on the client.

**See Also**

- [LWR Sites for Experience Cloud Guide: Create Components for LWR Sites](https://developer.salesforce.com/docs/atlas.en-us.exp_cloud_lwr.meta/exp_cloud_lwr/get_started_components.htm)

<!-- document id=30e16c062fcfc95d9e55b011edcc137a26f7c0fc7fea13efc7a993d9ca264c01 url=/developer/current/en-us/lwr-node/lwr/guides/lwr-ssr-islands-implementation.md -->

# Implement SSR Using Islands Architecture

Learn how to use the LWR hydration directive `lwr:hydrate` to create islands of component interactivity.
**Islands architecture** lets you pick which parts of your page you want to hydrate and make interactive. The rest of the page is static HTML. By only hydrating specific components instead of the entire page, your page loads more efficiently.

This method of implementing server-side rendering (SSR) only works for a server-rendered, **LWR on Node.js-only** site.

## Opt into Islands with `lwr:hydrate`

**Hydrating** a component starts its [component lifecycle](https://developer.salesforce.com/docs/platform/lwc/guide/create-lifecycle-hooks.html) and makes it interactive.

With the `lwr:hydrate` directive, you can create islands that use SSR with hydration or CSR.

### lwr:hydrate Limitations

- You can only apply `lwr:hydrate` to root components, which are Lightning web components (LWC) in a route's [LWR content templates, layout templates](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-templates.md), or `rootComponent` configuration.
  - If you add `lwr:hydrate` to an LWC component template, it won't work.

**note:** You have to [enable SSR](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-enable-ssr-site.md) for an app before you can configure islands architecture.

## Island Configurations

You can choose from these different configuration options for an islands architecture.

### SSR with Hydration

To opt-in to hydration and create an island for a **server-rendered** root component, add the `lwr:hydrate` directive to the component.

```
<!-- hydrated -->
<my-contact lwr:hydrate></my-contact>

<!-- NOT hydrated -->
<my-about></my-about>
```

| Resulting page HTML                                                                                           |
| ------------------------------------------------------------------------------------------------------------- |
| ![Server-rendered and hydrated component.](https://developer.salesforce.com/docs/media/lwr-node-ssr-hydration.png '{"class": "image-xs"}') |

### CSR only

Root components can use CSR instead of SSR by setting the `lwr:hydrate` directive to `client-only` and creating a client-rendered island. On the client-side, LWC `createElement()` API fully renders root components that opt-out of SSR.

```
<!-- SSRed -->
<my-info></my-info>

<!-- NOT SSRed -->
<my-map lwr:hydrate="client-only"></my-map>
```

| Resulting page HTML                                                                    |
| -------------------------------------------------------------------------------------- |
| ![Client-rendered component.](https://developer.salesforce.com/docs/media/lwr-node-csr.png '{"class": "image-xs"}') |

**tip:** For more information and guidance on island types, see [Understanding Islands](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-understanding-islands.md).

## SSR Warnings and Errors

After you implement SSR, review your output for the following SSR-related issues.

### Hydration Warnings

If the server-rendered component HTML doesn't match the output of its **first rendering cycle** on the client, Lightning Web Components (LWC) logs a hydration warning. To avoid hydration warnings, ensure that only asynchronous actions (like user interaction, data updates, or [eventing](https://developer.salesforce.com/docs/platform/lwc/guide/events.html)) cause template updates.

### Timeouts

By default, if SSR takes longer than five seconds, LWR times out and returns a 500 error. The timeout length includes [loading data](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-enable-ssr-site.md#load-data-during-ssr). You can override the timeout length by setting the `SSR_TIMEOUT` environment variable to a number in milliseconds before running the app.

```bash
# set the timeout to 10 seconds
SSR_TIMEOUT=10000 npm run start
```

<!-- document id=c3e2bba65ae4f3c83060f96b6537dd7c8f43e1c7860c9e69af8c5c350c56319a url=/developer/current/en-us/lwr-node/lwr/guides/lwr-label-module-provider.md -->

# Label Module Provider

Want to localize labels and reuse them across different pages? The Label Module Provider serves file-based labels as ES modules, and it shows different translations of each label depending on the user's locale.

To determine the user's locale, the Label Module Provider evaluates these resources in this order:

1. The `locale` path parameter in the request
2. The `Accept-Language` header in the request
3. The default locale set by the runtime

## Create Reusable Labels

In your project's `src` directory, add a `labels` folder. For each supported locale, create a JSON file that contains all the labels you want to use. The name of each file should be the **all-lowercase** locale code corresponding to the language and region of its labels. For example, if you have labels for the `fr-FR` locale, put them in a file named `fr-fr.json`.

If the Label Module Provider can't find a label file for a requested language and region code, it looks for a file that corresponds to only the requested language. For example, if a user requests `en-US` labels but you don't have an `en-us.json` file, the module provider looks for an `en.json` file as a fallback.

```
src/
  ├── assets/
  ├── labels/
  │   ├── en.json       // English
  │   ├── es.json       // Spanish
  │   ├── it.json       // Italian
  │   └── fr-fr.json    // French (France)
  ├── labelHandler.ts   // route handler for template translations
  ├── layout.html       // static layout template
  └── modules/
lwr.config.json
package.json
```

Here's an example of a file with labels for the English (`en`) language.

```
{
    "title": "Translation",
    "home": {
        "greeting": "Welcome"
    },
    "animal": {
        "cat": "Cat",
        "dog": "Dog"
    }
}
```

The same labels for the French (`fr`) language and country of France (`FR`) are in a separate file.

```
{
    "title": "Traduction",
    "home": {
        "greeting": "Bienvenu"
    },
    "animal": {
        "cat": "Chat",
        "dog": "Chien"
    }
}
```

## Add the Label Module Provider

To import the package for this module provider (`@lwrjs/label-module-provider`), run this code in your terminal. This also adds a dependency on `@lwrjs/label-module-provider` to your project's `package.json`.

```bash
npm install @lwrjs/label-module-provider
```

Then, register the module provider in `lwr.config.json`. Remember to include all the default module providers in the `moduleProviders` array.

```
{
  "moduleProviders": [
    "@lwrjs/label-module-provider",       // Add the Label Module Provider
    "@lwrjs/app-service/moduleProvider",  // Default provider
    "@lwrjs/router/module-provider",      // Default provider
    "@lwrjs/lwc-module-provider",         // Default provider
    "@lwrjs/npm-module-provider",         // Default provider
    "@lwrjs/module-registry/externals-module-provider"    // Default provider
  ]
}
```

In the same config file, add a route handler to the app route.

```
{
    "routes": [
        {
            "id": "labels",
            "path": "/",
            "routeHandler": "$rootDir/src/labelHandler.ts"
        }
    ]
}
```

## Optional: Configure the Label Module Provider

In `lwr.config.json`, you can set a package specifier for importing labels and customize the filepath of the label files.

- `provideDefault` - When `true`, the module provider returns the label reference as the value for any label it can't find. When `false`, the module provider returns `undefined` for labels it can't find. This lets any module providers called afterward attempt to resolve the request.
- `labelDirs` - An array of one or more label package namespaces and their locations in the project directory.

```
{
    "moduleProviders": [
        // Start of Label Module Provider configuration
        [
            "@lwrjs/label-module-provider",
            {
                "provideDefault": true,
                "labelDirs": [
                    {
                        "dir": "$rootDir/src/labels",   // Filepath
                        "package": "@my/label"          //
                    }
                ]
            }
        ],
        // End of Label Module Provider configuration
         "@lwrjs/app-service/moduleProvider",
    ]
}
```

If you don't specify a value for `dir` or `package`, the module provider uses the following configuration by default.

```
{
    "provideDefault": false,
    "labelDirs": [
        {
            "dir": "$rootDir/src/labels",
            "package": "@salesforce/label"
        }
    ]
}
```

## Import Labels into a Component

After you create your label files and configure the Label Module Provider, you can import labels into your components.

Here's an example of an app that displays a localized string (`greeting`) on its homepage. The Label Module Provider returns the label value from the file corresponding to the requested locale.

```
<!-- app.html -->
<template>
    <h1>{greeting}</h1>
</template>
```

```
import { LightningElement } from 'lwc';
import GREETING from '@my/label/home.greeting';

export default class LocalizedApp extends LightningElement {
    greeting = GREETING;
}
```

In this example:

- `import GREETING from '@my/label/home.greeting'` determines the language of the text that's displayed on the homepage.
- `@my/label` is the package namespace configured through the Label Module Provider
- `home.greeting` is the label reference in the label files. It's in the format of a property selector for label JSON file.

## Import Labels into a Template

Templates can't access the Label Module Provider. To pass translated strings into static templates, use a route handler. Templates have access to the `viewParams` returned by the route handler.

```
import type { HandlerContext, LocalizedViewRequest, RouteHandlerViewResponse } from '@lwrjs/types';

const DEFAULT_LOCALE = 'en';

function getViewParams(locale: string, rootDir: string): { title: string; language: string } {
    // Get the translated string from the file system, a database, etc.
}

// Return translated strings to be used in the layout template
export default function translationRouteHandler(
    viewRequest: LocalizedViewRequest,
    context: HandlerContext,
): RouteHandlerViewResponse {
    const locale = viewRequest.locale || DEFAULT_LOCALE;
    const params = getViewParams(locale, context.rootDir);
    return {
        view: {
            // This layout template uses the viewParams
            layoutTemplate: '$rootDir/src/layout.html',
        },
        viewParams: {
            // available as {{title}} or {{page.title}} in the layout template
            title: params.title,
            // available as {{language}} in the layout template
            language: params.language,
        },
    };
}
```

```
<!doctype html>
<html lang="{{language}}">
    <head>
        <title>{{title}}</title>
    </head>
    <body>
        <example-app></example-app>
        {{{lwr_resources}}}
    </body>
</html>
```

<!-- document id=f8ba1fcb28f02b537521e21818d007068a56aa82f124a17c83e7dd773e59b36c url=/developer/current/en-us/lwr-node/lwr/guides/lwr-locker.md -->

# Lightning Locker

To improve the security of your LWR apps, enable Lightning Locker.

Locker is a security architecture for Lightning web components (LWCs). To learn how Locker enhances the security of your components and code, visit [Lightning Aura Components Developer Guide: Lightning Locker](https://developer.salesforce.com/docs/platform/lightning-components-security/guide/locker-intro.html).

## Compatibility with LWR

- Locker is only supported for applications in AMD mode. It doesn't work for ESM mode. For more information about LWR application modes, see [Set the LWR Server Modes](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-get-started.md#set-the-lwr-server-modes).
- Locker is only supported on the client-side. You can't enable Locker for server-side code.

## Enable Locker

To opt-in to Locker, add the `locker` config to your project's `lwr.config.json`. You can determine which components run outside of Locker by listing them in the `trustedComponents` property.

```
{
    "lwc": {
        "modules": [{ "dir": "$rootDir/src/modules" }]
    },
    "locker": {
        "enabled": true,
        "trustedComponents": ["lightning/*", "example/app", "example/trustedCmp"]
    },
    "routes": [
        {
            "id": "locker-base",
            "path": "/",
            "rootComponent": "example/app",
            "layoutTemplate": "$layoutsDir/main.html"
        }
    ]
}
```

<!-- document id=1974ebf596162a728f1506f64bb2602a2b071f3ea4539ca6b74c1f5a203ba1eb url=/developer/current/en-us/lwr-node/lwr/references/csr-reference/lwc-for-lwr-navigation.md -->

# Lightning Web Components for LWR Navigation

You can use these Lightning web components for LWR client-side routing:

- [`lwr-router-container`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/lwr-router-container.md)
- [`lwr-outlet`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/lwr-outlet.md)

<!-- document id=e0609b27bc1c2f23fe4f8484e54d77b35abc73bd4617cea4a6c5d6aa29611ea0 url=/developer/current/en-us/lwr-node/lwr/guides/lwr-release-notes.md -->

# Lightning Web Runtime Release Notes

To learn what's new and changed, see the _Salesforce Release Notes_.

There may not be changes every release. If there are changes, they're listed under the Development section.

[_Salesforce Release Notes_: Development](https://help.salesforce.com/s/articleView?id=release-notes.rn_development.htm)

<!-- document id=ceea4b58ba60a31b7a2214193a6ebea3877d627d46ea403c17f0bed7744c6895 url=/developer/current/en-us/lwr-node/lwr/references/lwr-build.md -->

# lwr build

The `lwr build` command generates static site files as well as any configuration files for specified command `{options}`.

| Option                         | Type    | Required/Optional | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------------------------ | ------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-t`, `--target <target>`      | String  | Optional          | Set the site deployment target. If a target isn't specified, the default value is `default`. Accepted values are: <ul><li>`default` - Generates the static site wouthout any configuration options.</li><li>`mrt` - Generates the static site with a [Managed Runtime configuration.](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/mrt-overview.html)</li><li>`netlify` - Generates the static site with a Netlify configuration.</li></ul> |
| `-m`, `--mode <mode>`          | String  | Optional          | Set the [server mode](https://developer.salesforce.com/docs/platform/lwr/references/guides/lwr-get-started.md#set-the-lwr-server-modes). Accepted values are `prod` and `prod-compat`.                                                                                                                                                                                                                                                                                                                                                 |
| `-o`, `--output <directory>`   | String  | Optional          | Set the output directory for all of your static site files. If a directory isn't specified, the default value is `app`.                                                                                                                                                                                                                                                                                                                                                     |
| `--clean`                      | Boolean | Optional          | Delete an existing output directory. If the specified output directory already exists, the console logs a warning. By default, an existing output directory isn't deleted.                                                                                                                                                                                                                                                                                                  |
| `-r`, `--routes <routes...>`   | Routes  | Optional          | Specify the routes to include during the build using regex. If routes aren't specified, the default value is `[]`.                                                                                                                                                                                                                                                                                                                                                          |
| `-m`, `--modules <modules...>` | Modules | Optional          | Specify additional [modules](https://developer.salesforce.com/docs/platform/lwr/references/guides/lwr-packages-modules.md) to be generated during the build. If modules aren't specified, the default value is `[]`.                                                                                                                                                                                                                                                                                                                   |
| `-l`, `--locales <locales...>` | Locales | Optional          | Specify the list of locales to build your site for. The default value is `['en']`.                                                                                                                                                                                                                                                                                                                                                                                          |
| `--minify`                     | Boolean | Optional          | Minify the build output. By default, build output isn't minified.                                                                                                                                                                                                                                                                                                                                                                                                           |
| `-h`, `--help`                 |         | Optional          | View help text for `lwr build` options in the CLI.                                                                                                                                                                                                                                                                                                                                                                                                                          |

<!-- document id=4dd485267f81ac2f90953fa85d0a97a817e0d4485cd4870113909b788dd399f1 url=/developer/current/en-us/lwr-node/lwr/references/lwr-dev.md -->

# lwr dev

The `lwr dev` command starts a local development server that recompiles the source when it observes changes to local files. You can append `{options}` to this on the command line to configure settings like port number and server mode for your local server.

| Option                | Type    | Required/Optional | Description                                                                                                                                                                                                 |
| --------------------- | ------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-p`, `--port <port>` | Number  | Optional          | Set the [port](https://developer.salesforce.com/docs/platform/lwr/references/guides/lwr-configure-project.md#configure-the-port-and-server) for the local development server. If a port isn't specified, the default value is `3000`.                                  |
| `-m`, `--mode <mode>` | String  | Optional          | Set the [server mode](https://developer.salesforce.com/docs/platform/lwr/references/guides/lwr-get-started.md#set-the-lwr-server-modes). If a server mode isn't specified, the default value is `dev`. Accepted values are `dev`, `compat`, `prod-compat`, and `prod`. |
| `-o`, `--open`        | Boolean | Optional          | Open the static site in the browser on startup. By default, the browser doesn't open on startup.                                                                                                            |
| `-h`, `--help`        |         | Optional          | View help text for `lwr dev` options in the CLI.                                                                                                                                                            |

<!-- document id=6f7f1382bef2bae4309e99113e43b2551fb6467a6f3f02169e4050744bed17c3 url=/developer/current/en-us/lwr-node/lwr/references/csr-reference/nav-data-types.md -->

# LWR Navigation Data Types

You can use these data types for client-side routing.

- [LwrRouterConfig](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/lwrrouterconfig.md)
- [LwrConfigRouteDefinition](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/lwrconfigroutedefinition.md)
- [PageReference](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/pagereference.md)
- [RouteDefinition](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/routedefinition.md)
- [RouteInstance](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/routeinstance.md)
- [RouterConfig](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/routerconfig.md)
- [RouteDestination](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/routedestination.md)

<!-- document id=4bce8170845c4a0e7dc7dccfae7b0b9fc69ef4005aa535671ee843767cc0b6ed url=/developer/current/en-us/lwr-node/lwr/references/csr-reference/nav-methods.md -->

# LWR Navigation Methods

You can use these methods for client-side routing.

- [createRouter()](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/createrouter.md)
- [generateUrl()](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/generateurl.md)
- [navigate()](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/navigate.md)

<!-- document id=57811e20ff790eabefa4f23473d6044d741f7fc4a430cdafb70f4b22ef3a5ca5 url=/developer/current/en-us/lwr-node/lwr/references/csr-reference/lwr-navigation-wires.md -->

# LWR Navigation Wires

Lightning web components can receive information about navigation events from wire adapters provided by the `lwr/navigation` module.

You can use these wires for client-side routing:

- [`CurrentPageReference`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/currentpagereference.md)
- [`NavigationContext`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/navigationcontext.md)

<!-- document id=76ca15edbfe6fce05a553918c613d24babd90f5e4bc3fa6e8a0fce286909b33b url=/developer/current/en-us/lwr-node/lwr/references/lwr-start-lwr-preview.md -->

# lwr start|preview

To preview your site in its target environment after you successfully run `lwr build`, run `lwr start` or `lwr preview`.

If you run this command without a prebuilt directory, it'll default to the standard LWR standalone server and it won't use any statically generated content.

| Option                        | Type    | Required/Optional | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ----------------------------- | ------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-p`, `--port <port>`         | Number  | Optional          | Set the [port](https://developer.salesforce.com/docs/platform/lwr/references/guides/lwr-configure-project.md#configure-the-port-and-server) for the local development server. If a port isn't specified, the default value is `3000`.                                                                                                                                                                                                                                                                                                  |
| `-m`, `--mode <mode>`         | String  | Optional          | Set the [server mode](https://developer.salesforce.com/docs/platform/lwr/references/guides/lwr-get-started.md#set-the-lwr-server-modes). If a server mode isn't specified, the default value is `dev`. Accepted values are `dev`, `compat`, `prod-compat`, and `prod`.                                                                                                                                                                                                                                                                 |
| `-t`, `--target <target>`     | String  | Optional          | Set the site deployment target. If a target isn't specified, the default value is `default`. Accepted values are: <ul><li>`default` - Generates the static site wouthout any configuration options.</li><li>`mrt` - Generates the static site with a [Managed Runtime configuration.](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/mrt-overview.html)</li><li>`netlify` - Generates the static site with a Netlify configuration.</li></ul> |
| `-b`, `-buildDir <directory>` | String  | Optional          | Specify the prebuilt directory for your static site.                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `-o`, `--open`                | Boolean | Optional          | Open the static site in the browser on startup. By default, the browser doesn't open on startup.                                                                                                                                                                                                                                                                                                                                                                            |
| `-h`, `--help`                |         | Optional          | View help text for `lwr start` and `lwr preview` options in the CLI.                                                                                                                                                                                                                                                                                                                                                                                                        |

<!-- document id=dcbf3e38a19521c9ad094c8bc23f371f14064d4fe0d7706d4ef4482912039da1 url=/developer/current/en-us/lwr-node/lwr/references/csr-reference/lwr-outlet.md -->

# lwr-outlet

An outlet dynamically renders view components, which display when an application navigates to a location.

## Properties

| Property      | Type    | Required/Optional | Description                                                                                                                                               |
| ------------- | ------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `view-name`   | String  | Optional          | The key of the [`ViewSet`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/routedestination.md#viewset) entry to display. The default value is `default`.                                                 |
| `refocus-off` | Boolean | Optional          | Refocusing is on by default for accessibility. If `refocus-off` is present, the outlet doesn't put the browser focus on the view component when it loads. |

## Events

An outlet component fires these [events](https://developer.salesforce.com/docs/platform/lwc/guide/events-handling.html):

- `onviewchange`
  - A handler for the `viewchange` event that is dispatched whenever the view component changes. `event.detail` is the view component class.

```javascript
type Constructor<T = object> = new (...args: any[]) => T;
interface Constructable<T = object> {
    constructor: Constructor<T>
}
interface ViewChangePayload {
    detail: Constructable;
}
```

- `onviewerror`
  - A handler for the `viewerror` event that is dispatched whenever the view component cannot be rendered. `event.detail` is the error and stack.

```javascript
interface ViewErrorPayload {
  detail: {
    error: Error,
    stack: string,
  };
}
```

### Usage

An outlet dynamically renders view components. The `lwr-outlet` Lightning web component displays the current view component in the DOM.

This process is naturally lazy. The view isn't imported until the outlet consumes it, so any unused views aren't fetched. When the router's view state changes, the outlet is flagged to display the vivew. At that point, if the view module hasn't been fetched already, there may be an async process to retrieve it.

```
<template>
    <lwr-router-container>
        <lwr-outlet refocus-off onviewchange={onViewChange} onviewerror={onViewError}>
            <div slot="error">View component cannot display</div>
        </lwr-outlet>
    </lwr-router-container>
</template>
```

It's possible for a [route definition handler](https://developer.salesforce.com/docs/platform/lwr/guides/lwr-route-handler-modules.md#1-the-router-calls-routedefinitionhandler) to return multiple views, like this:

```javascript
import type { Module, RouteHandlerCallback } from "lwr/router";

export default class HomeHandler {
  callback: RouteHandlerCallback;

  constructor(callback: RouteHandlerCallback) {
    this.callback = callback;
  }

  dispose(): void {}

  update(): void {
    this.callback({
      viewset: {
        // return multiple views
        default: (): Promise<Module> => import("my/home"),
        nav: (): Promise<Module> => import("my/homeNav"),
        footer: (): Promise<Module> => import("my/homeInfo"),
      },
    });
  }
}
```

You can use multiple outlets to display all the current view components by setting different `view-name` values.

```
<template>
    <lwr-router-container>
        <lwr-outlet view-name="nav"></lwr-outlet>
        <lwr-outlet><!-- default view --></lwr-outlet>
        <lwr-outlet view-name="footer"></lwr-outlet>
    </lwr-router-container>
</template>
```

<!-- document id=d3572aa9c14c3c3fc9912c384a5d6adb33bfd51bf4a8d217ff2c2d5f33b04492 url=/developer/current/en-us/lwr-node/lwr/references/csr-reference/lwr-router-container.md -->

# lwr-router-container

A [router container](https://developer.salesforce.com/docs/platform/lwr/guides/lwr-router-containers.md) provides navigation context by processing all [navigation wires](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/lwr-navigation-wires.md) and events from its descendants in the DOM.

## Properties

| Property           | Type          | Required/Optional | Description                                                                                                                                                                                                       |
| ------------------ | ------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `router`           | Router object | Optional          | Obtained from the [`createRouter()` API](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/createrouter.md).                                                                                                                                                        |
| `history-disabled` | Boolean       | Optional          | Set `history-disabled` to `true` if your router container shouldn't alter the browser's [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) during navigation events or location changes. |

## Syntax

```
<lwr-router-container
  router="{router}"
  <!-- Event handlers -->
  onhandlenavigation="{handleNavigation}"
  onprenavigate="{preNavigate}"
  onpostnavigate="{postNavigate}"
  onerrornavigate="{errorNavigate}"
>
  <my-nav></my-nav>
  <lwr-outlet></lwr-outlet>
</lwr-router-container>
```

## Returns

A router container fires these events:

- `onhandlenavigation`
  - Dispatched when [`navigate(pageRef)`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/navigate.md) is called. `event.preventDefault()` cancels the navigation event. `event.detail` is the [`PageReference`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/pagereference.md).
- `onprenavigate`

  - Dispatched when a navigation event is received and a [`RouteDefinition`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/routedefinition.md) match is found. `event.preventDefault()` cancels the navigation event. `event.detail` is a `RouteChange` object.

    ```javascript
    interface RouteChange {
      current?: DomRoutingMatch; // the current location info
      next: DomRoutingMatch; // location info for the incoming nav event
    }
    ```

- `onpostnavigate`

  - Dispatched when a navigation event has completed. `event.detail` is a `DomRoutingMatch` object for the current location.

    ```javascript
    interface DomRoutingMatch {
      url: string; // e.g. "/recipes/desserts/010?units=metric&yummy=yes"
      route: RouteInstance;
      routeDefinition: RouteDefinition;
    }
    ```

- `onerrornavigate`

  - Dispatched when there's an error processing a navigation event. (For example, no `RouteDefinition` match or a `prenavigate` cancellation.) `event.detail` is a `MessageObject`.

    ```javascript
    interface MessageObject {
      code: string | number;
      message: string;
      level: number; // Fatal = 0, Error = 1, Warning = 2, Log = 3
    }
    ```

**See Also**

- [Simple Routing Example: Navigate](https://developer.salesforce.com/docs/platform/lwr/guides/lwr-routing-example-simple.md#navigate)

<!-- document id=b09fac8843177d6f935536d8f5cb82ff8213e0de858ca9bc1b8e15b38334299c url=/developer/current/en-us/lwr-node/lwr/references/csr-reference/lwrconfigroutedefinition.md -->

# LwrConfigRouteDefinition

**important:** To configure a router module with the [Router Module Provider](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-create-router.html#router-module-provider), you have to set up both [`LwrRouterConfig`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/lwrrouterconfig.md) and `LwrConfigRouteDefinition`.

## Syntax

```
interface LwrConfigRouteDefinition<TMetadata = Record<string, any>> {
    id: string;
    uri: string;
    page: Partial<PageReference>
    patterns?: { [paramName: string]: string };
    exact?: boolean;
    metadata?: TMetadata;
    // LwrConfigRouteDefinition must have ONE of the following, not both
    handler?: string; // a STRING reference to the handler class
    component?: string; // a STRING reference to a page component
}
```

## Properties

`LwrConfigRouteDefinition` object contains similar properties as the [`RouteDefinition`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/routedefinition.md) object. `handler` and `component` are string references, as LwrConfigRouteDefinition is pure JSON and can't contain any functions. Only define either the `handler` or `component` property, **not both**.

| Property    | Type    | Required/Optional | Description                                                                                                                                                                                                                                                                                                                                                                                                      |
| ----------- | ------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`        | String  | Optional          | Each `LwrConfigRouteDefinition` must have a unique `id` identifier.                                                                                                                                                                                                                                                                                                                                              |
| `uri`       | String  | Optional          | A pattern for URI locations that match the `LwrConfigRouteDefinition`. You can't use the `#` and `*` characters.                                                                                                                                                                                                                                                                                                 |
| `page`      |         | Required          | The form of page references that match the `LwrConfigRouteDefinition`. `page` values can be `:parameter` bindings, which map a path or query parameter from the URI to an `attributes` or `state` property, or literal bindings, which hard code a `type`, `attribute`, or `state` property to a literal value. Literal bindings can't contain the following characters: `?`, `*`, `#`, `&`, `+`, `;`, `(`, `)`. |
| `patterns`  |         | Optional          | A regular expression that a parameter has to match to be valid. To prevent unexpected values in the expression pattern, explicitly wrap the expression in the start-of-line character (`^`) and end-of-line character (`$`). For example: `{"patterns": {"parameter": "^id[0-9a-zA-Z]{5}$"}}`.                                                                                                                   |
| `exact`     | Boolean | Optional          | If there's a nested router, this value must be `false`. The default value is `true`.                                                                                                                                                                                                                                                                                                                             |
| `metadata`  |         | Optional          | Developer-defined metadata in the form of key (string) and value (any type) pairs. You can use the `metadata` property to attach additional information to an `LwrConfigRouteDefinition`. Extend `LwrConfigRouteDefinition` for required or more strongly typed metadata.                                                                                                                                        |
| `handler`   | String  | See description   | An `LwrConfigRouteDefinition` must contain a handler or a component, but not both. `handler` is a string reference to the `RouteHandler` class specifier.                                                                                                                                                                                                                                                        |
| `component` | String  | See description   | An `LwrConfigRouteDefinition` must contain a handler or a component, but not both. `component` is a string reference to the view component specifier. Use this property to directly specify the view component without authoring a route handler.                                                                                                                                                                |

## Example

```
{
    "id": "home",
    "uri": "/",
    "component": "examples/home",
    "page": {
        "type": "home"
    },
    "metadata": {
        "title": "Home"
    }
},
{
    "id": "namedPage",
    "uri": "/:pageName",
    "handler": "examples/namedPageHandler",
    "page": {
        "type": "namedPage",
        "attributes": {
            "pageName": ":pageName"
        }
    }
}
```

**See Also**

- [Routers and Route Matching: Route Definitions](https://developer.salesforce.com/docs/platform/lwr/guides/lwr-routers-route-matching.md#route-definitions)
- [Create a Router: Configure the Router JSON](https://developer.salesforce.com/docs/platform/lwr/guides/lwr-create-router.md#4-configure-the-router-json)

<!-- document id=0996f9406b8b05a5e0d3a8941b45d7b0ec980db51e3c86a7a56cfee80426d8b6 url=/developer/current/en-us/lwr-node/lwr/references/csr-reference/lwrrouterconfig.md -->

# LwrRouterConfig

**important:** To configure a router module with the [Router Module Provider](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-create-router.html#router-module-provider), you have to set up both `LwrRouterConfig` and `LwrConfigRouteDefinition`.

## Syntax

```
interface LwrRouterConfig {
    basePath?: string;
    caseSensitive?: boolean;
    routes: LwrConfigRouteDefinition[];
    i18n?: I18NRouterConfig;
}
```

## Properties

The `LwrRouterConfig` object, which is passed to the Router Module Provider, contains the same properties as [`RouterConfig`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/routerconfig.md), which is passed to [`createRouter()`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/createrouter.md).

| Property        | Type    | Required/Optional | Description                                                                                                                                                                                                          |
| --------------- | ------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `basePath`      | String  | Optional          | A path prefix applied to all URIs for the router. If no base path is provided, the default value is empty (" ").                                                                                                     |
| `caseSensitive` | Boolean | Optional          | If `true`, URIs are processed case sensitively. The default value is `false`.                                                                                                                                        |
| `routes`        | Array   | Required          | An array of `LwrConfigRouteDefinition` objects.                                                                                                                                                                      |
| `i18n`          | Array   | Optional          | An [`i18n`](https://developer.salesforce.com/docs/platform/lwc/guide/create-i18n.html) config that may affect the path prefix applied to all URIs. The default value is `{locale: 'en-US', defaultLocale: 'en-US'}`. |

## Example

```
{
    "caseSensitive": "true";        // URIs will be processed case sensitively
    "i18n": {                       // Sets custom locale
        "locale": "es",
        "defaultLocale": "es-MX"
    };
    "routes": [                     // Defines routes for two pages: home and namedPage
        {
            "id": "home",
            "uri": "/",
            "component": "examples/home",
            "page": {
                "type": "home"
            },
            "metadata": {
                "title": "Home"
            }
        },
        {
            "id": "namedPage",
            "uri": "/:pageName",
            "handler": "examples/namedPageHandler",
            "page": {
                "type": "namedPage",
                "attributes": {
                    "pageName": ":pageName"
                }
            }
        }
    ]
}
```

**See Also**

- [Routers and Route Matching: Router Configuration](https://developer.salesforce.com/docs/platform/lwr/guides/lwr-routers-route-matching.md#router-configuration)
- [Create a Router: Configure the Router JSON](https://developer.salesforce.com/docs/platform/lwr/guides/lwr-create-router.md#4-configure-the-router-json)

<!-- document id=a58596436616a1829d0c97310505a4b7314c5d16d03f22e4002a36ac9e07cc23 url=/developer/current/en-us/lwr-node/lwr/guides/lwr-module-providers.md -->

# Module Providers for Lightning Web Runtime on Node.js

**Module providers** locate and serve modules for your web app. Your project's LWR server contains a **module registry**, which maintains a list of available module providers and helps match **module requests** to a valid module provider.

All Lightning Web Runtime on Node.js (LWR-JS) apps automatically include [default module providers](#default-module-providers) that support common module types, like static file system modules and packaged Lightning web components (LWCs). If you want to use ECMAScript (ES) modules from other sources, you can [import a module provider](#import-a-module-provider) or [create a custom module provider](#create-a-custom-module-provider).

This flexibility ensures that your runtime is small for simple use cases, but LWR-JS can support more complex applications if needed.

## Default Module Providers

Your project automatically includes these module providers.

```
'@lwrjs/app-service/moduleProvider',  // Application Bootstrap Module Provider
'@lwrjs/router/module-provider',      // Router Module Provider
'@lwrjs/lwc-module-provider',         // LWC Module Provider
'@lwrjs/npm-module-provider',         // Node Package Manager (npm) Module Provider
'@lwrjs/module-registry/externals-module-provider'    //
```

### Application Bootstrap Module Provider

This module provider generates only the Application Bootstrap Module. You need it for your website to load correctly.

### Router Module Provider

The [Router Module Provider](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-create-router.md#router-module-provider) generates a router based on a static JSON file.

### LWC Module Provider

The LWC Module Provider locates and serves Lightning Web Components (LWC) modules for your app. LWCs are special instances of ES modules that extend the [`LightningElement`](https://developer.salesforce.com/docs/platform/lwc/guide/create-components-javascript.html#ui-component) class. They have to be processed by the LWC compiler before a module provider can serve them.

### npm Module Provider

This module provider locates and serves all of the Node Package Manager (npm) ES modules from your project's `node_modules` directories.

### Externals Module Provider

The LWR-JS Externals Module Provider creates module definitions based on the externals in your project's [bundle configuration (`bundleConfig`)](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-configure-project.md#configure-bundles).

## Import a Module Provider

With LWR-JS, you can add an existing module provider to your project. For example, the LWR [Label Module Provider](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-label-module-provider.md) exposes capabilities for scoped module label support (`@salesforce/label/*`). You can add this tooling to your application via the `@lwrjs/label-module-provider` npm package.

To add an optional module provider to your project, first install the package using `npm` on the command line interface (CLI). For example, this code installs the Label Module Provider.

```bash
npm install @lwrjs/label-module-provider
```

Then, add the module provider plugin to your `lwr.config.json` file. Remember to include the default module providers in the `moduleProviders` array. Here's how to add the Label Module Provider to your app's config file.

**important:** The `moduleProviders` array overwrites the default LWR array. You have to list **all** the module providers needed by your app, including the default LWR ones listed in [Default Module Providers](#default-module-providers).

```
{
  "moduleProviders": [
    "@lwrjs/label-module-provider",       // Optional provider
    "@lwrjs/app-service/moduleProvider",  // Default provider
    "@lwrjs/router/module-provider",      // Default provider
    "@lwrjs/lwc-module-provider",         // Default provider
    "@lwrjs/npm-module-provider",         // Default provider
    "@lwrjs/module-registry/externals-module-provider"    // Default provider
  ]
}
```

That configuration lets your application components statically import labels sourced from JSON files in your project’s `$rootDir/src/labels` directory, like this:

```javascript
import GREETING from "@salesforce/label/home.greeting";
```

### Optional Supported LWR-JS Module Providers

You can add these module providers to your LWR-JS project.

- [Label Module Provider](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-label-module-provider.md)

## Create a Custom Module Provider

If you want your app to use a custom module that can't be served by one of the default module providers, add a custom module provider to your project. You can create a custom ES provider or a [custom LWC provider](#create-a-custom-lwc-module-provider).

In this section, we'll walk through how to create and implement a custom ES provider. We can boil this process down into three steps.

1. Create the module provider.
2. Configure `getModuleEntry()` and `getModule()`.
3. Register the module provider.

### Create a Custom ES Module Provider

To create an ES module provider, implement the `ModuleProvider` LWR interface. You have to give the module provider a name, but the `version` property is optional.

```
import { ModuleProvider } from 'lwr';
export default class MyProvider implements ModuleProvider {
    name = 'echo-provider';
    private version = '1';
}
```

Save this file in your app's `src` folder. For example, the sample module provider `es-custom-provider` is nested in `src/services`.

```
build/
node_modules/
src/
  ├── modules/
  ├── services/
  │   ├── es-custom-provider.ts
  │   └── lwc-custom-provider.ts
  └── index.ts
lwr.config.json
package.json
```

### Configure `getModuleEntry()` and `getModule()`

Module providers rely on `getModuleEntry()` and `getModule()` to match module requests to module providers and help compile modules. You should customize these functions for your custom module provider.

#### `getModuleEntry()`

When your LWR server receives a request for a module – like someone loading a webpage – the module registry calls `getModuleEntry()` on all of its module providers. The first module provider to correctly handle this request is assigned to serve the requested module.

The module registry passes these two arguments into `getModuleEntry()`.

- A **module ID**, which contains the module's `specifier` (a unique ID value).
- `RuntimeParams`, a map of unique requirements for the requested page. For example, it could include a requirement for a specific `locale`.

The function returns a `ModuleEntry` object that contains information from a valid module provider and the module request.

You should customize the information in `ModuleEntry` based on your custom module provider and the module it serves.

- `id` - At a minimum, include the module's `specifier` and the module provider's `version`. If the module is locale-specific, include the `locale` value from `RuntimeParams`.
- `virtual` - If module code from your provider is generated from scratch, set this to `true`. If it's read off of a file system or another source, set this to `false`.
- `entry` - Set this to the module's filepath. If the module is virtual, ensure the path includes the `specifier`.
- `version` - Set this to the module provider's version.

Here's an example of a `ModuleEntry` object returned by a custom module provider.

```
import { AbstractModuleId, ModuleCompiled, ModuleEntry, ModuleProvider, RuntimeParams } from 'lwr';

export default class MyProvider implements ModuleProvider {
    async getModuleEntry(
        { specifier }: AbstractModuleId,
        runtimeParams: RuntimeParams = {},
    ): Promise<ModuleEntry | undefined> {
        if (specifier.startsWith('@my/')) {         // Module provider checks for the @my namespace
            return {
                id: `${specifier}|${this.version}`,
                virtual: true,
                entry: `<virtual>/${specifier}.js`,
                specifier,                          // Reuse the specifier passed into getModuleEntry()
                version: this.version,
            };
        }
    }
}
```

#### `getModule()`

When the module registry validates that a module provider can fulfill a module request, the registry calls `getModule()`. `getModule()` takes the same arguments as `getModuleEntry()`. It returns a `ModuleCompiled` object.

```
import { AbstractModuleId, ModuleCompiled, ModuleEntry, ModuleProvider, RuntimeParams } from 'lwr';
import { hashContent } from '@lwrjs/shared-utils';

// Return a generated ES code string
function generateModule(specifier: string): string {
    return `...`;
}

export default class MyProvider implements ModuleProvider {
    async getModule(
        { specifier, namespace, name }: AbstractModuleId,
        runtimeParams: RuntimeParams = {},
    ): Promise<ModuleCompiled | undefined> {
        // Retrieve the Module Entry
        const moduleEntry = await this.getModuleEntry({ specifier });
        if (!moduleEntry) {
            return;
        }

        // Generate code for the requested ES module
        const originalSource = generateModule(specifier);

        // Construct a Module object
        return {
            id: moduleEntry.id,
            specifier,
            namespace,
            name,
            version: this.version,
            originalSource,
            moduleEntry,
            ownHash: hashContent(originalSource),
            // Note: there is no need to compile this module
            // The module registry will compile ES code, if needed
            compiledSource: originalSource,
        };
    }
}
```

### Register a Custom Module Provider

To register a custom module provider, add it to your project's `lwr.config.json` file. Make sure that TypeScript has been transpiled into JavaScript.

```
{
    "moduleProviders": [
        "$rootDir/build/services/es-custom-provider.js",
        "$rootDir/build/services/lwc-custom-provider.ts",
        "@lwrjs/app-service/moduleProvider",
        "@lwrjs/lwc-module-provider",
        "@lwrjs/npm-module-provider"
    ]
}
```

**important:** The `moduleProviders` array overwrites the default LWR array. You have to list **all** the module providers needed by your app, including the default LWR ones listed in [Default Module Providers](#default-module-providers).

Alternatively, you can pass your configuration from `lwr.config.json` to a module provider constructor. The configuration can be any JSON object or primitive type.

```
{
    "moduleProviders": [
        [
            "$rootDir/build/services/provider-with-config.js",
            {
                "cache": true,
                "locales": ["en", "es", "de"]
            }
        ]
    ]
}
```

The configuration and `ProviderContext` (from the LWR server) are passed into the module provider constructor.

```
interface MyProviderOptions {
    cache?: boolean;
    locales?: string[];
}
export default class MyProvider implements ModuleProvider {
    constructor({ cache = true, locales = [] }: MyProviderOptions, context: ProviderContext) {
        // initialization
    }
}
```

## Create a Custom LWC Module Provider

LWCs are special instances of ES modules that extend the `LightningElement` class. Before a module provider serves LWCs, they have to be processed by the LWC compiler.

The easiest way to create a custom LWC module provider is to extend the `LwcModuleProvider` class from the package `@lwrjs/lwc-module-provider`.

To adapt the LWC module provider for your LWR app, override `getModuleEntry()` and `getModuleSource()`. The `getModule()` function of the superclass handles compilation of the LWC.

```
import path from 'path';
import LwcModuleProvider from '@lwrjs/lwc-module-provider'; // add to package.json dependencies
import {
    AbstractModuleId,
    FsModuleEntry,
    ModuleCompiled,
    ModuleEntry,
    ModuleProvider,
    ModuleSource,
} from 'lwr';
import { hashContent } from '@lwrjs/shared-utils';

// Return generated LWC code strings by file type: html, css or default js
function generateModule(specifier: string): string {
    const fileType = path.extname(specifier).substring(1);
    switch (fileType) {
        case 'html':
            return `<template><!-- HTML code --></template>`;
        case 'css':
            return `/* CSS code */`;
        default:
            // 'js'
            return `
import { LightningElement } from 'lwc';
export default class MyLwc extends LightningElement { /* LWC code */ }`;
    }
}

export default class MyLwcProvider extends LwcModuleProvider implements ModuleProvider {
    name = 'lwc-provider';
    private version = '1';

    async getModuleEntry({ specifier }: AbstractModuleId): Promise<FsModuleEntry | undefined> {
        if (canHandle(specifier)) {
            return {
                id: `${specifier}|${this.version}`,
                // Incoming specifiers may be html or css code
                // Ensure the entry file extension matches:
                entry: `<virtual>/${specifier}${path.extname(specifier) ? '' : '.js'}`,
                specifier,
                version: this.version,
            };
        }
    }

    getModuleSource(
        { name, namespace, specifier }: AbstractModuleId,
        moduleEntry: ModuleEntry,
    ): ModuleSource {
        const originalSource = generateModule(specifier);
        return {
            id: moduleEntry.id,
            specifier,
            namespace,
            name: name || specifier,
            version: moduleEntry.version,
            moduleEntry,
            ownHash: hashContent(originalSource),
            originalSource,
        };
    }

    // This method handles LWC compilation => let the superclass handle this processing
    // It calls `getModuleSource` under the covers
    async getModule(moduleId: AbstractModuleId): Promise<ModuleCompiled | undefined> {
        return super.getModule(moduleId);
    }
}
```

<!-- document id=def5ea9b975bbb225ebc424e85172bbffc93554f756a563488148c969d922096 url=/developer/current/en-us/lwr-node/lwr/references/csr-reference/navigate.md -->

# navigate()

Navigates to a page reference programmatically.

## Properties

| Method Input    | Type    | Required/Optional | Description                                                                                                                                                                                      |
| --------------- | ------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `context`       | String  | Required          | The ID of the parent router container nearest to the component that's generating a URL. A `ContextId` is an opaque value that you get from the [`NavigationContext`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/navigationcontext.md) wire. |
| `pageReference` | String  | Required          | The [`PageReference`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/pagereference.md) value for which to generate a URL.                                                                                                                       |
| `replace`       | Boolean | Optional          | If set to `true`, `navigate()` replaces the current history entry with the location passed in the method parameters.                                                                             |

## Syntax

```javascript
import { LightningElement, api, wire } from 'lwc';
import { NavigationContext, navigate } from 'lwr/navigation';
import type { ContextId, PageReference } from 'lwr/navigation';

navigate(
    context: ContextId,
    pageReference: PageReference,
    replace?: boolean
    ): void
```

## Returns

- None

**See Also**

- [Simple Client-Side Routing: Navigate](https://developer.salesforce.com/docs/platform/lwr/guides/lwr-routing-example-simple.md#navigate)

<!-- document id=0239ba80609fec86348a8edc4ec8b9d2d270e54650a4449d088ef0df8041da38 url=/developer/current/en-us/lwr-node/lwr/references/csr-reference/navigationcontext.md -->

# NavigationContext

Gets a reference to a Lightning web component's navigation context (its closest ancestor router container) for use with the [`generateUrl()`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/generateurl.md) and [`navigate()`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/navigate.md) APIs.

## Properties

None

## Syntax

```javascript
import { LightningElement, wire } from "lwc";
import { NavigationContext } from "lwr/navigation";

export default class Example extends LightningElement {
  @wire(NavigationContext)
  property;
}
```

## Returns

- A `ContextId`, which is an opaque ID for the parent router container nearest to the component.

## Example

```javascript
import { LightningElement, wire } from 'lwc';
import { NavigationContext, navigate } from 'lwr/navigation';

export default class HomeLink extends LightningElement {
    // Use the NavigationContext wire to obtain a Context Id value and assign it to the navContext property
    @wire(NavigationContext)
    navContext;

    navigateHome(event) {
        // Navigate when the button is clicked
        event.preventDefault();
        // The navigate() API uses the ContextId value
        if (this.navContext) {
            navigate(this.navContext, {
                type: 'home',
                attributes: { format: 'list' },
                state: { dark-mode: 'true' },
            });
        }
    }
}
```

```html
<template>
  <button onclick="{navigateHome}">Home</button>
</template>
```

**See Also**

- [Simple Routing Example: Navigate](https://developer.salesforce.com/docs/platform/lwr/guides/lwr-routing-example-simple.md#navigate)

<!-- document id=7ee3064dd6d18fa0b5610729ab21179e0e6d0ed554a8c803d6cf746ab9caefc8 url=/developer/current/en-us/lwr-node/lwr/references/csr-reference/navigationmixin.md -->

# NavigationMixin

You can use `NavigationMixin` instead of the `navigate()` and `generateUrl()` APIs. Both options offer the same functionality, but only `NavigationMixin` is compatible with Lightning Experience. If you're writing a component for use in both LWR and Lightning Experience, choose `NavigationMixin`.

## Syntax

```javascript
import { LightningElement } from "lwc";
import { NavigationMixin } from "lightning/navigation";

const pageRef = {
  type: "standard__recordPage",
  attributes: {
    recordId: "001xx000003DGg0AAG",
    objectApiName: "Account",
    actionName: "view",
  },
};

export default class Example extends NavigationMixin(LightningElement) {
  // Navigate to a page reference
  navPageRef() {
    this[NavigationMixin.Navigate](pageRef);
  }
  // Generate a URL for a page reference
  getUrl() {
    this[NavigationMixin.GenerateUrl](pageRef).then((url) => console.log(url));
  }
}
```

**See Also**

- [Component Reference (Lightning Web Components): lightning-navigation](https://developer.salesforce.com/docs/component-library/bundle/lightning-navigation/documentation)
- [Understand Client-Side Routing: Lightning Navigation](https://developer.salesforce.com/docs/platform/lwr/guides/lwr-outlets.md#lightning-navigation)

<!-- document id=566ac68b20f2b5b7f5963ff58813e74e2824eca8036fecee38a595981142c9c0 url=/developer/current/en-us/lwr-node/lwr/references/csr-reference/new.md -->

# new()

Creates a route handler module.

**note:** [Route handler **modules**](https://developer.salesforce.com/docs/platform/lwr/guides/lwr-route-handler-modules.md), which are used in client-side routing, aren’t the same as [route handler **functions**](https://developer.salesforce.com/docs/platform/lwr/guides/lwr-routing-server.md#route-handler-functions), which are used in server-side routing.

## Properties

| Method Input | Type                            | Required/Optional | Description                                                                                                                                                                                                                                                                                      |
| ------------ | ------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `callback`   | `RouteHandlerCallback` function | Required          | A reference to a route handler callback. Each `RouteHandlerCallback` takes a [`RouteDestination`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/routedestination.md) object. Make sure to save the reference to this callback. [`RouteHandler.update`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/update.md) invokes the callback to return the `ViewSet` for a given `RouteDestination`. |

## Syntax

```javascript
constructor(callback: RouteHandlerCallback) {
        this.callback = callback; // Important: maintain a reference to the callback
    }
```

## Signature

```javascript
public void new(callback: RouteHandlerCallback)
```

## Returns

- None

**See Also**

- [Route Handler Modules](https://developer.salesforce.com/docs/platform/lwr/guides/lwr-route-handler-modules.md#new)
- [Simple Routing Example: Create a Route Handler](https://developer.salesforce.com/docs/platform/lwr/guides/lwr-routing-example-simple.md#create-a-route-handler)

<!-- document id=87cfbf355f8a4a4aa3236d5c7ca99ed9f43dd0ed1968b22521c5c8f592cf4210 url=/developer/current/en-us/lwr-node/lwr/guides/lwr-outlets.md -->

# Outlets

An **outlet** dynamically renders view components. A view is the component to display when the application navigates to a location.

This process is naturally lazy: the view isn't imported until the outlet consumes it, so any unused views aren't fetched. When the router's view state changes, the outlet is flagged to display the view. Then, if the view module hasn't already been fetched, there may be an asynchronous process to retrieve it.

```
<template>
    <lwr-router-container>
        <lwr-outlet refocus-off onviewchange={onViewChange} onviewerror={onViewError}>
            <div slot="error">View component cannot display</div>
        </lwr-outlet>
    </lwr-router-container>
</template>
```

A route handler module can return multiple views.

```
import type { Module, RouteHandlerCallback } from "lwr/router";

export default class HomeHandler {
  callback: RouteHandlerCallback;

  constructor(callback: RouteHandlerCallback) {
    this.callback = callback;
  }

  dispose(): void {}

  update(): void {
    this.callback({
      viewset: {
        // return multiple views
        default: (): Promise<Module> => import("my/home"),
        nav: (): Promise<Module> => import("my/homeNav"),
        footer: (): Promise<Module> => import("my/homeInfo"),
      },
    });
  }
}
```

You can use multiple outlets to display all the current view components by setting different `view-name` values:

```
<template>
  <lwr-router-container>
    <lwr-outlet view-name="nav"></lwr-outlet>
    <lwr-outlet><!-- default view --></lwr-outlet>
    <lwr-outlet view-name="footer"></lwr-outlet>
  </lwr-router-container>
</template>
```

## Lightning Navigation

The `@lwrjs/router` package provides an implementation of `lightning/navigation`. The `lightning/navigation` module is an alias for the `lwr/navigation` module, so it includes the same [wires](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/lwr-navigation-wires.html) and APIs, along with [`NavigationMixin`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/navigationmixin.html). This allows you to write a component once and use it anywhere that supports the `lightning/navigation` contracts.

<!-- document id=caf1502aea4235b6c54fbf100c5eed92adefb58ac32ab5a9e430297bd45dc7ab url=/developer/current/en-us/lwr-node/lwr/references/packages-reference.md -->

# Packages and Modules

In this section, you can review specification docs for these LWR on Node.js packages and modules.

- [@lwrjs/security](https://developer.salesforce.com/docs/platform/lwr/references/packages-reference/packages-reference/lwrjs-security.md)

<!-- document id=f6b6178d08e885cfc993eba532840f4c4d1b8b037ae63da504879349160e5448 url=/developer/current/en-us/lwr-node/lwr/guides/lwr-packages-modules.md -->

# Packages and Modules in LWR on Node.js

Do you want to add dependencies to your project? What about customizing module support for your Lightning Web Runtime (LWR) on Node.js app? Read on to discover how.

You can also check out the [Configure Your Project](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-configure-project.md) page for other configuration options.

## Key Terms

**Package** - A set of files that provides a functionality or feature that you can add to your project. For LWR on Node.js projects, you can add packages using package manager toolchains like npm and Yarn.

**Module** - After you install a package, the resulting set of copied files inside your project is called a module. All of your modules are stored in the `node_modules` folder.

**note:** Lightning Web Runtime (LWR) on Node.js supports only ECMAScript (ES) and Lightning Web Components (LWC) modules.

**Dependency** - A reference to a **package** in your project's `package.json` file. Each reference tells your project which version of a package to install.

## Add Modules and Dependencies

Your [Quick Start project’s](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-get-started.md) `package.json` file looks something like this, with both the `lwr` and the `lwc` packages included as dependencies. When you install a package in your project, the project automatically gets added as a dependency in `package.json`.

```
{
  "name": "staticsite",
  "version": "0.0.1",
  "license": "MIT",
  "private": true,
  "type": "module",
  "scripts": {
    "clean": "rm -rf __lwr_cache__",
    "dev": "node scripts/start-server.mjs",
    "start": "MODE=prod node scripts/start-server.mjs",
    "start:amd": "MODE=compat node scripts/start-server.mjs"
  },
  "dependencies": {
    "lwc": "^2.2.0",
    "lwr": "^0.4.4"
  },
  "engines": {
    "node": ">=14.15.4 <15"
  }
}
```

LWR projects are standard npm packages, so you can add other project dependencies with typical package manager toolchains such as NPM or Yarn. (The examples that follow use npm, but the general guidance applies equally.)

For example, running the following code on the command line interface (CLI) installs the `best-library-ever` package.

```bash
npm install best-library-ever
```

After you run that command, your project's `package.json` file changes to include a dependency on the new `best-library-ever` module.

```
"dependencies": {
    "best-library-ever": "{version number}",
    "lwc": "^2.2.0",
    "lwr": "^0.4.4"
  },
```

Finally, you can import the module in your component source code and use it.

```
import { camelCase } from 'best-library-ever';
const componentName = camelCase("Component Name");
```

## Add a Lightning Web Components Dependency

Adding a Lightning Web Components (LWC) package as a dependency to your project is different than the general case described in [Manage Project Dependencies](#add-modules-and-dependencies).

**tip:** LWC packages are Lightning web components that someone else created and made distributable for reuse. If you’re curious about including an LWC package in your project, search the [npm package registry](https://www.npmjs.com/) for “LWC” or “Lightning Web Components” and discover what’s on offer. If you're interested in distributing your own Lightning web components, check out [Package and Distribute LWC OSS Components (video)](https://www.youtube.com/watch?v=uPmY14n7Xe8) or [Distribute Your Component Using npm](https://lwc.dev/guide/es_modules#distribute-your-component-using-npm).

To add an LWC package to your project use `npm` to install the module.

```bash
npm install lightning-base-components
```

When you run that command, npm adds a dependency on the module to your `package.json` file.

```
{
  "dependencies": {
    "lightning-base-components": "^1.9.0-alpha",
    "lwc": "^2.2.0",
    "lwr": "^0.4.4"
  }
}
```

Next, you have to add a directory module record to your LWC configuration in `lwr.config.json`. If you don't complete this step, your LWC module won't work as expected.

```
{
  "lwc": {
    "modules": [{ "dir": "$rootDir/src/modules" }, { "npm": "lightning-base-components" }]
  }
}
```

The [LWC documentation](https://github.com/salesforce/lwc/tree/master/packages/%40lwc/module-resolver#module-resolution) has more details on how LWC module resolution works, as does [this blog post](https://developer.salesforce.com/blogs/2020/09/lightning-web-components-module-resolution).

## Specify Module Records

You can add module records to `lwr.config.json` from any of these sources:

- **Alias module record**: A file path where a module can be resolved.
- **Directory module record**: A folder path where modules can be resolved.
- **npm package module record**: An npm package that exposes one or more modules.

Here's an example of module records in a config file. The order of the array matters. LWR iterates through the modules array and uses the first module that matches the requested module specifier.

```
{
  "lwc": {
    "modules": [
      {
        "name": "ui/button",
        "path": "src/modules/ui/button/button.js"
      },
      {
        "dir": "$rootDir/src/modules"
      },
      {
        "npm": "lightning-base-components"
      }
    ]
  }
}
```

## Next Steps

Modules are located and served by **module providers**. Your project's LWR server contains a **module registry**, which maintains a list of available module providers and helps match **module requests** to the appropriate module provider.

To learn more about how to create and use module providers, read [Module Providers for Lightning Web Runtime on Node.js](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-module-providers.md).

<!-- document id=289453225853a7ba9ad1e4ce30c53383f4370266a8cc8e8a65ebee778bfb1aad url=/developer/current/en-us/lwr-node/lwr/references/csr-reference/pagereference.md -->

# PageReference

An LWR router receives navigation events as page references. Page references are a JSON-format specification of a location. You pass a `PageReference` object to the router via the [`navigate` API](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/navigate.md).

## Syntax

```
interface PageReference {
  type: string;
  attributes: { [key: string]: string | null };
  state: { [key: string]: string | null };
}
```

## Properties

| Property     | Type   | Required/Optional | Description                                                                                              |
| ------------ | ------ | ----------------- | -------------------------------------------------------------------------------------------------------- |
| `type`       | string | Required          | An identifier that's a user-defined expression.                                                          |
| `attributes` | array  | Required          | An array of user-defined key-value pairs. If there are no attribute values, set this property to `null`. |
| `state`      | array  | Required          | An array of user-defined key-value pairs. If there are no attribute values, set this property to `null`. |

## Example

```
// URI
https://www.somewhere.com/animals/abc?view=compact&dark-mode

// page reference
{
    "type": "animal_page",
    "attributes": {
        "animalId": "abc"
    },
    "state": {
        "view": "compact",
        "dark-mode": ""
    }
}
```

**See Also**

- [Route Handler Modules](https://developer.salesforce.com/docs/platform/lwr/guides/lwr-route-handler-modules.md#3-the-router-passes-routeinstance-to-routehandlerupdate)
- [Simple Routing Example: Navigate](/docs/platform/lwr/guide/lwr-routing-example-simple.html#navigate)

<!-- document id=e04fb0c8c0e7f43ca72f0e086fa2edee66cf6e8e8cae010f7bd9d66075f69605 url=/developer/current/en-us/lwr-node/lwr/guides/lwr-configure-project.md -->

# Project Configuration in LWR on Node.js

LWR is built with customization and extensibility in mind.

You can customize both the server configuration and project setup for your LWR project. The LWR server is configured in `lwr.config.json`, at the root of the project. This page describes various `lwr.config.json` configuration options.

For other configuration options, such as adding dependencies to your project or customizing LWR’s module support, check out [Configure Packages and Modules](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-packages-modules.md).

## Understand lwr.config.json

The `lwr.config.json` file generated for your [initial StaticSite project](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-get-started.md) only has a few things happening:

- It provides a [module source directory](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-packages-modules.md#options-for-specifying-module-records) for LWC modules in your project repo.
- It specifies how to handle the [bundling](#configure-bundles) of the `lwc` module.
- It tells LWR how to [route](#configure-routes) to some pages.

```json
{
  "lwc": { "modules": [{ "dir": "$rootDir/src/modules" }] },
  "bundleConfig": { "exclude": ["lwc"] },
  "routes": [
    {
      "id": "Home",
      "path": "/",
      "contentTemplate": "$contentDir/home.md",
      "layoutTemplate": "$layoutsDir/main_layout.njk"
    },
    {
      "id": "About",
      "path": "/about",
      "contentTemplate": "$contentDir/about.md",
      "layoutTemplate": "$layoutsDir/main_layout.njk"
    },
    {
      "id": "Explore",
      "path": "/explore",
      "contentTemplate": "$contentDir/explore.md",
      "layoutTemplate": "$layoutsDir/main_layout.njk"
    }
  ]
}
```

You can do more with the lwr.config.json file, however. You can also [configure directory locations](#configure-directory-locations-and-lightning-web-security) of templates, global context data, and static assets, as well as set the [port, server type, and server mode](#configure-the-port-and-server).

## Configure Routes

Page routing for LWR projects is controlled in the `lwr.config.json` configuration file. This topic is covered in detail on the [Server-Side Routing in LWR page](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-routing-server.md).

## Configure the Port and Server

You can use `lwr.config.json` to access some LWR port and server configurations:

- `port`: The port from which to serve the LWR application. The default is `process.env.PORT || 3000`.
- `serverMode`: The mode in which to run the server. Mode is typically set on the [command line](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-get-started.md#set-the-lwr-server-modes). The default is `"dev"`. See available modes [here](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-get-started.md#set-the-lwr-server-modes).
- `serverType`: The type of underlying web server that LWR uses. Currently supported values are `"express"` (default) or `"koa"`.

For example:

```
{
    "port": 3333,
    "serverMode": "prod",
    "serverType": "express"
}
```

## Configure Directory Locations and Lightning Web Security

You can configure a variety of directory locations in your `lwr.config.json` file:

- `rootDir`: The root directory of the LWR project. The default is the current working directory (`.`).
- `cacheDir`: LWR caches LWC modules that it has compiled and stores them in a cache directory. The default is `"$rootDir/__lwr_cache__"`.
- `contentDir`: The content templates directory. The default is `"$rootDir/src/content"`.
- `layoutsDir`: The layout templates directory. The default is `"$rootDir/src/layouts"`.
- `globalDataDir`: The directory of [global data](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-compile-data.html#global-data) for templating. The default is `"$rootDir/src/data"`.
- `hooks`: A list of configuration hooks that you can use to dynamically alter the configuration and global data for your application on server startup. Hooks are an advanced topic and are not covered in detail at this point.
- `locker`: Allows you to enable [Lightning Web Security](https://developer.salesforce.com/docs/component-library/documentation/en/lwc/lwc.security_lwsec_intro) and optionally configure a list of trusted components. By default, Lightning Web Security (LWS) is disabled. If LWS is on, components from LWC and LWR are automatically trusted.

**note:** The `locker` key actually configures LWS, not Lightning Locker. This setting is independent of the LWS setting that can be enabled for an org.

For example:

```
{
    "rootDir": "/Users/me/lwr/projects/awesome",
    "cacheDir": "$rootDir/build/cache",
    "contentDir": "$rootDir/templates",
    "layoutsDir": "$rootDir",
    "globalDataDir": "$rootDir/src/templateContext",
    "hooks": ["$rootDir/src/hooks/docs-app-hooks.js"],
    "locker": {
        "enabled": true,
        "trustedComponents": ["my/trustedCmp"]
    }
}
```

You can also configure directories to serve static assets. For more information, see [Template and Asset References](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-templates.md#template-and-asset-references) in [LWR Content and Layout Templates](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-templates.md).

## Configure Bundles

If a recipe is running in `prod` or `prod-compat` [mode](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-get-started.md#set-the-lwr-server-modes), LWR bundles modules before sending them to the client. Depending on your project setup, the same module dependency can get pulled into more than one bundle. This doesn't cause a problem for most modules, but some must be treated as singletons.

Examples of such modules are `lwc`, `lwr/navigation`, and `@lwc/synthetic-shadow`. The solution is to put these modules in their own, shareable bundles. In the `lwr.config.json` file, `bundleConfig.exclude` excludes the module from bundling when modules are requested. If your application contains additional singleton modules, exclude them from bundling as well:

```
{
    "bundleConfig": {
        "exclude": ["my/singleton", "do/notBundle"]
    }
}
```

<!-- document id=675f1a165ec9ae81c3da7436751e2433d1f31380c3073a231ca13eb4eda42e7c url=/developer/current/en-us/lwr-node/lwr/guides/lwr-get-started.md -->

# Quick Start: LWR on Node.js

New to LWR? Let's walk through how to build a simple static website in your local environment using LWR on Node.js.

## Install Node

[Node.js](https://nodejs.org/en/) is a free, open source tool that lets you run and develop JavaScript applications. Using LWR **on** Node.js means running LWR inside a Node.js runtime.

Applications developed using Node.js are cross-platform compatible, so they're supported by multiple operating systems (like MacOS, Windows, and Linux). Node.js developers can use JavaScript for both frontend and backend development.

Before you can start your first LWR on Node.js project, [install the latest recommended version of Node.js](https://nodejs.org/).

1. Click the `[Version Number] LTS` button to start downloading Node.js. The button should also say `Recommended For Most Users`.
2. To start the installation process, open your Downloads folder and click the `node-VersionNumber` file (for Windows users) or package (for Mac users) that you just downloaded.

## Create Your First Project

Node.js gives you access to a huge database of packages that you can install in your applications. For this project, you'll use the Node Package Manager (NPM) to set up a simple site template from the `create-lwr` package. Don't worry about how to set up NPM! When you installed Node.js on your computer earlier, you also installed NPM.

Let's review the basics of NPM:

- A **package** is a directory of files.
- A **module** is a JavaScript file inside of a package.
- To install a package in an application, run an `npm` command in a terminal program.
- Some developers use `yarn` commands instead to install packages. We're only going to use `npm` commands because you already have it installed on your machine.

Now you're ready to use NPM to create this project.

**important:** If you previously installed `create-lwr` globally, first uninstall the package by running `npm uninstall -g create-lwr` or `yarn global remove create-lwr`, then complete the following steps. For more information about this package, see [NPM: create-lwr](https://www.npmjs.com/package/create-lwr).

1. In a terminal program, run `npm init lwr@latest`
2. For **Project name**, enter _StaticSite_.
3. Accept the generated package name by pressing the **Enter** key.
4. For **Select a type of project**, accept the default, _Static Site_.
5. For **Select a variant**, accept the default, _Markdown Static Site_.

Just like that, you've scaffolded your first project!

Now, run these three commands to start a live preview of your new site.

```bash
cd StaticSite
npm install
npm run dev
```

You can see your live site preview in your browser on your [localhost](http://localhost:3000/).

![Static Site output](https://developer.salesforce.com/docs/media/static-site-output.png)

**tip:** Want to explore all of the packages that you can install in a Node.js project? Check out the [NPM Registry](https://www.npmjs.com/) to explore free and paid libraries for your applications.

### Installing vs Initializing a Package

Did you notice that the `create-lwr` package page says you can **install** `create-lwr` by running `npm i create-lwr` in your terminal? Installing and initializing a package are two different actions.
| `npm i package-name` | `npm init package-name`|
|---------|----------|
| This command **installs** a package. | This command **initializes** a package. |
| Running `npm i create-lwr` only installs the `create-lwr` package on your machine. To create the LWR sample site from that package, you have to run `create-lwr` in your terminal afterward. |We recommend scaffolding your project with the `npm init lwr@latest` command because it installs and creates the `create-lwr` sample project in one step.|

If you're wondering exactly what the `npm init lwr@latest` command does, let's break it down:

- `npm init` tells your machine to initialize a new project. It also creates a new package.json file inside of your project directory. This is an important file that handles information about dependencies (like packages) for your project.
- `lwr` is the package you're telling NPM to initialize. This package scaffolds a sample site from the `create-lwr` package.
- The `@latest` suffix tells NPM to install the latest version of the package.

## Deploy to Heroku

Are you a [Heroku developer](https://devcenter.heroku.com/)? Now that you have your static site up and running, deploying to Heroku is a breeze. Heroku uses [the preset start script](https://devcenter.heroku.com/articles/node-best-practices#hook-things-up) in your project's `package.json` file, and LWR serves the app on Heroku in the same way as it does locally. See [Deploying with Git](https://devcenter.heroku.com/articles/git#deploy-your-code) or the [Deployment](https://devcenter.heroku.com/categories/deployment) category in the Heroku Dev Center for more deployment options.

## Set the LWR Server Modes

If you're getting the idea that LWR projects are standard NPM packages, you're right. You can use commands with LWR from typical package manager toolchains like NPM.

**tip:** If you run into errors or have a stale project, try the command `npm run clean`. It removes the build directory and file cache.

For example, using [NPM](https://npmjs.com/), you can run your LWR application in several different modes.

| MODE        | Start Command                      | Module Format | File Watch | Bundling | Minification |
| ----------- | ---------------------------------- | ------------- | ---------- | -------- | ------------ |
| dev         | `npm run dev`                      | ESM           | ✅         | 🚫       | 🚫           |
| prod        | `npm run start`                    | ESM           | 🚫         | ✅       | ✅           |
| compat      | `npm run dev --mode compat`        | AMD           | ✅         | 🚫       | 🚫           |
| prod-compat | `npm run start --mode prod-compat` | AMD           | 🚫         | ✅       | ✅           |

**dev**

Running LWR in `dev` mode uses hot module reloading for easier debugging, so when you change a component in one place it updates immediately. In `dev` mode, the server registers all file paths and watches them individually.

**prod**

When you run in `prod` mode, [LWR bundles](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-configure-project.md#configure-bundles) modules before sending them to the client. This bundling reduces the number of HTTP requests to the server.

**compat**

By default, the LWR server formats modules in the [ECMAScript format](https://nodejs.org/api/esm.html#modules-ecmascript-modules) or “ESM”. However, some browsers don't support ESM semantics. When you run your application in `compat` mode, LWR uses a custom module loader, and the modules are formatted as [AMD-compliant](https://en.wikipedia.org/wiki/Asynchronous_module_definition) JavaScript resources.

**prod-compat**

A production version of compatibility mode. For `prod-compat`, as with `prod` mode, LWR uses [bundling](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-configure-project.md#configure-bundles) and minification for efficiency. And, as in `compat` mode, modules are formatted as [AMD-compliant](https://en.wikipedia.org/wiki/Asynchronous_module_definition) resources. |

## It's Simple to Be Sophisticated

LWR is built with customization and extensibility in mind. You can use LWR for everything from static sites to SPAs (single page applications).

Ready to get going? Before we move on, let's review some of the key files in the static site project you just built and their capabilities:

- `lwr.config.json`: With this file you have a variety of options for project configuration, including routing, directory locations, and server configuration. Find out more in [Configure Your LWR Project.](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-configure-project.md)
- `package.json`: Here you can add dependencies to your project or customize LWR’s module support. Check out [Configure Packages and Modules](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-packages-modules.md) for more details.
- `src/layouts/main_layout.njk`: The scaffolding for your static site contains a website layout using the [Nunjucks](https://mozilla.github.io/nunjucks/templating.html) templating language. Learn about [LWR layouts and templating.](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-templates.md)
- `src/content`: The site is using [Markdown](https://daringfireball.net/projects/markdown/) syntax for the content templates for the **Home** and **About** pages. Markdown is easy and fast to use and read, and there are many resources and cheatsheets available.

**tip:** LWR supports the following languages for templating:

- [HTML](https://en.wikipedia.org/wiki/HTML)
- [Markdown](https://www.markdownguide.org/)
- [Nunjucks](https://mozilla.github.io/nunjucks/)

## Next Steps

We hope that your static site gives you a glimpse of the simplicity and flexibility of LWR. Want to do more? You can start by reading up on [LWR content and layout templates](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-templates.md) and [routing](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-routing.md).

<!-- document id=242cac76857ce2ab6fca4bfe469ebb1c81eb4bd0e7d26889eb0efe5c487dda0d url=/developer/current/en-us/lwr-node/lwr/guides/lwr-route-handler-modules.md -->

# Route Handler Modules

After a router confirms that an incoming location change matches a route definition, what happens next?

The router accesses `RouteDefinition.handler` to determine the associated **view**, or the component that displays when the application navigates to a location. A `RouteHandler` module uses its `update()` function to provide the router with the right view to display.

Let's break down this process in detail.

**note:** Route handler **modules**, which are used in client-side routing, aren’t the same as [route handler **functions**](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-routing-server.md#route-handler-functions), which are used in server-side routing.

## Call RouteDefinition.handler

After a router validates an incoming location change, it accesses the `handler` property of the corresponding route definition to determine the new view.

[`RouteDefinition.handler`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/routedefinition.html) contains a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) for the `RouteHandler` module. In LWR, route handler modules are always provided via promises. Promises allow the module code to be lazily loaded, which improves application performance.

## Create RouteHandler module

Then, the router uses the `new()` method to create a RouteHandler module. The route handler is active upon construction, and it can immediately pass results to the callback via the `update()` method.

### new()

[`new()`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/new.html) takes a reference to a route handler callback (`RouteHandlerCallback`).

```
public void new(callback: RouteHandlerCallback)
```

### RouteHandlerCallback and RouteDestination

`RouteHandlerCallback` contains a route destination object ([`RouteDestination`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/routedestination.html)). `RouteDestination` contains a [`ViewSet`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/routedestination.html#viewset) object that specifies the view to display.

```
type RouteHandlerCallback = (routeDestination: RouteDestination) => void;
```

![Diagram showing input and output for `new()`.](https://developer.salesforce.com/docs/media/method-new.png '{"class": "image-lg"}')

It's important to maintain a reference to the callback in the RouteHandler module, like this:

```
export default class RecipeHandler {
    callback: RouteHandlerCallback;   // Callback for the route handler module RecipeHandler

    constructor(callback: RouteHandlerCallback) {
        this.callback = callback;     // Important: maintain a reference to the callback
    }
}
```

## Pass RouteInstance to RouteHandler.update()

Finally, `RouteHandler.update()` takes `RouteInstance` and returns view component information via a callback from the `update` function. This changes what the user sees in the browser.

[`RouteInstance`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/routeinstance.html) contains information about a location ([`PageReference`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/pagereference.html)). It tells the route handler which view to show the user.

```
interface RouteInstance {
    // location information passed to `RouteHandler.update()`
    id: string; // RouteDefinition.id
    attributes: { [key: string]: string | null };
    state: { [key: string]: string | null };
    pageReference: PageReference;
}
```

### update()

The [`update()`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/update.html) method accepts a `RouteInstance` object.

`update()` invokes the `RouteHandlerCallback` from `RouteHandler.new` to return the `ViewSet` that corresponds to the callback's `RouteDestination`.

![Diagram showing input and output for `update()`.](https://developer.salesforce.com/docs/media/method-update.png '{"class": "image-lg"}')

## RouteHandler Example

`recipeHandler` below is an example of a `RouteHandler` module.

```
import type { Module, RouteHandlerCallback } from "lwr/router";

export default class RecipeHandler {
  callback: RouteHandlerCallback;

  // Create new RouteHandler module via callback
  constructor(callback: RouteHandlerCallback) {
    this.callback = callback; // Important: maintain a reference to the callback
  }

  // Implementation of dispose()
  dispose(): void {
    // perform cleanup tasks
  }

  // Implementation of update()
  update(routeInfo: RouteInstance): void {
    // called every time a RouteDefinition with this handler matches a location during processing
    const {
      attributes: { cat }, // location information
    } = routeInfo;
    const category = cat || "entree"; // cat may be null
    const viewSpecifier = `my/${category}Recipe`; // e.g. "my/dessertRecipe"
    this.callback({
      viewset: {
        // return view component info based on the recipe's category
        default: {
          module: (): Promise<Module> => import(viewSpecifier),
          specifier: viewSpecifier,
        },
      },
    });
  }
}
```

[Simple Client-Side Routing](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-routing-example-simple.md) includes examples of additional route definition handlers, including for branching logic.

### dispose()

[`RouteHandler.dispose`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/dispose.html) is called when a route handler is no longer needed by the app and no longer emits view changes. A disposed route handler can't be used again.

## Next Steps

To use a router in your app, you have to attach it to the DOM with a router container. To learn how, check out [Router Containers](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-router-containers.md).

<!-- document id=23adc0daf779d40680cccdcc832dbc0f29232a8684d3aad085ab6a5491019221 url=/developer/current/en-us/lwr-node/lwr/references/csr-reference/routedefinition.md -->

# RouteDefinition

[`createRouter()`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/createrouter.md) takes a [`RouterConfig`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/routerconfig.md) object. `RouterConfig` has to contain an array of `RouteDefinition` objects.

## Syntax

```javascript
interface RouteDefinition<TMetadata = Record<string, any>> {
    id: string;
    uri: string;
    page: Partial<PageReference>
    handler: () => Promise<{ default: RouteHandler }>
    patterns?: { [paramName: string]: string };
    exact?: boolean;
    metadata?: TMetadata;
}
```

## Properties

| Property   | Type    | Required/Optional | Description                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ---------- | ------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`       | String  | Required          | Each `RouteDefinition` has to have a unique identifier.                                                                                                                                                                                                                                                                                                                                                                                         |
| `uri`      | String  |                   | A string pattern for URI locations that match this `RouteDefinition`. You can use the following characters: `/`, `:parameter`, `?`, `&`. You can't use `#` or `*`.                                                                                                                                                                                                                                                                              |
| `page`     |         |                   | The form of page references that match the [`LwrConfigRouteDefinition`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/lwrconfigroutedefinition.md). `page` values can be `:parameter` bindings, which map a path or query parameter from the URI to an `attributes` or `state` property, or literal bindings, which hard code a `type`, `attribute`, or `state` property to a literal value. Literal bindings can't contain the following characters: `?`, `*`, `#`, `&`, `+`, `;`, `(`, `)`. |
| `handler`  | String  | Optional          | A promise to a module that's called when a `RouteDefinition` matches a location. For more information, see [Route Handler Modules](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-route-handler-modules.html).                                                                                                                                                                                                                    |
| `patterns` |         | Optional          | A regular expression that a parameter has to match to be valid. To prevent unexpected values in the expression pattern, explicitly wrap the expression in the start-of-line character (`^`) and end-of-line character (`$`). For example: `{"patterns": {"parameter": "^id[0-9a-zA-Z]{5}$"}}`.                                                                                                                                                  |
| `exact`    | Boolean | Optional          | If there's a nested router, this value must be `false`. The default value is `true`.                                                                                                                                                                                                                                                                                                                                                            |
| `metadata` |         | Optional          | Developer-defined metadata in the form of key (string) and value (any type) pairs. You can use the `metadata` property to attach additional information to an [`LwrConfigRouteDefinition`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/lwrconfigroutedefinition.md). Extend `LwrConfigRouteDefinition` for required or more strongly typed metadata.                                                                                                                                        |

## Example

```
{
    id: 'namedPage',
    uri: '/:pageName',
    handler: () => import('example/namedPageHandler'),
    page: {
        type: 'namedPage',
        attributes: {
            pageName: ':pageName',
        },
    },
}
```

**See Also**

- [Routers and Route Matching: Route Definitions](https://developer.salesforce.com/docs/platform/lwr/guides/lwr-routers-route-matching.md#route-definitions)
- [Create a Router: Configure createRouter()](https://developer.salesforce.com/docs/platform/lwr/guides/lwr-create-router.md#2-configure-createrouter)
- [Route Handler Modules](https://developer.salesforce.com/docs/platform/lwr/guides/lwr-route-handler-modules.md#1-the-router-calls-routedefinitionhandler)

<!-- document id=aa6c38fe20d47a50b41fa0bb4892a7e5f838e52afc76bb57e49b537f4168a315 url=/developer/current/en-us/lwr-node/lwr/references/csr-reference/routedestination.md -->

# RouteDestination

`RouteDestination` contains a [`ViewSet`](#viewset) object. [`RouteHandler.new()`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/new.md) takes a `RouteHandlerCallback` containing a `RouteDestination`. [`RouteHandler.update()`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/update.md) takes a `RouteHandlerCallback` containing a `RouteDestination`.

## Syntax

```javascript
type RouteDestination {
    viewset: ViewSet;
}
```

## Properties

| Property  | Type               | Required/Optional | Description                                            |
| --------- | ------------------ | ----------------- | ------------------------------------------------------ |
| `viewset` | A `ViewSet` object | Required          | A `ViewSet` object that specifies the view to display. |

## ViewSet

The view to display. Supply a `ViewSet` object to a [`RouteDestination`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/routedestination.md).

### Properties

| Property   | Type   | Required/Optional | Description                                                                                                                                                                                                                                                                     |
| ---------- | ------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `viewName` | String | Required          | The `viewName` key maps to the `viewName` property for the [`outlet`](https://developer.salesforce.com/docs/platform/lwr/guides/lwr-outlets.md). It accepts **either**: <ul><li>a Promise to a route handler module: `{ default: import('my/routeHandler') }`.</li><li>a [`ViewInfo` object](#viewinfo)</li></ul></li></ul> |

**note:** In LWR, modules are always provided via a Promise object. Promises allow the module code to be lazily loaded, improving application performance.

### Syntax

```javascript
interface ViewSet {
    [viewName: string]: (() => Promise<Module>) | ViewInfo;
}
```

**note:** If a single page reference maps to more than one view, you can specify more than one outlet where each outputs a different view component. For example: `{ default: import('my/routeHandler'), sidebar: import('my/sideHandler'), footer: import('my/footerHandler') }`. Check out [Outlets](https://developer.salesforce.com/docs/platform/lwr/guides/lwr-outlets.md) for more information about using multiple outlets.

## ViewInfo

An object containing a Promise to a route handler module and a string specifier for the module. Supply a `ViewInfo` object to a [`ViewSet` object](#viewset).

### Properties

| Property | Type    | Required/Optional | Description                                                                                                                                                                                                                                                                                                 |
| -------- | ------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `module` | Promise | Required          | A promise to a route handler module.                                                                                                                                                                                                                                                                        |
| `string` | String  | Required          | A string specifier for the module, like `my/recipePage`. Simple or straightforward use cases typically don't require a specifier. In other cases, the specifier for the module can't be determined from a Promise alone, so you should manually define the module's string specifier for the route handler. |

### Syntax

```javascript
interface ViewInfo {
    module: () => Promise<Module>
    specifier: string;
}
```

**See Also**

- [Route Handler Modules](https://developer.salesforce.com/docs/platform/lwr/guides/lwr-route-handler-modules.md#routehandlercallback-and-routedestination)

<!-- document id=ffb1b4f6727853bb95c37e6fe8868ff08d0d6735f3fc3776db70b8f51a8c31ff url=/developer/current/en-us/lwr-node/lwr/references/csr-reference/routehandler-interface.md -->

# RouteHandler Interface

The `RouteHandler` class is defined as:

```
export interface RouteHandler {
  new (callback: RouteHandlerCallback): RouteHandler;
  dispose(): void;
  update(routeInfo: RouteInstance): void;
}
```

You can use these methods for `RouteHandler`:

- [new()](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/new.md)
- [dispose()](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/dispose.md)
- [update()](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/update.md)

**See Also**

- [Understand Client-Side Routing: Route Handler Modules](https://developer.salesforce.com/docs/platform/lwr/guides/lwr-route-handler-modules.md)

<!-- document id=0f397c04c9ddd922629aad8e109f7f11161df8634473d25da3db8f6744d1ad92 url=/developer/current/en-us/lwr-node/lwr/references/ss-routing-reference/routehandlerfunction.md -->

# RouteHandlerFunction

To learn how to use `RouteHandlerFunction`, see [Server-Side Routing](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-routing-server.html#route-handler-functions).

## Syntax

`RouteHandlerFunction` takes:

- a [`ViewRequest`](#viewrequest)
- a [`HandlerContext`](#handlercontext)

It returns a [`RouteHandlerViewResponse`](https://developer.salesforce.com/docs/platform/lwr/references/ss-routing-reference/routehandlerviewresponse.md).

```
type RouteHandlerFunction = (
  viewRequest: ViewRequest,
  handlerContext: HandlerContext,
) => Promise<RouteHandlerViewResponse>;
```

### `ViewRequest`

A `ViewRequest` object has to have:

- a URL
- a path (`requestPath`)

`ViewRequest` can optionally have any number of:

- parameters (`params`)
- queries (`query`)

```
// Request: given GET http://www.example.com/custom/thing?sort=desc
interface ViewRequest {
  url: string; // "/custom/thing?sort=desc
  requestPath: string; // "/custom/thing"
  params?: Record<string, string>; // { "param": "thing" }
  query?: Record<string, undefined | string | string[]>; // { "sort": "desc" }
}
```

For example, the `ViewRequest` object for the request `get http://www.example.com/custom/thing?sort=desc` looks like this.

```
{
  url: "/custom/thing?sort=desc
  requestPath: "/custom/thing"
  params?: { "param": "thing" }
  query?: { "sort": "desc" }
}
```

### `HandlerContext`

A `HandlerContext` object has to have:

- a route in the form of an `LwrRoute` or an `LwrErrorRoute` object
- a [`RouteHandlerViewApi`](#routehandlerviewapi) call

```
interface HandlerContext {
  route: LwrRoute | LwrErrorRoute; // the current route from lwr.config.json
  viewApi: RouteHandlerViewApi; // functions to call into the LWR server
}
```

### `RouteHandlerViewApi`

The `RouteHandlerViewApi` calls the functions:

- `hasViewResponse`
  - Takes a [`RouteHandlerView`](#routehandlerview) and a `Record`
  - Returns a boolean
- `getViewResponse`
  - Takes a `RouteHandlerView` and a `Record`
  - Returns a [`RouteHandlerViewResponse`](https://developer.salesforce.com/docs/platform/lwr/references/ss-routing-reference/routehandlerviewresponse.md) or `undefined`

```
interface RouteHandlerViewApi {
  // interact with the LWR rendered page view cache
  hasViewResponse(view: RouteHandlerView, viewParams?: Record<string, Json>): boolean;
  getViewResponse(
    view: RouteHandlerView,
    viewParams?: Record<string, Json>,
  ): Promise<RouteHandlerViewResponse | undefined>;
}
```

### `RouteHandlerView`

A `RouteHandlerView` object has this syntax:

```
type RouteHandlerView = Pick<LwrRoute, 'contentTemplate' | 'layoutTemplate' | 'rootComponent'>;
```

**See Also**

- [Server-Side Routing: Route Handler Functions](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-routing-server.html#route-handler-functions)

<!-- document id=7f30956aec414952f6d50ee030a5ac496336f912fff65e9e07ab91c7ad376b91 url=/developer/current/en-us/lwr-node/lwr/references/ss-routing-reference/routehandlerviewresponse.md -->

# RouteHandlerViewResponse

A `RouteHandlerViewResponse` can be a [`ViewDefinitionResponse`](#viewdefinitionresponse) object or a [`ViewResponse`](#viewresponse) object.

## `ViewDefinitionResponse`

Use this object to customize response input handled by the LWR server.

```
interface ViewDefinitionResponse {
  status?: number;
  view: RouteHandlerView;
  viewParams: Record<string, Json>
  renderOptions?: RenderOptions;
  cache?: CacheResponse;
  headers?: Record<string, string>
}
```

| Property        | Type                                                           | Required/Optional | Description                                                                                          |
| --------------- | -------------------------------------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------- |
| `status`        | Number                                                         | Optional          | The [HTTP response status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status).           |
| `view`          | [`RouteHandlerView`](https://developer.salesforce.com/docs/platform/lwr/references/ss-routing-reference/routehandlerfunction.md#routehandlerview) | Required          | A partial route.                                                                                     |
| `viewParams`    | `Record<string, Json>`                                         | Required          | The record is passed into the templates as dynamic content.                                          |
| `renderOptions` | [`RenderOptions`](#renderoptions)                              | Optional          | Configure settings for metadata collection, embedded asset URLs, and caching the page view response. |
| `cache`         | [`CacheResponse`](#cacheresponse)                              | Optional          | Page caching settings.                                                                               |
| `headers`       | `Record<string, string>`                                       | Optional          | HTTP headers.                                                                                        |

### `RenderOptions`

```
interface RenderOptions {
    skipMetadataCollection?: boolean;
    freezeAssets?: boolean;
    skipCaching?: boolean;
}
```

| Property                 | Type    | Required/Optional | Description                                                                                                                                  |
| ------------------------ | ------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `skipMetadataCollection` | Boolean | Optional          | To skip parsing of `body` for `<link>` and `<img>` tags, set to `true`. The default value is `false`.                                        |
| `freezeAssets`           | Boolean | Optional          | To construct immutable URLs for embedded assets, set this value to `true`. The default value is set to `runtimeEnvironment.immutableAssets`. |
| `skipCaching`            | Boolean | Optional          | To not cache the page view response, set this value to `true`. The default value is `false`.                                                 |

### `CacheResponse`

```
interface CacheResponse {
    ttl?: string | number;
}
```

| Property | Type              | Required/Optional | Description                                           |
| -------- | ----------------- | ----------------- | ----------------------------------------------------- |
| `ttl`    | `String`/`Number` | Optional          | Set the `"max-age`" for the `"Cache-Control"` header. |

## `ViewResponse`

Use this object to return a completely custom response override.

```
interface ViewResponse {
    status?: number;
    body: Buffer | string | boolean | Json;
    cache?: CacheResponse;
    headers?: Record<string, string>;
}
```

| Property  | Type                               | Required/Optional | Description                                                                                |
| --------- | ---------------------------------- | ----------------- | ------------------------------------------------------------------------------------------ |
| `status`  | Number                             | Optional          | The [HTTP response status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status). |
| `body`    | `Buffer`/`string`/`boolean`/`json` | Required          | The response body.                                                                         |
| `cache`   | [`CacheResponse`](#cacheresponse)  | Optional          | Page caching settings.                                                                     |
| `headers` | `Record<string, string>`           | Optional          | HTTP headers.                                                                              |

**See Also**

- [Server-Side Routing: Route Handler Functions](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-routing-server.html#route-handler-functions)

<!-- document id=ecfae76302930c5be46ea79f5a4c5b4e6ee07a50b690f475c772cb52e0e8684d url=/developer/current/en-us/lwr-node/lwr/references/csr-reference/routeinstance.md -->

# RouteInstance

A [route handler](https://developer.salesforce.com/docs/platform/lwr/guides/lwr-route-handler-modules.md) receives a `RouteInstance` when a new client-side navigation event occurs. `RouteInstance` contains location information passed to [`RouteHandler.update`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/update.md). The route handler uses the `RouteInstance` to determine which view to show.

## Syntax

```
interface RouteInstance {
  id: string; // RouteDefinition.id
  pageReference: PageReference;
  label: string;
}
```

## Properties

| Property        | Type                   | Required/Optional | Description                                                              |
| --------------- | ---------------------- | ----------------- | ------------------------------------------------------------------------ |
| `id`            | String                 | Required          | The unique identifier for the [`RouteDefinition`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/routedefinition.md).   |
| `pageReference` | `PageReference` object | Required          | The [`PageReference` object](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/pagereference.md) for the navigation event. |

## Example

```
{
    id: '1',
    pageReference: {
        type: 'animal',
        attributes: { pageName: 'animal' },
        state: {},
    },
},
```

**See Also**

- [Route Handler Modules](https://developer.salesforce.com/docs/platform/lwr/guides/lwr-route-handler-modules.md#3-the-router-passes-routeinstance-to-routehandlerupdate)

<!-- document id=4a7aa576defa16f16dd24f4fb44286f76439c77aaee536e57dd4e8eb549089b6 url=/developer/current/en-us/lwr-node/lwr/guides/lwr-router-containers.md -->

# Router Containers

In order to use a router in an application, it must be attached to the DOM with a router container. Router containers are provided by the [`lwr-router-container`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/lwr-router-container.html) component.

A router container provides **navigation context**. This means that the router container is responsible for processing all [navigation wires](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/lwr-navigation-wires.html) and events from its descendants in the DOM. In the following example, those descendants are `my-nav` and `lwr-outlet`.

```
<template>
    <lwr-router-container
        router={router}
        onhandlenavigation={handleNavigation}
        onprenavigate={preNavigate}
        onpostnavigate={postNavigate}
        onerrornavigate={errorNavigate}>
        <my-nav></my-nav>
        <lwr-outlet></lwr-outlet>
    </lwr-router-container>
</template>
```

```
import { LightningElement } from "lwc";
import { createRouter } from "lwr/router";
import { ROUTE_DEFINITIONS } from "./routeDefinitions";

export default class MyApp extends LightningElement {
  router = createRouter({ routes: ROUTE_DEFINITIONS });
  approvedCategories = ["apps", "entrees", "sides", "desserts"];

  handleNavigation(e: CustomEvent): void {
    console.log("navigate() called with page reference:", e.detail);
  }

  preNavigate(e: CustomEvent): void {
    const {
      next: {
        route: { pageReference },
      },
    } = e.detail;
    const {
      attributes: { cat },
    } = pageReference;
    console.log("navigation event incoming with page reference:", pageReference);
    if (!this.approvedCategories.includes(cat)) {
      // REJECT unapproved recipe categories
      e.preventDefault();
    }
  }

  postNavigate(e: CustomEvent): void {
    const {
      route: { pageReference },
    } = e.detail;
    console.log("navigated to page reference:", pageReference);
  }

  errorNavigate(e: CustomEvent): void {
    const { code, message } = e.detail;
    console.error(`navigation error -> ${code}: ${message}`);
  }
}
```

## Router Container Events

A router container requires a router, and it fires these [events](https://developer.salesforce.com/docs/platform/lwc/guide/events-handling.html):

`onhandlenavigation`

- Dispatched when [`navigate(pageRef)`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/navigate.html) is called.
- `event.preventDefault()` cancels the navigation event.
- `event.detail` is the `PageReference`.

`onprenavigate`

- Dispatched when a navigation event is received and a `RouteDefinition` match is found.
- `event.preventDefault()` cancels the navigation event.
- `event.detail` is a `RouteChange()`.

  ```
interface RouteChange {
  current?: DomRoutingMatch; // the current location info
  next: DomRoutingMatch; // location info for the incoming nav event
  }
```

`onpostnavigate`

- Dispatched when a navigation event has completed.
- `event.detail` is a `DomRoutingMatch` for the current location.

  ```
interface DomRoutingMatch {
  url: string; // e.g. "/recipes/desserts/010?units=metric&yummy=yes"
  route: RouteInstance;
  routeDefinition: RouteDefinition;
  }
```

`onerrornavigate`

- Dispatched when there is an error processing a navigation event. (For example, no `RouteDefinition` match or `prenavigate` cancelation.)
- `event.detail` is a `MessageObject`.

  ```
interface MessageObject {
  code: string | number;
  message: string;
  level: number; // Fatal = 0, Error = 1, Warning = 2, Log = 3
  }
```

## Next Steps

[Simple Client-Side Routing: Create a Router](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-routing-example-simple.md#create-a-router) demonstrates how to attach a router instance to a router container.

<!-- document id=f5f240a28124f91ba1b6cca1e9c9d7e881977bd3dff6fcc73625c6d0a7ae482b url=/developer/current/en-us/lwr-node/lwr/references/csr-reference/routerconfig.md -->

# RouterConfig

Pass a `RouterConfig` object to the [`createRouter()`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/createrouter.md) API to create a router for specific routes.

## Properties

| Property        | Type    | Required/Optional | Description                                                                                                                                                                                                                             |
| --------------- | ------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `routes`        | Array   | Optional          | An array of [route definitions](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/routedefinition.md). If you don't specify a `RouteDefinition` array, the default value is an empty array. If you don't specify a value for `RouterConfig.routes`, the router can't match any locations. |
| `basePath`      | String  | Optional          | A path prefix applied to all URIs for the router. If you don't specify a base path, the default value is `""`.                                                                                                                          |
| `caseSensitive` | Boolean | Optional          | If `true`, URIs are processed case sensitively. The default value is `false`.                                                                                                                                                           |
| `i18n`          | Array   | Optional          | An [`i18n`](https://developer.salesforce.com/docs/platform/lwc/guide/create-i18n.html) config that may affect the path prefix applied to all URIs. The default value is `{locale: 'en-US', defaultLocale: 'en-US'}`.                    |

## Syntax

```
type RouterConfig = {
  routes?: RouteDefinition[],
  basePath?: string,
  caseSensitive?: boolean,
  i18n?: {
    locale: string;
    defaultLocale: string;
  },
};
```

## Example

```
routes: [
    {
      id: 'home',
      uri: '/'
      handler: () => import('example/homePageHandler'),
        page: {
            type: 'home',
        },
    },
    {
        id: 'namedPage',
        uri: '/:pageName',
        handler: () => import('example/namedPageHandler'),
        page: {
            type: 'namedPage',
            attributes: {
                pageName: ':pageName',
            },
        },
    }
  ],
  basePath: '/my-site',
  i18n: {
    locale: 'es',
    defaultLocale: 'en-US'
  },
  caseSensitive: true
```

<!-- document id=6b8769eecd7c54642f21b0a61d62aae7554e8fff802daa63ec6c47196aad3ee6 url=/developer/current/en-us/lwr-node/lwr/guides/lwr-routers-route-matching.md -->

# 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.

## Routers

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](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-create-router.md#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](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-create-router.md#createrouter) to create and initialize a router based on a JSON configuration object. This method is appropriate for more sophisticated use cases.

### Route Definitions

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**](#route-matching).

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

|                             | Router Module Provider                                                                                                                  | `createRouter()` API                                                                                                  |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Route Definition Object** | [`LwrConfigRouteDefinition`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/lwrconfigroutedefinition.html) | [`RouteDefinition`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/routedefinition.html) |

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

#### URI

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](https://developer.mozilla.org/en-US/docs/Web/API/Window/popstate_event). Here's an example of a URI:

```
https://www.somewhere.com/animals/abc?view=compact&dark-mode
```

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

**note:** A URL is a type of URI.

#### Page Reference

A page reference is a location specified in JSON form. The [`navigate()` API](/docs/platform/lwr/references/csr-reference/navigate.html) passes navigation events to the router in the form of a [`PageReference` object](/docs/platform/lwr/references/csr-reference/pagereference.html).

This `PageReference` object is equivalent to the above URI.

```
{
    "type": "animal_page",
    "attributes": {
        "animalId": "abc"
    },
    "state": {
        "view": "compact",
        "dark-mode": ""
    }
}
```

## Route Matching

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

### URI Route Matching Rules

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 definition URI.
  - Case sensitivity only applies to literal query **values**. Matching can be case insensitive if `caseSensitive` isn’t specified in the [`RouteDefinition`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/routedefinition.html).
  - Case sensitivity always applies to the query key, regardless of `caseSensitive` settings.
- The order of the query parameters in the URL doesn’t matter.

### Page Reference Route Matching Rules

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).

### Route Matching Example

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

```
{
    id: 'apple-pie',
    uri: '/recipes/:category/:recipeId?units=:units&lang=en-us',
    // The query parameter "units" is bound to a dynamic value.
    // The query parameter "lang" is bound to the string literal "en-us".

    patterns: {
        recipeId: '^[0-9]{3}$',    // RegEx requiring that "recipeId" must be a 3 digit number
    },
    page: {
        type: 'recipe_page',       // Matching page references must be of type "recipe_page"
        attributes: {
            recipeId: ':recipeId', // The "recipeId" attribute is bound to the dynamic ":recipeId" path parameter
            cat: ':category',      // The "cat" attribute is bound to the dynamic ":category" path parameter
            units: ':units',       // The "units" attribute is bound to the dynamic ":units" query parameter
        },
        state: {
            code: 'abc123',        // Hard-coded state literal
        },
    },
    handler: () => import('my/recipeHandler'),
}
```

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

```
// URI -> https://www.somewhere.com/recipes/desserts/010?units=metric&lang=en-us&extra=foo
  // Same recipeId (010).
  // Matching query parameter (units). Matching query parameter and value (lang=en-us).
  // Extra query parameter (extra) is allowed.

// page reference:
{
    "type": "recipe_page", // Type matches
    "attributes": {
        // all bound attributes have values
        "recipeId": "010", // the "recipeId" matches the pattern
        "cat": "desserts",
        "units": "metric"
    },
    "state": {
        "code": "abc123", // the state literal matches
        "extra": "foo"    // extra state properties are allowed
    }
}
```

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

```
// URI -> https://www.somewhere.com/r/desserts/no?ylang=ja-jp
  // recipeId ("no") DOES NOT match. Missing the units query parameter. "lang" query literal ("ja-jp") DOES NOT match.

// page reference:
{
    "type": "blank_page", // type DOES NOT match
    "attributes": {
        "recipeId": "abc",  // the "recipeId" DOES NOT match the pattern
        "extra": "bad"     // extra attributes ARE NOT allowed
        // the "cat" and "units" attributes are missing
    },
    "state": {
        "code": "fail"     // the state literal IS NOT equal
    }
}
```

## Next Steps

What happens after a router matches an incoming location change to a route definition? Check out [Route Handler Modules](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-route-handler-modules.md) to learn more.

<!-- document id=3c7758a03a3a97525c7779f4ae0fc1ed439ff769baeaed676a3901919a6e3c91 url=/developer/current/en-us/lwr-node/lwr/references/ss-routing-reference/route.md -->

# routes

Each server-side `routes` object in an `lwr.config.json` file includes some of these properties

## Properties

| Property          | Type            | Required/Optional | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ----------------- | --------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`              | String          | Required          | The unique identifier for the route.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `path`            | String          | Required          | The unique URI path from which the route is served.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `layoutTemplate`  | String          | Optional          | The path to a static template that renders the page [layout](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-templates.html). If you don't set a value for `layoutTemplate`, it uses a default template.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `contentTemplate` | Filepath        | See description   | **Each route must have either a `rootComponent` or a `contentTemplate`, but not both.** Set `contentTemplate` as the path to a static template that renders the page content.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `rootComponent`   | Filepath        | See description   | E**ach route must have either a `rootComponent` or a `contentTemplate`, but not both.** Set `rootComponent` as the path to the top-level Lightning web component that LWR bootstraps into the HTML output for the route. If you use a `rootComponent`, LWR applies a default `contentTemplate` to render it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `properties`      | JSON object     | Optional          | A JSON object that can be passed to the templates as context.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `routeHandler`    | String          | Required          | A path to a [route handler function](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-routing-server.html#route-handler-functions) configured for the route.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `cache`           | Key-value pairs | Optional          | The cache settings for the routing, including: <ul><li>`ttl`: A number, in seconds, or a [time string](https://github.com/vercel/ms#examples) to use as the max-age on the [Cache-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) header.</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `bootstrap`       | JSON object     | Optional          | The `bootstrap` object contains client options that determine how an application page is loaded, including: <ul><li>`syntheticShadow`: An optional boolean value. When `true`, [LWC synthetic shadow](https://www.npmjs.com/package/@lwc/synthetic-shadow) is enabled. The default value is `false`.</li><li>`services`: An optional array of LWC modules to run on page load.</li><li>`ssr`: An optional boolean value. When `true`, [server-side rendering](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-what-is-ssr.html) is enabled for the route. The default value is `false`.</li><li>`mixedMode`: An optional boolean value. When `true`, [mixed mode](https://developer.salesforce.com/docs/platform/lwc/guide/create-mixed-shadow.html) is enabled for the route. The default value is `false`.</li></ul> |

## Example

```
{
  "id": "example",
  "path": "/",
  "rootComponent": "example/app",
  "layoutTemplate": "$layoutsDir/main.html",
  "properties": { "staticParam": "This is the Home page" },
  "cache": { "ttl": 60 }
  "bootstrap": {
      "syntheticShadow": true,
      "services": ["example/service", "example/loaderHooks"]
  }
}
```

<!-- document id=481757fd48a87a2ae113c9080e5b64a2c5ba9f14e81fc6ee90696cc975a29c41 url=/developer/current/en-us/lwr-node/lwr/guides/lwr-routing.md -->

# Routing and Navigation in LWR on Node.js

What’s web routing about and why does it matter? Should I care about routing in my single page application (SPA)?

The short answer is yes. A **route** is a way to connect a URL for a web page (that is, a request path) with the resource to be served for that request. Routes are integral to letting users:

- Share and bookmark links to parts of your site.
- Use the browser's "back," "forward," and "refresh" buttons.
- Open pages in new windows or tabs.

Routing can be simple, but LWR also supports sophisticated routing configurations. For example, LWR supports dynamic routes and complex content querying to handle scenarios such as [pagination](https://developer.mozilla.org/en-US/docs/Web/CSS/Layout_cookbook/Pagination).

For your LWR on Node.js site, you can control routing in two ways:

## Server-side routing

If your app uses server-side routing to manage page navigation, the user's entire webpage is reloaded before they can see the new page. In theory, the more complex your webpages are, the longer it takes for those pages to load from scratch. As a result, server-side routing is appropriate for simple routing needs.

Check out [Server-Side Routing](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-routing-server.md) to learn more.

## Client-side routing

If your app uses client-side-routing, the browser changes the current URL and updates the UI of the current webpage as needed. Instead of reloading the entire page from scratch (like server-side routing), the browser may only reload certain elements on the page.

Client-side routing enables single-page applications (SPAs), and you can use it in conjunction with server-side routing. To learn more, see [Client-Side Routing](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-routing-client-overview.md).

<!-- document id=03358c7b413fb66f4bbfa86616cb4dd7332cd5fac28f58ecb1ddc9b5db650e46 url=/developer/current/en-us/lwr-node/lwr/guides/lwr-platform-integrations.md -->

# Salesforce Platform Integrations

Want to add Salesforce resources to your site? With LWR, you can use these external dependencies to customize your app.

| Dependency                                | Use Case                                                  |
| ----------------------------------------- | --------------------------------------------------------- |
| Salesforce Lightning Design System (SLDS) | Style your site with accessible design systems.           |
| Lightning Base Components (LBC)           | Use base components from the Lightning component library. |
| Lightning Locker                          | Improve client-side security.                             |

<!-- document id=0dc62603cd49b92314be32c1b07c5ebb1f1a5b8e3d5992b797ddc817be0ff6b3 url=/developer/current/en-us/lwr-node/lwr/guides/lwr-ssr.md -->

# Server-Side Rendering

Want your website to render more quickly in the browser? Server-side rendering is one of the most impactful tools to improve site load times.

To review the basics of SSR, head over to [What is SSR?](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-what-is-ssr.md)

Otherwise, if you're ready to dive into implementing SSR, we recommend reviewing the following resources.

- [Configure Components for SSR](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-configure-component-ssr.md)
- [Best Practices for Portable Components](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-portable-best-practices.md)
- [Test Your Components](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-ssr-components-test.md)
- [Enable SSR for LWR Apps](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-enable-ssr-site.md)
- [Understanding Islands](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-understanding-islands.md)
- [Implement SSR Using Islands Architecture](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-ssr-islands-implementation.md)
- [Hydration Capabilities for Islands (Experience Cloud)](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-ssr-hydration-experience-cloud.md)
- [Update Lightning Base Components Styling](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-lbc-styling.md)

<!-- document id=b541246a7bf968cff0a49f90a70a2fc0be752174e60e145ea885d683da15d8d1 url=/developer/current/en-us/lwr-node/lwr/references/ss-routing-reference.md -->

# Server-Side Routing

Configure server-side routing for your web app with these resources.

- [`route`](https://developer.salesforce.com/docs/platform/lwr/references/ss-routing-reference/ss-routing-reference/route.md)
- [`RouteHandlerFunction`](https://developer.salesforce.com/docs/platform/lwr/references/ss-routing-reference/ss-routing-reference/routehandlerfunction.md)
- [`RouteHandlerViewResponse`](https://developer.salesforce.com/docs/platform/lwr/references/ss-routing-reference/ss-routing-reference/routehandlerviewresponse.md)

**See Also**

- [Server-Side Routing: Route Handler Functions](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-routing-server.html#route-handler-functions)

<!-- document id=34f06675f01c757584009476277de4520e1454ef08ac050e4d3061805b6a5794 url=/developer/current/en-us/lwr-node/lwr/guides/lwr-routing-server.md -->

# Server-Side Routing in LWR on Node.js

To set server-side routes for your app with LWR, use the `lwr.config.json` project configuration file. Server-side routes can be specified in `lwr.config.json` by providing either:

- a static path for each page
- a JavaScript file that defines a hook to dynamically generate server-side routes for pages at server startup (this is an advanced option)

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.

## Static Server-Side Routing

Let’s add a page to our site and do some basic (and fast!) routing.

1. Now that you’ve got your [`StaticSite` project](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-get-started.md), make a copy of the `about.md` file. Rename the new file `explore.md` and leave it in the `content` directory.
2. Edit the `explore.md` file. Change the first line from `# About LWR` to `# Explore LWR`. Save the file.
3. Open the `main_layout.njk` file. On a new line, add `<li><a href="/explore">Explore</a>` under the `about` line. Save the file. ![Code snippet showing the Explore href addition](https://developer.salesforce.com/docs/media/addingExploreButton.png)
4. Finally, open the `lwr.config.json` file. Copy the entire block of code for `about`, including the curly brackets, and paste it below the `about` block. Change `about` to `explore` throughout, and don’t forget to add the comma after the closing bracket in the `about` block. Save the file. ![Code snippet showing the Explore block added](https://developer.salesforce.com/docs/media/addingExploreRouting.png)
5. If you're still in the `StaticSite` directory from when you [first made your site](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-get-started.md), just type `npm run start` in the terminal to see your changes. Your updated `StaticSite` project runs at [http://localhost:3000/](http://localhost:3000/), with a new **Explore LWR** page and a working **Explore** button. ![Screenshot of updated site with Explore LWR page](https://developer.salesforce.com/docs/media/siteWithNewExploreRouting.png)

**tip:** If you get a "Port 3000 is already in use" error after running `npm run start`, close any terminal tabs that run your site preview. Then, open a new terminal tab and run `npm run start`.

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 using a [**route**](https://developer.salesforce.com/docs/platform/lwr/references/ss-routing-reference/route.html)
  - you gave an `id` for the page (`Explore`)
  - you provided the `path` for the page (`/explore`)
  - you provided a `contentTemplate` for the page (`explore.md`)
  - you told LWR the `layoutTemplate` to 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

## Error Routes

You can set up routes to serve if LWR encounters a `404` or `500` error during the bootstrap of a route. Error routes take a `status` code value instead of a `path` value.

```
{
  "errorRoutes": [
    {
      "id": "not_found",
      "status": 404,
      "rootComponent": "example/notFound"
    },
    {
      "id": "server_error",
      "status": 500,
      "contentTemplate": "$contentDir/not-found.html"
    }
  ]
}
```

## Dynamic Server-Side Routing with Configuration Hooks

**note:** This is an advanced topic.

Configuration hooks let you dynamically generate server-side routes for your application. On server startup, they update the [configuration](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-configure-project.md) and [global data](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-compile-data.md#global-data) for your app.

To set up a configuration hook, start by creating a `hooks` section in your `lwr.config.json` file. In there, add the filepath that points to the hook.

```
{
  "hooks": ["$rootDir/src/hooks/my-config-hook.ts"]
}
```

The following is an example of a configuration hook:

```
import path from 'path';
import { DEFAULT_LWR_BOOTSTRAP_CONFIG } from '@lwrjs/config';
import { slugify } from '@lwrjs/shared-utils';
import type { HooksPlugin, NormalizedLwrGlobalConfig, NormalizedLwrRoute, GlobalData } from '@lwrjs/types';

const DEFAULT_MAIN_LAYOUT = 'main_layout.njk';
const CACHE_TTL = '30m';
interface GuideItem {
  label: string;
  content: string;
}
interface GuideSidebarItem {
  label: string;
  id: string;
  url: string;
}
interface SiteGlobalData extends GlobalData {
  site?: {
    guide: GuideItem[];
      sidebar: GuideSidebarItem[];
  };
}

function generateGuideSidebar(guide: GuideItem[]): GuideSidebarItem[] {
  return guide.map(({ label, content }) => {
    return {
      label,
      id: `guide_${slugify(label)}`,
      url: `/${content.replace('.md', '')}`,
    };
  });
}

function generateGuideRoutes(
  guide: GuideItem[],
  { contentDir, layoutsDir }: NormalizedLwrGlobalConfig,
): NormalizedLwrRoute[] {
  return guide.map(({ label, content }) => {
    return {
      id: `guide_${slugify(label)}`,
      path: `/${content.replace('.md', '')}`,
      contentTemplate: path.join(contentDir, content),
      layoutTemplate: path.join(layoutsDir, DEFAULT_MAIN_LAYOUT),
      cache: { ttl: CACHE_TTL },
      bootstrap: DEFAULT_LWR_BOOTSTRAP_CONFIG,
    };
  });
}

// Export an Application Configuration hook
// Configured in lwr.config.json[hooks]
export default class MyAppHooks implements HooksPlugin {
  initConfigs(lwrConfig: NormalizedLwrGlobalConfig, globalData: SiteGlobalData): void {
    if (!globalData.site) {
      throw 'Expected site global data to be defined';
    }

    // The guide is an ordered list of files we want to display
    // Hardcoded here: src/data/site/guide.json
    const guide = globalData.site.guide;

    // Generate sidebar add it to the globalData object
    // The data is accessed in src/layouts/partials/guide-sidebar.njk
    globalData.site.sidebar = generateGuideSidebar(guide);

    // Dynamically add a new route for each guide
    // Note: other routes are statically declared in lwr.config.json[routes]
    lwrConfig.routes.push(...generateGuideRoutes(guide, lwrConfig));
  }
}
```

Dynamic server-side routes can use [route handler functions](#route-handler-functions) to customize the page response at runtime.

## Route Handler Functions

**note:** This is an advanced topic.

Route handler functions are part of the [LWR context object](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-compile-data.md). They’re a server-side way to alter the current route and customize the page response at runtime. You can use route handler functions with both [static](#static-server-side-routing) and [dynamic](#dynamic-server-side-routing-with-configuration-hooks) server-side routing.

**tip:** Route handler **functions**, which are used in LWR's server-side routing, aren’t the same as [route handler **modules**](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-route-handler-modules.md), which are used in client-side routing.

There are a couple of differences between [configuration hooks](#dynamic-server-side-routing-with-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 `lwr.config.json`, like this:

```
{
  "id": "custom_route_handler",
  "path": "/custom/:param",
  "routeHandler": "$rootDir/src/routeHandlers/custom.ts"
}
```

A route handler function follows this syntax. For more information about syntax and properties of [`RouteHandlerFunction`](https://developer.salesforce.com/docs/platform/lwr/references/ss-routing-reference/routehandlerfunction.html) and the [`RouteHandlerViewReponse`](https://developer.salesforce.com/docs/platform/lwr/references/ss-routing-reference/routehandlerviewresponse.html) that it returns, see the [Server-Side Routing Reference](https://developer.salesforce.com/docs/platform/lwr/references/ss-routing-reference/ss-routing-reference.html).

```
type RouteHandlerFunction = (
    viewRequest: LocalizedViewRequest,
    handlerContext: HandlerContext,
) => Promise<RouteHandlerViewResponse>;
```

Things to note:

- **Cache size.** All the `ViewDefinitionResponse.viewParams` are 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.viewParams` replace the [static route properties](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-compile-data.md#static-route-properties), so if the static route properties are needed, you must merge them into the `viewParams` in the route handler function.
- **Markdown.** The dynamic `ViewDefinitionResponse.viewParams` are available in Markdown content templates. This is notable because in general [context](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-compile-data.md#understand-context-objects) isn't passed into Markdown templates, _unless_ you use a custom route handler.
- **View.** LWR merges the `ViewDefinitionResponse.view` with the `id` and `bootstrap` values from the current route.
- **Time-to-live.** The `CacheResponse.ttl` is a number, in seconds, or a [time string](https://github.com/vercel/ms#examples) to use as the `max-age` on the [`Cache-Control`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) header.
- **Supported languages**. You can use both TypeScript and JavaScript to create your route handler.

### 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.

```
import { HandlerContext, RouteHandlerViewResponse, ViewRequest } from '@lwrjs/types';

// Return customized input, from which the LWR server constructs a response
// viewRequest = { url, requestPath, params?, query? }
// handlerContext = { route, viewApi: { hasViewResponse, getViewResponse } }
export default function echoRouteHandler(
  viewRequest: ViewRequest,
  handlerContext: HandlerContext,
): RouteHandlerViewResponse {
  const routeProperties = handlerContext.route.properties || {};
  const message = viewRequest.params.message;

  // return a "ViewDefinitionResponse"
  return {
    // Required: customize the current route by setting:
    // { rootComponent?, contentTemplate?, layoutTemplate? }
    view: {
      contentTemplate: '$contentDir/echo.html',
    },
    // Required: pass context to the templates
    viewParams: {
      message, // pass the "message" path param
      ...routeProperties, // pass the static route properties
    },
    // Optional: rendering options { skipMetadataCollection?, freezeAssets?, skipCaching? }
    renderOptions: {
      freezeAssets: true,
    },
    // Optional: caching options { ttl? }
    cache: {
      ttl: 200,
    },
  };
}
```

### 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.

```
import { ViewRequest, ViewResponse } from 'lwr';

// Return a completely custom response
// containing some JSON data, based on the current path and query parameters
// viewRequest = { url, requestPath, params?, query? }
export default function jsonRouteHandler(viewRequest: ViewRequest): ViewResponse {
  const myPathParam = viewRequest.params.my;
  const someQueryParams = viewRequest.query?.some;

  // return a "ViewResponse": { status?, body, cache?, headers? }
  return {
    // Required: return the response body
    body: {
      my: myPathParam,
      some: someQueryParams,
    },
    // Optional: HTTP header map
    headers: {
      'Content-Type': 'application/json',
    },
  };
}
```

<!-- document id=a34906ab26253b649b9ca30872357398f51a0bf33994577b45b6a6ce421adfee url=/developer/current/en-us/lwr-node/lwr/guides/lwr-routing-example-simple.md -->

# Simple LWR Client-Side Routing Example

You can use the `@lwrjs/router` package to create a single page LWR application (SPA) with client-side routing. Important exports from the package include:

- `lwr/router`
- `lwr/routerContainer`
- `lwr/outlet`
- `lwr/navigation`

For additional information:

- [Client-Side Routing in LWR on Node.js](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-routing-client-overview.md)
- [LWR Client-Side Routing Reference](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/csr-reference.html)

## Example Project Setup

While an LWR app contains more files than shown here, in this recipe the following example module files are most important:

```asciidoc
simple-routing
├── src
│   └── modules
│       └── example
│           ├── app
│           │   ├── app.css
│           │   ├── app.html
│           │   └── app.js
│           ├── homePageHandler
│           │   └── homePageHandler.js
│           ├── namedPageHandler
│           │   └── namedPageHandler.js
│           └── pageLink
│                   └── pageLink.html
│                   └── pageLink.js
├── lwr.config.json
└── package.json
```

## Set the Root Component of Your Application

The first step in creating a router is to set up the root component of your SPA. You specify a `rootComponent` value in a `routes` object in your app’s `lwr.config.json` file. Check out the following example and ["Routing Properties"](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-routing-server.md#routing-properties) for more information.

**note:** The routes defined in `lwr.config.json` are server-side. They differ from the [`RouteDefinition`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/routedefinition.html) array that you set up in the next step for the client-side router.

This file is lwr.config.json.

```json
{
  "lwc": { "modules": [{ "dir": "$rootDir/src/modules" }] },
  "routes": [
    {
      "id": "app",
      "path": "/",
      "rootComponent": "example/app"
    }
  ]
}
```

## Create a Router

After you set up your root component, create a router for it. This example uses the [`createRouter()`](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-create-router.md) function to generate a router.

<!-- prettier-ignore -->
```javascript
// src/modules/example/app/app.js

import { LightningElement } from "lwc";
import { createRouter } from "lwr/router";

// Route definition array
const routes = [
  {
    id: 'home',
    uri: '/',
    handler: () => import('example/homePageHandler'),
    page: {
      type: 'home',
    },
  },
  {
    id: 'namedPage',
    uri: '/:pageName',
    handler: () => import('example/namedPageHandler'),
    page: {
      type: 'namedPage',
      attributes: {
        pageName: ':pageName',
      },
    },
  },
];

export default class SimpleRoutingApp extends LightningElement {
  router = createRouter({ routes });

  homeReference = { type: 'home' }; // Home page reference for the page-link
}
```

In your root component’s html file, attach the router instance to `lwr/routerContainer`, as in this example:

<!-- prettier-ignore -->
```html
<!-- src/modules/example/app/app.html -->

<template>
    <lwr-router-container router={router}>
        <example-page-link label="Home" page-reference={homeReference}></example-page-link>
        <lwr-outlet>
            <div slot="error">This content failed to display.</div>
        </lwr-outlet>
    </lwr-router-container>
</template>
```

## Create a Route Handler

In the previous step you [created a router](#create-a-router) in your root component file. That router includes a promise in `RouteDefinition.handler` to a route handler module that’s called when a location matches a [`RouteDefinition`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/routedefinition.html). [Route handler modules](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-route-handler-modules.md) determine the associated "view", which is the component to display when the application navigates to a location.

**note:** In LWR, route handler modules are [dynamically imported](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import), so they are provided via promises. Promises allow the module code to be lazily loaded, improving application performance.

A simple route handler for a home page:

<!-- prettier-ignore -->
```javascript
// src/modules/example/homePageHandler/homePageHandler.js

export default class HomePageHandler {
  callback;

  constructor(callback) {
    this.callback = callback;
  }

  dispose() {
    /* noop */
  }

  update() {
    this.callback({
      viewset: {
        default: () => import('example/home'),
      },
    });
  }
}
```

Route handler modules allow you to define enhanced routing rules such as branching and pivoting logic based on data and metadata values. Here’s another route handler, this time with branching logic:

<!-- prettier-ignore -->
```javascript
// src/modules/example/namedPageHandler/namedPageHandler.js

export default class NamedPageHandler {
  callback;

  constructor(callback) {
    this.callback = callback;
  }

  dispose() {
    /* noop */
  }

  update({ attributes }) {
    let viewGetter;

    // Get the "pageName" from the incoming page reference
    switch (attributes.pageName) {
      case "products":
        viewGetter = () => import('example/products');
        break;
      case "recipes":
        viewGetter = () => import('example/recipes');
        break;
      case "contact":
        viewGetter = () => import('example/contact');
        break;
      default:
        return;
    }

    this.callback({
      viewset: {
        default: viewGetter,
      },
    });
  }
}

```

## Navigate

In a Lightning web component, use the [`NavigationContext` wire](/docs/platform/lwr/references/csr-reference/navigationcontext.html) and [`navigate()` function](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/navigate.html) from `lwr/navigation` to navigate.

For example, in this snippet, the `NavigationContext` wire obtains a `ContextId` value. It assigns the ID to the `navContext` property, where it can be used by the [`navigate()`](/docs/platform/lwr/references/csr-reference/navigate.html) API.

```
import { LightningElement, wire } from 'lwc';
import { NavigationContext, navigate } from 'lwr/navigation';

export default class HomeLink extends LightningElement {
    @wire(NavigationContext)
    navContext;

    navigateHome(event) {
        // Navigate when the button is clicked
        event.preventDefault();
        if (this.navContext) {
            navigate(this.navContext, {
                type: 'home',
                attributes: { format: 'list' },
                state: { 'dark-mode': 'true' },
            });
        }
    }
}
```

```
<template>
  <button onclick="{navigateHome}">Home</button>
</template>
```

You can also use [`generateUrl()`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/generateurl.html) to generate a URL from a page reference, like this:

```
import { LightningElement, api, track, wire } from 'lwc';
import { NavigationContext, generateUrl, navigate } from 'lwr/navigation';

export default class PageLink extends LightningElement {
  @api label;
  @api pageReference;
  @track path;

  @wire(NavigationContext)
  navContext;

  async connectedCallback() {
    // Add an href to the link anchor
    if (this.pageReference && this.navContext) {
      this.path = generateUrl(this.navContext, this.pageReference) || undefined;
    }
  }

  handleClick(event) {
    // Navigate when the link is clicked
    event.preventDefault();
    if (this.pageReference && this.navContext) {
      navigate(this.navContext, this.pageReference);
    }
  }
}
```

```
<template>
    <a onclick={handleClick} href={path}>{label}</a>
</template>
```

## Handle Errors

Sometimes the router navigation completes, but the component's new view contains an error. This situation is considered a successful navigation, so an [`errornavigate` event](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/lwr-router-container.html#returns) doesn't fire. To handle this situation:

1. Display an error:

   Via an error slot in an [`lwr-outlet`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/lwr-outlet.html) component:

   ```html
   <!-- app.html -->

   <lwr-outlet>
     <div slot="error">This content failed to display</div>
   </lwr-outlet>
   ```

   Or via a custom component in the error slot:

   ```html
   <!-- app.html -->

   <lwr-outlet>
     <div slot="error">
       <c-my-error></c-my-error>
     </div>
   </lwr-outlet>
   ```

2. Handle the [`viewerror` event](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/lwr-outlet.html#events) that `lwr-outlet` dispatches:

   ```
<template>
       <lwr-router-container router={router}>
           <lwr-outlet onviewerror={onViewError}></lwr-outlet>
       </lwr-router-container>
   </template>
```

   ```
onViewError(viewErrorEvent: CustomEvent) {
       // handle viewerror
       const error = viewErrorEvent.detail.error;
       const stack = viewErrorEvent.detail.stack;
       console.error(`error rendering view component: '${error.message}' from:\n${stack}`);
   }
```

Read more about [LWR outlets](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-outlets.md).

## Run Your SPA

Run the following terminal commands from the root of your project. Read [Get Started](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-get-started.md#set-the-lwr-server-modes) for details on LWR NPM commands.

```bash
npm install
npm run build
npm run start
```

Open the site at http://localhost:3000.

<!-- document id=68928f28d1e7a1ea1e390e1814dd634d19f146b4942754f91264850e2e931d68 url=/developer/current/en-us/lwr-node/lwr/references/packages-reference/lwrjs-security/stricttransportsecurity.md -->

# StrictTransportSecurity object

Use `StrictTransportSecurity` to configure the [`Strict-Transport-Security`](https://developer.salesforce.com/docs/platform/guides/lwr-security.md#strict-transport-security) header.

## Syntax

```
interface StrictTransportSecurity {
   maxAge: number;
   includeSubDomains: boolean;
   preload: boolean;
}
```

## Directives

You can customize these directives for a `Strict-Transport-Security` header. Set values for them in a `StrictTransportSecurity` object.

- `max-age` (number)
- `includeSubDomains` (boolean)
- `preload`
  - Add this directive to request your site to join [Google Chrome's HTTP Strict Transport Security (HSTS) preload list](https://hstspreload.org/). To be eligible, your app has to adhere to all of the submission requirements listed on the HSTS site.

For information about each directive, see [MDN Web Docs: Strict-Transport-Security Directives](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security#directives)

## Example

```
"strictTransportSecurity":
  {
    "maxAge": 15552000;
    "includeSubDomains": true;
    "preload": true;
  }
```

**See Also**

- [Guide: @lwrjs/security](https://developer.salesforce.com/docs/platform/guides/lwr-security.md)

<!-- document id=b8ca5b42cbbf0142396ebca96ff31dfff705e2ccef5fdd50a59e8cd6ad0bb782 url=/developer/current/en-us/lwr-node/lwr/guides/lwr-ssr-components-test.md -->

# Test Your Components

**important:** Before you test components, make sure you've reviewed the [best practices for portable components](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-portable-best-practices.md).

To check if you can server-side render (SSR) your components, evaluate them with the [SSR playground](#debug-with-the-ssr-playground), the [SSR test runner](#run-the-test-runner), and unit tests with Jest. You can also [manually verify](#manually-verify-ssr-for-a-component) that SSR was successful for a component.

## Debug with the SSR Playground

The SSR playground lets you render, debug, and experiment with individual components and their children. You can use the playground in client-side rendering (CSR) mode or SSR mode.

To run the playground, navigate to a directory that contains one of these files and run the appropriate [playground command](#ssr-playground-commands).

- `lwc.config.json` file
- `package.json` file containing an `lwc` field
- `sfdx-project.json` file that points to a project directory containing LWCs

### SSR Playground Commands

To open the playground in Chrome, run this command in your terminal:

```bash
npx -p @lwc/wds-playground playground namespace/component
```

To open the playground in Chrome with DevTools, run this terminal command:

```bash
npx -p @lwc/wds-playground playground namespace/component --open --devtools
```

### Step-By-Step Testing with the SSR Playground

Start at the "leaves" of your component tree, or components that don't contain other components.

1. Open the component in the SSR playground.
   1. Modify the component properties to test important use cases.
   2. Address errors that are reported during the three phases of hydration—SSR, DOM insertion, and rehydration.
   3. Look for and address any visual bugs in your component.
2. Enable the CSR toggle to render your component with SSR and CSR side by side.
3. Use the playground’s comparison tool to ensure the SSR and CSR component instances are visually identical.
4. Enable the layout shift tool in the Misc section in config to observe any layout shifts during SSR hydration.

![The SSR playground's comparison tool.](https://developer.salesforce.com/docs/media/uplift-playground.png)

By default, the SSR playground takes your component through three stages of its SSR lifecycle:

1. Render the component to HTML markup on the server.
2. Insert the markup into the DOM on the client.
3. Hydrate the DOM subtree and associate it with an instance of your component class.

We recommend that you write tests using the SSR test runner to ensure that your components don't regress as you make changes.

### Install the SSR Test Runner

**note:** This tool works best with Node v18 or v20.

You have to install the SSR Test Runner before you can use it on your project.

To add the test runner to your project, download the `@lwc/test-runner` package using a package management tool. We recommend using Node Package Manager (npm).

```
npm install --save-dev @lwc/test-runner
```

### Write SSR tests

**note:** By default, the SSR Test Runner executes SSR tests in headless Chrome. Unlike Jest tests, the SSR tests run in a full-featured web browser.

To create your own SSR tests, you can use these functions from the `@lwc/test-runner` package.

#### `renderToMarkup()`

`renderToMarkup()` is an asynchronous function that takes:

- The path to your component
- The properties that you use for rendering

It returns:

- `Promise<String>` where the `String` is HTML markup

#### `insertMarkupIntoDom()`

`insertMarkupIntoDom()` is an asynchronous function that takes:

- SSR markup, like `Promise<String>` returned by `renderToMarkup()`

It returns:

- `Promise<HtmlElement>()`, which is a handle to the root element of your SSR-rendered DOM subtree.

#### `hydrateElement()`

`hydrateElement()` is an async function that takes:

- A root element, like `Promise<HtmlElement>` returned from `insertMarkupIntoDom()`
- Component properties, which should be the same as those passed into `renderToMarkup()`

It returns:

- `Promise<Boolean>`, where the `Boolean` indicates whether hydration completed without validation errors. In most cases, you'll want this Boolean value to be true. If hydration failed, review the errors in the console.

#### `expect()`

You can use this function to chain assertions. To make it easier to test your components, it includes all the assertions from `Chai.expect` as well as the following additions.

- `throwErrorInConnectedCallback`: Asserts any errors thrown in `connectedCallback`.
- `SSRCorrectly`: Checks that all three stages of SSR lifecycle are performed correctly.
- `visuallyIdenticalInCSRandSSR`: Performs a pixel match of SSR and CSR components.
- `noLayoutShifts`: Ensures that the component didn't have any layout shifts when it was hydrated in DOM.
- `notMakeDomMutationsDuringSSR`: Ensures that the component didn't make any DOM mutation.

#### Example SSR Test

Here's a sample SSR test that you can execute with the SSR Test Runner.

```
import {
    // Importing `expect` from the toolkit is subject to change
    expect,
    querySelectorDeep,
    // These three functions contribute heavily to your tests
    renderToMarkup,
    insertMarkupIntoDom,
    hydrateElement,
} from '@lwc/test-runner';

// Instead of importing the component directly, use the path of
// the component's JS file. This value is passed to `renderToMarkup`
// and `hydrateElement` where the component is imported automatically.
const componentPath = import.meta.resolve('./parent.js');

describe('<x-parent>', () => {
    it('is SSR-able and very snazzy', async () => {
    // Errors thrown during SSR cause the test to fail
    const markup = await renderToMarkup(componentPath, {});

    // Once you have the raw HTML markup, you can make related assertions.
    expect(markup).to.contain('</x-parent>');

    // Insert that markup into the DOM. It doesn't get attached
    // to an instance of your component class yet.
    const el = await insertMarkupIntoDom(markup);

    // Make assertions about pre-hydrated DOM
    expect(el).to.haveShadowChild('p.child-content');

    // Finally, hydrate the HTML that was generated on the server and
    // inserted into the DOM in previous steps.
    const hydratedWithSsrDOM = await hydrateElement(el, componentPath);

    // Check that hydration occurred without validation errors.
    expect(hydratedWithSsrDOM).to.be.true;

    // Now that the SSR-generated markup has been inserted and hydrated,
    // the component should behave as though it were originally rendered
    // in the browser with CSR. Check the component to ensure expected behavior.
    expect(querySelectorDeep('p.child-content', el)).to.have.text('Hmm! hello from parent');
    });

    // Unless you want to make assertions on output of each individual stage of SSR,
    // you can use this one-liner to check that DOM was hydrated without any errors.
    it('SSR correctly', async () => {
        await expect(componentPath, {}).to.SSRCorrectly();
    });

    // Make sure no error is thrown when connected callback lifecycle is executed
    it('doesnt throw in connected callback', async () => {
        await expect(async () => {
            await renderToMarkup(componentPath, {});
        }).to.not.throwErrorInConnectedCallback();
    });

    // Pixel match rendered SSR and CSR components to check for visual correctness
    it('checks that SSR and CSR are visually the same ', async () => {
        await expect(componentPath, {}).to.be.visuallyIdenticalInCSRandSSR();
    });

    // No layout shift was observed during hydration stage
    it('has no layout shifts', async () => {
        await expect(componentPath, {}).to.have.noLayoutShifts();
    });

    // The component doesn't make any DOM mutation
    it('makes no DOM mutations', async () => {
        await expect(componentPath, {}).to.notMakeDomMutationsDuringSSR();
    });
});
```

### Run the Test Runner

Ready to invoke the test runner and run your own SSR tests? First, make sure you [installed](#install-the-ssr-test-runner) the `@lwc/test-runner` dependency for your project.

Then, run the test runner using `npx` or NPM scripts to invoke the `@lwc/test-runner` command. Tests run in parallel in separate headless Chrome tabs. The tests run fast, and as many as ten thousand tests can complete in under six seconds — depending on your hardware.

Here's the `npx` command to start the test runner. To customize your test runner output, you can use [supported command line flags](#lwctest-runner-flags). By default, the `@lwc/test-runner` command prints all the browser console output in your terminal.

```
npx @lwc/test-runner SPEC_FILE_PATTERN
```

**important:** If you use ZSH, surround `SPEC_FILE_PATTERN` in single quotes.

To distinguish your project's SSR tests from your Jest tests, use unique file extensions. For example, if your Jest tests follow the format `COMPONENT_NAME.spec.js`, you can follow the format `COMPONENT_NAME.spec-ssr.js` for your SSR test files. If you follow this filename format, run your tests like this:

```
npx @lwc/test-runner './src/**/*.spec-ssr.js'
```

You can also create a shortcut for this command in your project's `package.json` that uses NPM. Here's an example:

```
"scripts": {
    "test:ssr": "lwc-test-runner 'src/**/*.spec-ssr.js'"
}
```

#### @lwc/test-runner Flags

Add these flags to your `@lwc/test-runner` command to customize its command line output.

| Flag                            | Description                                                                        |
| ------------------------------- | ---------------------------------------------------------------------------------- |
| `--debug`                       | Enables debug mode to find issues with your tests.                                 |
| `--modulesDir <directory name>` | Invoke the test runner on a specific directory in your project.                    |
| `--puppeteer`                   | Execute the test runner in the [Puppeteer](https://pptr.dev/) browser environment. |
| `--quiet`                       | Prevents browser console output from printing in your terminal.                    |

### Interpret Test Runner Output

If the test runner returns failures for `hydrateElement`, `noLayoutShifts`, or `notMakeDomMutationsDuringSSR`, you likely have performance issues on the client-side.

## Manually Verify SSR for a Component

When a component is rendered on a page, you can verify that SSR was successful by looking at the DOM elements.
To determine if an island or component tree implemented SSR successfully:

1. In Chrome, right-click the page and select to **View Page Source**. If you use Firefox or another browser, the **View Page Source** tool might be named something else, like Inspect or View Selection Source.
2. Search for some HTML or text from the component. If you find it, then SSR was successful.

**CSR-only** — The wrapper has no inner HTML.

```
<webruntime-island-container-x1787601173>
</webruntime-island-container-x1787601173>‍
```

**SSR with hydration** — The wrapper has inner HTML and a `data-lwr-props-id` attribute.

```
<webruntime-island-container-x1783627592 data-lwr-props-id="lwcprops8de0">
    <c-cmp>
        <style type="text/css">...</style>
        <textarea></textarea>
    </c-cmp>
</webruntime-island-container-x1783627592>
```

**SSR-only (not hydrated)** — There's no wrapper, so the HTML exists in the page source.

```
<c-title>
    <style type="text/css">...</style>
    <h1>Page Title</h1>
</c-title>
```

## Write Jest Unit Tests

Jest is the primary tool used for testing in LWR projects. The [`lwc-test` NPM package](https://github.com/salesforce/lwc-test/) lets you write Jest unit tests that you can run in SSR and CSR environments. We recommend using two separate test suites to ensure that SSR and CSR are independently and thoroughly validated.

To start working with SSR or CSR unit tests, add the latest version of the following dependencies to your project:

- `@lwc/jest-ssr-snapshot-utils`
- `@lwc/jest-jsdom-test-env`
- `@lwc/jest-preset`

### SSR Unit Tests

Server-side tests focus on rendering components to static HTML on the server side. To make sure that server-side logic works as expected without client-side DOM interactions, these tests are executed in a Node environment.

Here's a sample Jest configuration file for server-side testing:

```
module.exports = {
    displayName: 'Server-side rendering',
    preset: '@lwc/jest-preset/ssr-server',
    testMatch: ['**/*.ssr-server.(spec|test).(js|ts)'],
    collectCoverageFrom: ['**/*.ssr-server.(spec|test).(js|ts)'],
};
```

To run a server-side test, add a script to your `package.json`. You can alternatively use `jest --selectProjects <project_name>` to target specific test suites.

```
"scripts": {
    "test:ssr:server": "jest --no-cache --projects=./example-ssr/jest.ssr-server.config.js"
}
```

Running server-side tests generates static HTML markup as snapshots. Every part of a snapshot associated with a table-driven test case is linked to a unique hash that's generated from the component's tag name, properties, and state. Use snapshots to verify the consistency of server-rendered output, like this:

1. Run server-side tests to generate baseline snapshots.
2. Whenever your components change, rerun the server-side tests to identify any related markup changes. The tests fail if any discrepancies between component versions arise.
3. After you confirm that your changes are safe and valid, update your HTML markup snapshots.

### CSR Unit Tests

Client-side tests validate how components behave [post-hydration](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-understanding-islands.md) in a browser-like environment. To simulate browser behavior, these tests are executed using JSDOM.

Here's a sample Jest configuration file for client-side testing:

```
module.exports = {
    displayName: 'SSR with hydration',
    preset: '@lwc/jest-preset/ssr-for-hydration',
    setupFilesAfterEnv: ['./jest.ssr-client.setupAfterEnv.js'],
    testMatch: ['**/*.ssr-client.(spec|test).(js|ts)'],
    transformIgnorePatterns: ['node_modules/(?!(@webcomponents/.+)/)'],
};
```

To track hydration errors, monitor the `console.warn` event.

```
let hydrationMismatchOccurred = false;
let hydrationMismatchMessage = '';

beforeEach(() => {
    // Reset the flag and message before each test
    hydrationMismatchOccurred = false;
    hydrationMismatchMessage = '';

    // Spy on console.warn and intercept warnings
    jest.spyOn(console, 'warn').mockImplementation((message) => {
        if (message.includes('Hydration mismatch')) {
            // Set the flag to indicate a hydration mismatch occurred
            hydrationMismatchOccurred = true;
            // Store the hydration mismatch message
            hydrationMismatchMessage = message;
        } else {
            // If it's not a hydration mismatch, call the original console.warn
            console.warn(message);
        }
    });
});

afterEach(() => {
    // Restore original console.warn after each test
    jest.restoreAllMocks();

    // Check if a hydration mismatch occurred and fail the test if so
    if (hydrationMismatchOccurred) {
        throw new Error(`Test failed due to hydration mismatch: ${hydrationMismatchMessage}`);
    }
});
```

To run a client-side test, add a script to your `package.json`. You can alternatively use `jest --selectProjects <project_name>` to target specific test suites.

```
"scripts": {
    "test:ssr:client": "jest --no-cache --projects=./example-ssr/jest.ssr-client.config.js"
}
```

Client-side tests use [server-side snapshots](#ssr-unit-tests) to validate your components' post-hydration behavior, like this:

1. Read server-side-generated snapshots.
2. Insert the pre-rendered markup into the DOM.
3. Hydrate the component and validate its behavior in the client environment.

By comparing pre- and post-hydration markup, SSR client-rendering testing helps identify potential performance issues early on. It helps you address inconsistencies, layout shifts and inefficiencies before they affect your overall user experience.

## Next Steps

Now that you've...

- Configured your components for SSR
- Aligned them with the SSR best practices
- Evaluated them in SSR testing environments

...you can enable SSR for a page of your LWR site by following the instructions in [Enable SSR for LWR Apps](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-enable-ssr-site.md). If you have an Experience Cloud site, review [Hydration Capabilities for Islands (Experience Cloud)](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-ssr-hydration-experience-cloud.md) instead.

Enabling SSR for an entire page is a **prerequisite** for configuring a single component island for SSR.

<!-- document id=af18f416f3bbb4dd4e35512811e28fa68e71039f5c050cbbed0d213302c80420 url=/developer/current/en-us/lwr-node/lwr/guides/resolve-errors.md -->

# Troubleshooting Guide

Want to resolve an error thrown by Lightning Web Runtime (LWR) on Node.js or an LWR package? Find the error message on this page and follow the corresponding guidance.

The error messages are grouped by which LWR package they're related to. To quickly navigate to the error message you want, use the Table of Contents in the right sidebar or your browser's **Find** tool.

## General LWR Errors

**`Unable to load configurable module: ${filepath}`**

The error message returns all the modules that don't exist or fail to transpile.

Review your app's config file (`lwr.config.json`) and make sure that it sets only the following configurations as modules:

- `hooks`
- `route.routeHandler`
- `moduleProviders`
- `viewProviders`
- `viewTransformers`
- `assetProviders`
- `assetTransformers`
- `resourceProviders`

<!--
**`EADDRINUSE` - `HMR Socket Server: Port ${this.context.appConfig.port} already in use.`**

**`errorRoute` - `[view-middleware] Route Error ${req.originalUrl}`**

**`DiagnosticsError` - `LWR Diagnostic Error: err.message`**

**`[SSG] Error occurred processing asset config:`** -->

## @lwrjs/auth-middleware

**`${MESSAGE_PREFIX}could not authenticate. Error body:{text}`**

The middleware tried to [request an access token](https://help.salesforce.com/s/articleView?id=xcloud.remoteaccess_oauth_web_server_flow.htm) from the configured Salesforce connected app, but the OAuth endpoint returned an error.

To identify the source of the error, use the `Error body` text. For example, if the error message reports `OAuth not set up correctly`, you should review your OAuth settings for issues.

## @lwrjs/diagnostics

**`LwrConfigValidationError` - `Configuration validation errors in ${SOURCE_BY_PHASE[phase]}`**

This error message returns `"message"` text with specific information about where the issue is located in your code. To resolve this error, make sure your app config:

- Contains only valid JSON
- Contains only valid properties
- Matches the config interface

**`LwrUnresolvableError [DiagnosticsError]: 404: Could not find {item} at "{filepath}"`**

This package returns this error when a module, bundle, resource, asset, or view wasn't found for a given specifier.

Make sure the content you're referencing is configured properly, and ensure that the filepath printed in this error message points to the correct resource.

**`LwrServerError [DiagnosticsError]: An error occurred during warmup: {error text}`**

The server failed to load configured modules into the runtime cache during startup or warmup. Use the `error text` printed in this message to identify which module or modules failed to load and why.

Warmup only occurs when the `WARMUP` environment variable is set to `true`.

**`invalidMode` - `No configuration found for server mode - ${mode}`**

Your configured [server mode](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-get-started.md#set-the-lwr-server-modes) has to be `dev`, `prod`, `compat`, or `prod-compat`. Check your server mode and ensure it's set to one of these values.

## @lwrjs/router

**`INVALID_MIXIN_CMP` - `{0} must be an Element type`**

LWR throws this error when you try to add NavigationMixin to an invalid resource. To correct this, add [NavigationMixin](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/navigationmixin.md) to specifically a Lightning web component.

**`MISSING_CONTEXT` - `Could not find context to perform navigation action.`**

To use the navigation actions [`navigate()`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/navigate.md) and [`generateUrl()`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/generateurl.md), you have to configure the `context` property. Set `context` to the stringified ID of the parent router container nearest to the component that's generating a URL.

The component that performs navigation actions has to be a descendant of a router (like [`<lwr-router-container>`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/lwr-router-container.html)) in the DOM. LWR throws this error when you set `context` to an invalid router container.

**`MULTIPLE_ROOTS` - `Router connection failed. There can only be one root router.`**

Router nodes like [`<lwr-router-container>`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/lwr-router-container.html) can be nested, but they can't be siblings in the DOM. Check your router node hierarchy to make sure it's valid.

**`MULTIPLE_CHILDREN` - `Could not add to the navigation hierarchy. There can only be one child per navigation node.`**

Router nodes can have a maximum of one child. Make sure each of your routers has one child or no children.

**`MISSING_ROUTE` - `A route cannot be created to navigate to URL "{0}"`**

The page reference or URL passed to [`navigate()`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/navigate.html) or [`generateUrl()`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/generateurl.html) is invalid. Use the URL from the error message to identify the resource that's triggering this error, then correct it.

**`MISSING_URL` - `A URL cannot be created to navigate to route "{0}"`**

The page reference or URL passed to [`navigate()`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/navigate.html) or [`generateUrl()`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/generateurl.html) is invalid. Use the URL from the error message to identify the resource that's triggering this error, then correct it.

**`PRENAV_FAILED` - `A preNavigate hook listener blocked routing to "{0}"`**

The `preNavigate` hook of the router blocked navigation to the given page reference or URL.

**`MISSING_ROUTE_TEMPLATE` - `A route definition must contain a "uri" property.`**

To configure routing for your app, you have to set the `uri` property for all of your route definitions. For more information about valid values for `uri`, see [`RouteDefinition`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/routedefinition.md) or [`LwrConfigRouteDefinition`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/lwrconfigroutedefinition.md).

**`INVALID_ROUTE_QUERY` - `Invalid query param in route definition.`**

The query in the `uri` property of a route definition is invalid. Review and correct your query. For more information about valid values for `uri`, see [`RouteDefinition`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/routedefinition.md) or [`LwrConfigRouteDefinition`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/lwrconfigroutedefinition.md).

**`MISSING_PAGE_BINDING` - `Route definition must provide page binding.`**

All route definitions configured for a router must have a `page` property. Review your route definitions to ensure that each one includes a `page`.

**`INVALID_PAGE_BINDING` - `Invalid page binding in route definition.`**

The `page` property of a route definition is invalid. For more information about valid values for `page`, see [`RouteDefinition`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/routedefinition.md) or [`LwrConfigRouteDefinition`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/lwrconfigroutedefinition.md).

**`INVALID_URI_SYNTAX` - `Invalid URI syntax. URI cannot contain *, +, (, ).`**

Remove any instances of `*`, `+`, `(`, and `)` from the URI that triggered this error.

**`VIEW_IMPORT_FAILED` - `Error importing view with name "{0}", failure was: {1}.`**

There was an error importing the module returned by the `update()` function of the route handler for the current route. This error message should include more specific information about the cause of the error.

**`VIEW_MISSING` - `Expected a view with name "{0}" in the viewset.`**

`RouteHandler.update()` tried to return a requested view, but the view is missing from the [`ViewSet`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/routedestination.html#viewset) returned by [`update()`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/update.html).

To resolve this error, make sure your `ViewSet` object for your `RouteDestination` contains the desired [`ViewInfo`](hhttps://developer.salesforce.com/docs/platform/lwr/references/csr-reference/routedestination.html#viewinfo) object. For more information about these objects, see [`RouteDestination`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/routedestination.html).

**`VIEW_IMPORT_FAILED_WITH_SPECIFIER` - `Error importing module "{0}" from view with name "{1}", failure was: {2}.**

There was an error importing the module returned by the [`update()`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/update.html) function of the route handler for the current route. This error message should include more specific information about the cause of the error.

**`NO_ROUTE_MATCH` - `A routing match cannot be found for {0}.`**

The page reference or URL passed to [`navigate()`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/navigate.html) or [`generateUrl()`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/generateurl.html) is invalid. Use the details in this error message to identify the input that's causing this error, and then correct it.

**`INVALID_ROUTE_HANDLER` - `Route definition "{0}" does not have a valid route handler module.`**

The route handler class for a route definition is invalid.

To resolve this issue, confirm that the route handler has a default export.

**`DESTINATION_NOT_FOUND` - `Route handler returned 404: Not Found.`**

The route handler [`update()`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/update.html) function for the current route returned a `404` error.

**`DESTINATION_ERROR` - `Route handler returned error status {0}: {1}.`**

The route handler [`update()`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/update.html) function for the current route returned a non-`404` error status.

**`NO_INIT_URL` - `Cannot initialize a server router without a "url".`**

A configuration without the required url property was passed to the `createServerRouter()` function. Define a URL for the server router.

## @lwrjs/lambda

**`unhandledRejection - Unhandled Rejection: {}`**

A promise threw an error during server execution. This error usually happens during server-side rendering.

If your component invokes an asynchronous task, make sure it doesn't attempt to execute non-portable APIs like `window` or `document`.

## @lwrjs/lwc-ssr

This section describes how to resolve errors caused by invalid server-side rendering (SSR) configurations. For information about setting up SSR for LWR apps, see [Server-Side Rendering](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-ssr.md).

**`Adding links during server-side rendering failed. Could not find the </head> tag.`**

LWR can't add links returned by [`getServerData`](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-enable-ssr-site.md#load-data-during-ssr) hooks to the page because it doesn't have a `<head>` tag. Add a `<head>` tag to the page's layout template.

**`Server-side rendering for "bad/cmp" failed. Falling back to client-side rendering. Reason: SSR Error`**

[`lwr.renderComponent()`](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-enable-ssr-site.md#opt-in-to-ssr) failed for the given component specifier because the component isn't portable. Review the error message for more details about the source of the issue.

## @lwr/src

**`Node version ${nodeVersion} is not one of LWR Lambda's supported versions`**

Upgrade `node` to a supported version. For information about which versions of `node` are valid, check out [`lwr/package.json`](https://www.npmjs.com/package/lwr?activeTab=code) and review the `node` entry in the `engines` section.

<!-- document id=b6c5413433ffb6854fa71ad85ca067345f4cc74d6c4176e4c5dfc1273a2275d4 url=/developer/current/en-us/lwr-node/lwr/guides/lwr-understanding-islands.md -->

# Understanding Islands

With SSR, HTML is rendered on the server and then sent to the client along with any JavaScript needed to hydrate it. **Hydration** refers to the process of adding interactivity to the component on the client side.

However, there’s a performance cost associated with loading and executing excess JavaScript. To counteract this issue, **islands architecture** lets you create islands of interactivity on a server-rendered page. Rather than an all-or-nothing approach where SSR or CSR is controlled at the page level, you have granular control over which components require hydration, with the remainder of the page being static HTML.

![Diagram of a simple LWR on Node.js page with islands.](https://developer.salesforce.com/docs/media/simple-islands-page.png)

**important:** To use islands architecture, you have to [enable SSR for your site](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-enable-ssr-site.md).

Note that a component must be hydrated if it contains dynamic content or is interactive, including:

- Overriding the render method of `LightningElement`
- Implementing the `renderedCallback` lifecycle hook (this function isn’t called during SSR)
- Using dynamically bound text or attributes that can change on the client (for example, `<h2>{dynamicText}</h2>`)
- Attaching events
- Composing other components that need to be hydrated (for example, `<template><c-form></c-form></template>`)

For LWR on Node.js, you can create custom components that use the following configurations.

## SSR with Hydration

Components render on the server side and get hydrated on the client side. They produce hydrated islands. This configuration is suitable for interactive components, like a carousel.

## SSR only

Components render on the server side. This configuration is suitable for static components (like images) that don't require hydration.

## CSR only

Components render on the client side. This configuration is suitable for components that rely on client-side APIs and data.

## Next Steps

Ready to set up islands architecture for an LWR on Node.js-only site? Follow the steps in [Implement SSR Using Islands Architecture](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-ssr-islands-implementation.md).

**See Also**

- [patterns.dev: Islands Architecture](https://www.patterns.dev/vanilla/islands-architecture)

<!-- document id=a145be251244f404dd8e8b627135099c7c523c3684832a14d1caf1eef4bf7287 url=/developer/current/en-us/lwr-node/lwr/guides/lwr-lbc-styling.md -->

# Update Lightning Base Components Styling

Lightning base components implement Salesforce Lightning Design System (SLDS) component blueprints and styling. The base components are available as Aura components and Lightning web components (LWC). Only the LWC versions of the base components work in LWR.

For SSR environments, base components can render in native shadow DOM or [light DOM](https://developer.salesforce.com/docs/platform/lwc/guide/create-light-dom.html). Be aware that native shadow blocks global styles from being applied to individual components, which means that your existing styling rules sometimes don’t work as expected anymore. For a list of base components that support SSR, see [Use Supported Lightning Base Components](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-portable-best-practices.md#use-supported-base-components).

To achieve your styling goals in native shadow, use SLDS styling hooks that are assigned to specific parts of the component with the [`::part` CSS pseudo function](https://developer.mozilla.org/en-US/docs/Web/CSS/::part).

Here’s an example of how you can modify your existing styling rules. Let's say you use SLDS styling hooks to customize the text colors on your buttons.

```css
div.privacy lightning-button {
  --slds-c-button-brand-text-color-active: rgb(255, 255, 255);
  --sds-c-button-text-color: rgb(255, 255, 255);
  --slds-c-button-brand-text-color-hover: rgb(211, 211, 211);
  --sds-c-button-text-color-hover: rgb(211, 211, 211);
}
```

In this example, the values aren’t applied to `lightning-button`. The `lightning-button` component's internals become untargetable because of the native shadow boundary.

The previous example renders the following result:

![Website that renders "got it" button text in blue instead of white.](https://developer.salesforce.com/docs/media/lbc-shadow-example.png)

In the footer, the **got it** button text renders in blue instead of white.

To fix this styling issue, apply `::part(button)` with the same rules:

```css
div.privacy lightning-button::part(button) {
  --slds-c-button-brand-text-color-active: rgb(255, 255, 255);
  --sds-c-button-text-color: rgb(255, 255, 255);
  --slds-c-button-brand-text-color-hover: rgb(211, 211, 211);
  --sds-c-button-text-color-hover: rgb(211, 211, 211);
}
```

Using `::part(button)` results in the correct styles getting applied to the button.

![Website that correctly renders "got it" button.](https://developer.salesforce.com/docs/media/lbc-part-example.png)

**See Also**

- Lightning Design System: [Styling Hooks on SLDS Components](https://lightningdesignsystem.com/components/buttons/#Styling-Hooks-Overview)
- Lightning Design System: [Styling Hooks](https://www.lightningdesignsystem.com/platforms/lightning/styling-hooks/)

<!-- document id=3984b9732181bdfada05460b75338e3a4de245aca87184bb945a6c59c53b7155 url=/developer/current/en-us/lwr-node/lwr/references/csr-reference/update.md -->

# update()

Provides a set of views for the current location.

## Properties

| Method Input                        | Required/Optional | Description                                                                                                                                         |
| ----------------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`RouteInstance`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/routeinstance.md) | Required          | Each `RouteInstance` contains a [`PageReference`](https://developer.salesforce.com/docs/platform/lwr/references/csr-reference/pagereference.md) object. The route handler uses `RouteInstance` to determine which view to show. |

## Syntax

```javascript
update(routeInfo: RouteInstance): void {
    this.callback({
        viewset: {
            default: () => import('example/home'),
        },
    });
}
```

## Signature

```javascript
public void update(routeInfo: RouteInstance)
```

## Returns

- None

**See Also**

- [Route Handler Modules](https://developer.salesforce.com/docs/platform/lwr/guides/lwr-route-handler-modules.md#update)
- [Simple Routing Example: Create a Route Handler](https://developer.salesforce.com/docs/platform/lwr/guides/lwr-routing-example-simple.md#create-a-route-handler)

<!-- document id=e2658fbdf1560ea019819b97c3fccb28353780aeb79b695b309a6d74c96cebcf url=/developer/current/en-us/lwr-node/lwr/guides/lwr-lwc.md -->

# Use Lightning Base Components with LWR on Node.js

**important:** Lightning base components are currently **unavailable** via Node Package Manager (NPM). We're working on bringing them back. Stay tuned for updates.

Lightning base components (https://developer.salesforce.com/docs/component-library/overview/components) are out-of-the-box building blocks for user interfaces like LWR sites. To use base components in your LWR application, set up the [lightning-base-components](https://www.npmjs.com/package/lightning-base-components) package in your project.

## Set up Lightning Base Components

**important:** Before you begin, [**you have to configure the Salesforce Lightning Design System ("SLDS")** with your app](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-slds.md). Base components are built on SLDS.

### 1. Add a lightning-base-components dependency

Open your project's `package.json` file. In `dependencies`, add a dependency for the `lightning-base-components` package. Check [npm: lightning-base-components](https://www.npmjs.com/package/lightning-base-components) for the latest stable version of the package.

```
{
  "dependencies": {
    "lwc": "^6.2.0",
    "lwr": "0.11.13",
    "lightning-base-components": "^1.21.6-alpha"
  }
}
```

### 2. Declare the lightning-base-components package

Open your project's `lwr.config.json` file. To make the `lightning-base-components` npm package available to your LWR app, add an entry for it in the `lwc` module.

```
{
  "lwc": {
    "modules": [{ "npm": "lightning-base-components" }]
  }
}
```

**note:** For more information about what your `lwr.config.json` file does, check out [Understand lwr.config.json](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-configure-project.md#understand-lwrconfigjson).

### 3. Optional: Specify a layout template

If you’re creating your own [layout template](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-templates.md), include the [`lwr_resources`](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-compile-data.md#lwr) context object property in `lwr.config.json`.

If you’re _not_ creating your own layout template, LWR creates a default template for you that already includes `lwr_resources`. You don't have to do anything for this step!

### 4. Pull in Lightning Base Components

Run `npm install` in your terminal to pull the base components from the `lightning-base-components` NPM repo to your project.

Now you can start using base components in your project.

### 5. Run your app

Run the following terminal commands from the root of your project:

```bash
npm run build
npm run start
```

**tip:** Read [Get Started with LWR](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-get-started.md#set-the-lwr-server-modes) for details on LWR's NPM commands.

Open a local preview of your site at http://localhost:3000. If you're already using port 3000 for something else, review your terminal output for the alternative port being used.

## Example: lightning-button

Once you've enabled SLDS and LWC for an LWR app, you can add base components to it. This process requires revising and creating a few more files in your project.

Let's take a look at StaticSite, a simple LWR single-page app (SPA) that contains one [`lightning-button`](https://developer.salesforce.com/docs/component-library/bundle/lightning-button/example) component. Here's what the site looks like in the browser with the developer console open.

![Screenshot of StaticSite with developer console view.](https://developer.salesforce.com/docs/media/example-LBC-site.png)

This is the file structure of the StaticSite project. Certain files had to be updated or created to support the `lightning-button` base component. We'll dig into those changes below.

```
scripts/
  └── copy-slds.mjs
src/
  ├── assets/             // NEW - generated at build time, stores SLDS resources sent from copy-slds.mjs
  ├── layouts/
  │   └── main.njk        // home page structure and link to SLDS stylesheet
  ├── modules/            // NEW - contains component folders
  │   └── example/
  │       └── app/
  │           └── app.css // optional
  │           └── app.html
  │           └── app.js
  │       └── button/
  │           └── button.html
  │           └── button.js
  ├── lwr.config.json     // CHANGED - configures SLDS and Lightning base components
  ├── package.json        // creates dependencies on SLDS and Lightning base components
  └── index.ts            // LWR server startup script
site/                     // NEW - generated at build time
node_modules/
__lwr_cache__/            // NEW - generated at build time
```

### modules/

StaticSite has a `modules` folder that contains the app's components, `button` and `app`.

#### `modules/example/button/`

The button component displayed on StaticSite is descended from the `lightning-button` base component in `node_modules`.

```
import { LightningElement } from 'lwc';

export default class Button extends LightningElement {
  handleClick(event) {
    console.log(`You clicked the "${event.target.label}" button`);
  }
}
```

To customize this button for StaticSite, set properties on the element in `button.html`.

```
<template>
  <lightning-button variant="brand" label="Click Me" title="Primary action" onclick={handleClick}
    class="slds-m-left_x-small"></lightning-button>
</template>
```

#### `modules/example/app/`

The `app` component configures what content renders on the home page. You can optionally have an `app.css` file for styling.

When you reference a component from `modules`, the naming syntax is `<parent folder-component name.>` For example, the StaticSite `button` component is declared in `app.html` as `<example-button>`.

```
<template>
  <main>
    <header>
      <h1 class="slds-text-heading_medium slds-m-bottom_medium">SLDS and Lightning Base Components</h1>
    </header>
    <example-button></example-button>
  </main>
</template>
```

```
import { LightningElement } from 'lwc';

export default class StylesApp extends LightningElement { }
```

### lwr.config.json

The project's config file was updated to include the `dir` module for `lwc` that points to the new `modules` folder. `lwr.config.json` also contains `rootComponent` property in `routes` that points to the new `app` component.

```
{
    "lwc": {
        "modules": [
            {
                "dir": "$rootDir/src/modules"
            },
            {
                "npm": "lightning-base-components"
            }
        ]
    },
    "routes": [
        {
            "id": "Home",
            "path": "/",
            <!-- Changed contentTemplate to rootComponent that points to app folder in modules/example -->
            "rootComponent": "example/app",
            "layoutTemplate": "$layoutsDir/main_layout.njk",
            "bootstrap": {
                "syntheticShadow": true
            }
        }
    ],
    "assets": [
        {
            "alias": "assetsDir",
            "dir": "$rootDir/src/assets",
            "urlPath": "/public/assets"
        },
        {
            "alias": "favicon",
            "file": "$rootDir/src/assets/favicon.ico",
            "urlPath": "/favicon.ico"
        },
        {
            "file": "$rootDir/src/assets/utilitySprite.svg",
            "urlPath": "/lightning.utilitySprite"
        }
    ]
}
```

### Content Generated at Build Time

After StaticSite gets built, LWR adds the following automatically generated files to the project.

- `node_modules`
  - Contains packages corresponding to project dependencies (like `@salesforce-ux` and `lightning-base-components`).
- `site`
  - Files generated by the `build` command.
- `__lwr_cache__`
  - Assets and modules generated by the `build` command.

<!-- document id=dd98eaaaf23fd4572b50b8dd7220cb4a5972c1b7fedbc2df0043acb731c365bd url=/developer/current/en-us/lwr-node/lwr/guides/lwr-slds.md -->

# Use Salesforce Lightning Design System with LWR

You can use the [Salesforce Lightning Design System (SLDS)](https://www.lightningdesignsystem.com/getting-started/) to style your LWR site. Setting up SLDS for an LWR app lets you add base components to your app. You have to enable SLDS before you can pull over base components.

## Prerequisites

Before you can start using SLDS to customize your site, make sure your project has a layout template in your `src/layouts` directory. For more information, see [Content and Layout Templates in LWR on Node.js](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-templates.md).

Then, follow these steps to make SLDS available to your app.

## 1. Create an SLDS package dependency

In `package.json`, add a dependency on `@salesforce-ux/design-system` to the `devDependencies` section. Check [npm: @salesforce-ux/design-system](https://www.npmjs.com/package/@salesforce-ux/design-system) for the latest stable version of the package.

```
{
    "devDependencies": {
        "@salesforce-ux/design-system": "^2.22.2"
    }
}
```

## 2. Copy SLDS resources with a script

To ensure your project uses the latest compatible version of the SLDS package, we recommend using a script to copy SLDS resources into your app every time you run `npm run build`.

1. Make sure you have a `scripts` folder at the top level of your project.
2. In the `scripts` folder, create a new file called `copy-slds.mjs` and add your build script. Here's an example script:

   ```
import cpx from 'cpx';
    cpx.copy('./node_modules/@salesforce-ux/design-system/assets/**/*', 'src/assets', () => {
        console.log('Done copying SLDS resources');
    });
```

3. In `package.json`, add a dependency on the `cpx` package to `devDependencies` and update the `build` script to run `copy-slds.mjs`. To ensure that SLDS resources copy over before your site gets built, make sure you run the `copy-slds` script before `lwr build`.

   ```
"scripts": {
       "build": "node ./scripts/copy-slds.mjs && lwr build --clean"
   }

   "devDependencies": {
       "@salesforce-ux/design-system": "^2.22.2",
       "cpx": "1.5.0"
   },
```

## 3. Link your layout template to SLDS stylesheets

In your app's static layout template, add or change the `link` to point to the SLDS stylesheets. The layout template can be an `.html` or a `.njk` file.

```
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
        <title>LWR + SLDS Example</title>

        <!-- Point to SLDS stylesheet -->
        <link rel="stylesheet" href="$assetsDir/styles/salesforce-lightning-design-system.css" />

    </head>
    <body>
        {{ body | safe }} // context object property,
        {{ lwr_resources | safe }}
    </body>
</html>
```

For more information about the context object properties `body` and `lwr_resources`, see [Compile-Time Data: LWR](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-compile-data.md#lwr)

## 4. Update the config file to support SLDS

1.  In the `routes` section of the file, configure the `bootstrap` property to set the `syntheticShadow` property to `true`. Enabling `syntheticShadow` lets the SLDS stylesheet function as global styles.

    ```
"routes": [
        {
            "id": "Home",
            "path": "/",
            "contentTemplate": "$contentDir/home.md",
            "layoutTemplate": "$layoutsDir/main_layout.njk",

            // Configure the bootstrap property to enable syntheticShadow for this page
            "bootstrap": {
                "syntheticShadow": true
            }
        }
    ]
```

2.  If they don't already exist, add the `/assets` and `/utility-sprite` paths to SLDS stylesheets and images, respectively, to allow browser access.

    ```
"assets": [
        {
            "alias": "assetsDir",
            "dir": "$rootDir/src/assets",
            "urlPath": "/assets"
        },
        {
            "file": "$rootDir/src/assets/icons/utility-sprite/svg/symbols.svg",
            "urlPath": "/lightning.utilitySprite"
        }
    ]
```

## Optional: Update .gitignore

If you initialized your project as a git repo, this step applies to you!

The LWR `build` command generates a few very large folders in your repo. For example, LWR creates two `assets` folders (that each contain over 4,000 files) in your project directory at build time.

To easily avoid adding unnecessary content to your repo, we recommend revising your `.gitignore` to exclude certain folders.

```
node_modules
__lwr_cache__
src/assets
.DS_Store
site
```

## 5. Run your app

Run the following terminal commands from the root of your project:

```bash
npm install
npm run build
npm run start
```

Read [Get Started with LWR](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-get-started.md#set-the-lwr-server-modes) for details on LWR's NPM commands.

Open the site at http://localhost:3000. If you're already using port 3000 for something else, review your terminal output for the alternative port being used.

## Next Steps

Now that you've set up SLDS for your LWR site, you can configure your app to use Lightning base components. Base components run on SLDS, so you have to enable SLDS before you can add components to your site.

To start adding LWC to your LWR app, take a look at [Use Lightning Base Components with LWR on Node.js](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-lwc.md).

<!-- document id=f1b50ef7f0b945bd7e712459c9f49aca63dc29727ac985d6b191b5ef228b62e1 url=/developer/current/en-us/lwr-node/lwr/guides/lwr-what-is-ssr.md -->

# What is Server-Side Rendering?

With client-side rendering (CSR), all the HTML, JavaScript, CSS, images, and other assets that make up the page are downloaded to the client, and then the computation required to produce the rendered page is done within the browser.

But with SSR, the browser doesn’t need to wait for all the JavaScript to download and execute before it can display the component markup. Moving computation to the server lets the resulting page get cached in the CDN for subsequent visitors.

More benefits of SSR include:

- faster time-to-content
- improved SEO data freshness — data will be available whenever search engines crawl the site

![Diagram comparing the First Contentful Paint (FCP), Largest Contentful Paint (LCP), and Time to Interactive (TTI) of client-side and server-side rendering processes.](https://developer.salesforce.com/docs/media/csr-vs-ssr.png)

## Implement SSR Page-By-Page

There are two ways to add SSR functionality to your site. One way is to enable SSR on a page-by-page basis. This means that you choose which pages to render on the server-side, and which to render on the client-side.

To learn how to turn on SSR for a page of an LWR on Node.js-only site, review [Enable SSR for LWR Apps](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-enable-ssr-site.md).

## Implement SSR with Islands

If you want more granular control over which specific components on a page get SSRed, take a look at [Understanding Islands](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-understanding-islands.md). LWR supports **islands architecture**, which lets you determine whether components are server-rendered, server-rendered with hydration, or client-rendered. **Hydration** adds interactivity to a component on the client side.

Before you can set up islands on a page, you have to enable SSR for the entire page.

## Next Steps

Before you enable SSR for your site, you have to make sure your components are SSRable. This process involves auditing, editing, and testing your components. To get started, visit [Configure Components for SSR](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-configure-component-ssr.md).