Use Lightning Base Components with LWR on Node.js

Lightning base components are currently unavailable via Node Package Manager (NPM). We’re working on bringing them back. Stay tuned for updates.

Important

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 package in your project.

Set up Lightning Base Components

Before you begin, you have to configure the Salesforce Lightning Design System (“SLDS”) with your app. Base components are built on SLDS.

Important

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 for the latest stable version of the package.

1{
2  "dependencies": {
3    "lwc": "^6.2.0",
4    "lwr": "0.11.13",
5    "lightning-base-components": "^1.21.6-alpha"
6  }
7}

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.

1{
2  "lwc": {
3    "modules": [{ "npm": "lightning-base-components" }]
4  }
5}

For more information about what your lwr.config.json file does, check out Understand lwr.config.json.

Note

3. Optional: Specify a layout template

If you’re creating your own layout template, include the lwr_resources 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:

1npm run build
2npm run start

Read Get Started with LWR for details on LWR’s NPM commands.

Tip

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 component. Here’s what the site looks like in the browser with the developer console open.

Screenshot of StaticSite with developer console view.

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.

1scripts/
2  └── copy-slds.mjs
3src/
4  ├── assets/             // NEW - generated at build time, stores SLDS resources sent from copy-slds.mjs
5  ├── layouts/
6  │   └── main.njk        // home page structure and link to SLDS stylesheet
7  ├── modules/            // NEW - contains component folders
8  │   └── example/
9  │       └── app/
10  │           └── app.css // optional
11  │           └── app.html
12  │           └── app.js
13  │       └── button/
14  │           └── button.html
15  │           └── button.js
16  ├── lwr.config.json     // CHANGED - configures SLDS and Lightning base components
17  ├── package.json        // creates dependencies on SLDS and Lightning base components
18  └── index.ts            // LWR server startup script
19site/                     // NEW - generated at build time
20node_modules/
21__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.

1import { LightningElement } from 'lwc';
2
3export default class Button extends LightningElement {
4  handleClick(event) {
5    console.log(`You clicked the "${event.target.label}" button`);
6  }
7}

To customize this button for StaticSite, set properties on the element in button.html.

1<template>
2  <lightning-button variant="brand" label="Click Me" title="Primary action" onclick={handleClick}
3    class="slds-m-left_x-small"></lightning-button>
4</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>.

1<template>
2  <main>
3    <header>
4      <h1 class="slds-text-heading_medium slds-m-bottom_medium">SLDS and Lightning Base Components</h1>
5    </header>
6    <example-button></example-button>
7  </main>
8</template>

1import { LightningElement } from 'lwc';
2
3export 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.

1{
2    "lwc": {
3        "modules": [
4            {
5                "dir": "$rootDir/src/modules"
6            },
7            {
8                "npm": "lightning-base-components"
9            }
10        ]
11    },
12    "routes": [
13        {
14            "id": "Home",
15            "path": "/",
16            <!-- Changed contentTemplate to rootComponent that points to app folder in modules/example -->
17            "rootComponent": "example/app",
18            "layoutTemplate": "$layoutsDir/main_layout.njk",
19            "bootstrap": {
20                "syntheticShadow": true
21            }
22        }
23    ],
24    "assets": [
25        {
26            "alias": "assetsDir",
27            "dir": "$rootDir/src/assets",
28            "urlPath": "/public/assets"
29        },
30        {
31            "alias": "favicon",
32            "file": "$rootDir/src/assets/favicon.ico",
33            "urlPath": "/favicon.ico"
34        },
35        {
36            "file": "$rootDir/src/assets/utilitySprite.svg",
37            "urlPath": "/lightning.utilitySprite"
38        }
39    ]
40}

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.

Developer Preview Feature

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