Creating a Custom Web Component Library

A real-life roadmap for building a design system — Pt II

The Challenge 🍝

The JW Player enterprise dashboard is a robust product that many of our users rely on for their daily workflows. It provides a GUI for our APIs, allows customers to manage their tools and content throughout every stage of our platform — video players, ad schedules, live stream events, etc — it operates conditionally based on user entitlements, and handles sensitive billing and account data.

The Solution 💫

If you’ve worked with any number of modern Javascript tools, you’re probably familiar with the concept of components: collections of HTML, JS & CSS that define modular pieces of UI and UX.

  • A UI component is always product-agnostic
  • A UI component is always framework-agnostic
  • A UI component is reusable

A Tale of 2 Storybooks 📕

Storybook is a platform that allows you to develop components in isolated environments without the need for a complex dev stack, database connections, or the need to dig through browser dev tools to force an element into a specific state.

Storybook interfaces for date-picker, loading spinner & select input
Event logs for buttons and tags

Scalability Roadblocks

The heaviest burden of this first iteration became the requirement to develop and maintain two concurrent builds of Storybook: one for Angular and one for React. The React side experienced some neglect as time-sensitive Angular dashboard tickets took precedence, and it was a challenge to keep releases coordinated.

The Case for Web Components 🕸

We were 2/3 on our golden rules — we had achieved reusable and product-agnostic — but to be truly framework agnostic, we also had to support the projects that use no framework at all. Web components to the rescue!

Building with Stencil

Our research on web component implementation led us to Stencil, a system that combines the best concepts of the most popular front-end frameworks into a compile-time rather than runtime tool. It takes TypeScript, JSX, a tiny virtual DOM layer, efficient one-way data binding, an asynchronous rendering pipeline (similar to React Fiber), and lazy-loading out of the box, and it generates 100% standards-based web components that run in any browser supporting the Custom Elements v1 spec.

Using WUI 🔧

Like Hook, WUI is consumable by CDN or our internal npm registry, so it’s easily accessible for all teams in our organization.

<script type="module" src="[version]/dist/wui/wui.esm.js"></script> <script nomodule src="[version]/dist/wui/wui.js"></script>
<wui-button type="tertiary" label="Play" icon="play" />
Importing components from WUI in React
Importing WUI components in React
Code examples of Typescript autocomplete features
Autocomplete support in VS Code

Creating an Intuitive API 🧠

WUI is built by engineers, for engineers. To be intuitive, consistent, and performant, its API must stay as close to the existing DOM API as possible. For example, wui-check-input accepts the propsdisabled and checked—both valid HTML attributes—which can be passed directly to our inner input element without extra configuration or translation.

Custom Props & Children

To discourage developers from passing incompatible child elements to any given component, we restrict the contents with strictly-typed props and construct the resulting HTML accordingly. Here’s an example of how we use a string label prop to guard against rogue child elements and remove the guesswork of populating a wui-button:

Code examples for right and wrong button implementation
Code detailing how to use <slot> syntax for dynamic child elements
<slot> usage for dynamic child elements
Modal example

Introducing Atlas 🗺

Atlas became everything we couldn’t pull off in Storybook at the time: a single, highly dynamic hub that showcases all of our available components more visually, with interactive documentation and changelogs for each release. It’s built with React & SCSS and is tested with Jest and Puppeteer.

WUI Atlas browse page
Example of an Alert component documentation
WUI Alert previews
Atlas playground example

The Payoff 🎉

At the time of writing this, WUI is at v7.3.0 and steadily growing. The Stencil-based web components approach has proven to be a great improvement on past iterations and has integrated seamlessly into our major codebases.

Next Up… 🧚‍♀️

In part 3, we’ll investigate how we use Hook, WUI, and other internal tools to improve design handoff and forge a stronger partnership between designers and engineers.



A technical blog about delivering online video at scale.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Kim Hart

Front-end engineer | design enthusiast | ISFJ | west coast kid | Brooklyn, NY