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.

{
    "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.

    <!-- 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>

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

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:

npm install
npm run build
npm 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.