Over the weekend, I thought about the design systems in the context of Lightning Web Component.
In large Salesforce implementations, especially Experience Cloud, for industries such as banking, financial services, insurance, and retail, companies build their own component libraries and design systems on top of a standard Lightning component library.
Usually, it's a set of components with some common name prefix to differentiate from the rest of the metadata.
It might serve its purpose, but as the implementation grows, eventually, the development experience becomes poor.
Such component libraries become hard to maintain and use.
The documentation is non-existent, and following the guidelines and government process is challenging.
As a short recap, I haven't come up with any solution yet, but I would like to outline some of my thoughts in this post.
Contents
Visual Regression Testing
Jest Snapshot Testing
First, I started thinking about the challenges with the visual regression testing.
Lightning Web Components implements a Jest testing framework.
Salesforce has its own NPM package called sfdx-lwc-jest to run Jest against the Lightning Web Components in a Salesforce DX workspace environment.
Jest is great for unit testing.
Currently, you can also validate the component snapshots.
It works as follows. We can render the components, capture the DOM output, and compare them against the saved snapshots.
It's a straightforward and fast way to detect structural changes quickly.
However, the limitation is that it cannot capture the visual changes, e.g., CSS overflows, color variations, etc.
Image Snapshot Testing
For that purpose, we can run visual regression testing.
The difference is that it captures the visual data (screenshots) for pixel-by-pixel comparisons.
The primary purpose is to ensure the UI components and pages remain consistent.
It can detect subtle visual changes, and you can use it across different browsers and resolutions.
Some time ago, I worked on the Nordea Common Component's library, which was used across many teams and served millions of users, so it's critical to make sure none of the changes in the library introduce visual regression bugs.
Regulated industry and legal accessibility requirements make it crucial.
I came to a point where I would also like to implement such testing in the Salesforce LWC context.
That's where the challenges started to arise.
Because LWC is something you mainly use in the Salesforce DX projects, adding customizations on top of that is quite limited.
I've tried implementing the visual regression testing using the Jest, Puppeteer, and Playwright.
I also tried the jest-image-snapshot library maintained by American Express.
Unfortunately, I couldn't build a quick working proof of concept with that.
Storybook
One of the biggest challenges was lacking a proper local environment to serve the LWCs.
One thing that came to mind was using a Storybook.
It's an excellent tool for having component documentation and examples and running visual regression tests.
We used that at Nordea, which is what Salesforce uses now for their Lightning Design System 2.
I quickly explored the ready-made solutions and even found some implementations on GitHub.
Funny enough, I cloned one of the repositories but couldn't install libraries as it used the internal Salesforce NPM registry and required a local SF network to connect.
Overall, it's possible to make this thing work, but it would require more effort than spending some spare time on the weekend.
Framework-Agnostic Component Library
After spending more time creating something meaningful, I questioned myself: Why do we even have to maintain a component library as Lightning Web Components?
Isn't it better to use other popular and well-maintained web component frameworks, like Stencil and Lit, to implement a framework-agnostic design system?
It's the web component at the end of the day, and once it's registered as a custom element, you can use it inside any web application.
Trying to fix everything in LWC didn't make sense, and it was much better to spin up a separate component library project with Stencil.
It enforces a separation of concerns since you can decouple it from the rest of the Salesforce metadata, and a separate team could own and maintain that library.
It will have its own development and deployment lifecycle.
The main idea was to have a library of base components that you could use in the Salesforce domain and other applications.
You can keep more complex components requiring Salesforce data and API usage as LWCs.
Using Third-party Components in LWC
For example, in the case of a bank, the self-service Experience Cloud customer portal or insurance claim flow and online bank application can benefit from using a shared component library to reduce bugs, maintenance, and development costs, as well as enforce style guidelines.
Unfortunately, it also became a challenge in Salesforce.
You cannot just register and render any web components in the Experience Cloud.
In the LWC framework, it is now possible to use third-party components via the lwc:external attribute, but it's in the Beta stage.
Unfortunately, the API and developer experience is relatively poor, and Salesforce doesn't support third-party components or endorse their use.
Generally, you would need to load the web components via the loadScript method and register and define native web components directly.
Some of the known issues are:
- Load script method doesn't support
<script type="module">. - LWC doesn't support importing from NPM.
- Components that reference elements by IDs aren't supported in the shadow DOM. The LWC cannot access the global HTML document.
- Experience Builder doesn't support third-party web components when Lightning Web Security (LWS) is enabled.
Conclusion
As mentioned, some Salesforce implementations demand you implement and maintain a component library.
In return, it introduces several challenges, such as developer experience and quality assurance.
Maintaining a third-party base component library may be a valid use case to overcome the testing issues and build sound and reliable components for complex implementations.
As a result, you can get a reliable, well-tested, maintained, and documented base component library that you could release independently and reduce the development burden from Salesforce teams.
My biggest concern is the LWS, as it's recommended that it be enabled for better security.
I will continue investigating that path.
I don't have such a requirement at the moment, but I hope there will be a valid production case in the future.
I'm also curious to hear from the others.
If you have experience implementing visual regression tests or Storybook for LWCs or serving third-party web component libraries in Salesforce, please get in touch with me!
Nikita Verkhoshintcev
Senior Salesforce Consultant
I'm a senior Salesforce consultant based in Helsinki, Finland, specializing in Experience Cloud, Product Development (PDO), and custom integrations. I've worked as an independent consultant building custom Salesforce communities and applications since 2016. Usually, customers reach out to me because of my expertise, flexibility, and ability to work closely with the team. I'm always open to collaboration, so feel free to reach out!
