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.

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.

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.

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:

  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.

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.

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

  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.

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

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.

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

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.

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.