Use Salesforce Lightning Design System with LWR

You can use the Salesforce Lightning Design System (SLDS) 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.

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

1{
2    "devDependencies": {
3        "@salesforce-ux/design-system": "^2.22.2"
4    }
5}

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.

Make sure you have a scripts folder at the top level of your project.

In the scripts folder, create a new file called copy-slds.mjs and add your build script. Here’s an example script:

1import cpx from 'cpx';
2 cpx.copy('./node_modules/@salesforce-ux/design-system/assets/**/*', 'src/assets', () => {
3     console.log('Done copying SLDS resources');
4 });

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.
package.json
1"scripts": { 2 "build": "node ./scripts/copy-slds.mjs && lwr build --clean" 3} 4 5"devDependencies": { 6 "@salesforce-ux/design-system": "^2.22.2", 7 "cpx": "1.5.0" 8},

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.

1<!DOCTYPE html>
2<html lang="en">
3    <head>
4        <meta charset="utf-8" />
5        <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
6        <title>LWR + SLDS Example</title>
7
8        <!-- Point to SLDS stylesheet -->
9        <link rel="stylesheet" href="$assetsDir/styles/salesforce-lightning-design-system.css" />
10
11    </head>
12    <body>
13        {{ body | safe }} // context object property,
14        {{ lwr_resources | safe }}
15    </body>
16</html>

For more information about the context object properties body and lwr_resources, see Compile-Time Data: LWR

4. Update the config file to support SLDS

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.

1"routes": [
2    {
3        "id": "Home",
4        "path": "/",
5        "contentTemplate": "$contentDir/home.md",
6        "layoutTemplate": "$layoutsDir/main_layout.njk",
7
8        // Configure the bootstrap property to enable syntheticShadow for this page
9        "bootstrap": {
10            "syntheticShadow": true
11        }
12    }
13]

If they don’t already exist, add the /assets and /utility-sprite paths to SLDS stylesheets and images, respectively, to allow browser access.

1"assets": [
2    {
3        "alias": "assetsDir",
4        "dir": "$rootDir/src/assets",
5        "urlPath": "/assets"
6    },
7    {
8        "file": "$rootDir/src/assets/icons/utility-sprite/svg/symbols.svg",
9        "urlPath": "/lightning.utilitySprite"
10    }
11]

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.

1node_modules
2__lwr_cache__
3src/assets
4.DS_Store
5site

5. Run your app

Run the following terminal commands from the root of your project:

1npm install
2npm run build
3npm run start

Read Get Started with LWR 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.

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.