How we use Web Components at GitHub

At GitHub, we pride ourselves on delivering a first-class developer experience. A considerable part of our work is on our front end, which we strive to keep as lightweight, fast, and accessible as possible. For a product as large as GitHub, this can be quite the task. Like many front-end codebases, we leverage components, independent, isolated, and reusable pieces of code that allow application teams to deliver high fidelity UI quickly and efficiently while still keeping to our high standards of quality.

We’re using Web Components in a big way at GitHub. We have over a dozen open-source Web Components and with dozens more that are closed source.

How we got here

When GitHub launched over a decade ago, we had a modest front-end codebase that mostly used jQuery. Ten years and nearly 85,000 lines of code later, we had a large front-end codebase that was starting to show growing pains. We ultimately transitioned away from jQuery (for reasons which we detailed in a blog post at the time) and started using new technologies which could better solve our problems.

We began to dabble with a new technology called Web Components, a set of native browser technologies that allow the development of customized HTML elements, progressively enhanced with JavaScript.

We chose to use Web Components because our codebase was already structured into component-like behaviors. Still, as the GitHub monolith grew in size, we saw the need to implement better encapsulations before the front-end became unmanageable – and Web Components fit the bill. Web Components offered better portability and encapsulation than our existing JavaScript behaviors. We were happy to experiment with Web Components alongside our existing front-end infrastructure since it doesn’t incur any upfront cost or “buy-in” to a specific framework.

Our first two custom elements shipped in 2014: <relative-time> and <local-time>, which show times and dates in friendly formats, and <include-fragment>, which allows us to lazy load HTML fragments. Slowly we realized just how powerful these elements could be and began replacing design patterns within the codebase wholesale, such as replacing our “facebox” modal dialog pattern with <details-dialog>. Our components now range from very generic, multi-purpose behaviors like <remote-input> to specific single-purpose components such as the <markdown-toolbar> element and its siblings.

For the power Web Components affords, there are still pain points and pitfalls. With such a large codebase owned by hundreds of engineers across dozens of teams, we need to provide as much support and tooling as possible, encoding best practices without manual code review becoming a bottleneck.

Improving how we author components

To make engineers effective at writing high-quality Web Components—and encourage best practices—we’ve been working on a few tools to make authoring Web Components much easier.

ViewComponent

We’ve been transitioning our Rails code to using ViewComponent, a framework for building reusable components within Rails. ViewComponent goes hand-in-hand with Web Components since a ViewComponent can have a one-to-one relationship with a Web Component, allowing our developers to work on a single abstraction for both front-end and backend.

Catalyst

Catalyst, our open source library that makes it easier to write web components, has been a driving force that ties together some of our best practices. Catalyst leverages TypeScript to add decorators, which save on a lot of the boilerplate necessary to write Web Components.

Catalyst took inspiration from the excellent Stimulus library, and Google’s LitElement. It is designed to answer the specific set of needs our developers require. Our internal developer experience surveys have shown success in providing a substantial improvement in authoring code over legacy patterns.

You can read more about Catalyst and its conventions, patterns, and anti-patterns in our guide.

Tooling

We provide a set of open-source linter configurations for developers. For general code practices we have eslint-plugin-github. We also have eslint-plugin-custom-elements, which provides further checks for authoring Web Components. Extracting these to open source repositories allows us to remove code from the monolith but remain consistent.

We also have internal tests to verify that developers follow best practices and ensure that they don’t continue to use deprecated patterns and behaviors. One of our tests makes sure that a deprecated “facebox” pattern isn’t introduced to the codebase and suggests using a <details-dialog> element as an alternative.

class FaceboxDeprecationTest < Test::Fast::TestCase
  EXPECTED_NUMBER_OF_FACEBOXES = 44

  # Find facebox triggers set with rel=facebox, in either HTML attributes or
  # as part of hash assignment (for rails helpers)
  REGEX_FOR_FACEBOX_BINDING = %r|rel\s*[=:]>?\s*["']?facebox|
  REGEX_FOR_DATA_FACEBOX = %r|data-facebox\s*=>?\s*|

  def test_limit_facebox
    actual_rel_facebox = grep(REGEX_FOR_FACEBOX_BINDING, options: %w[-In], paths: %w[app/**/*.erb])
    actual_data_facebox = grep(REGEX_FOR_DATA_FACEBOX, options: %w[-In], paths: %w[app/**/*.erb])
    count = actual_rel_facebox.count("\n") + actual_data_facebox.count("\n")

    assert_operator count, :<=, EXPECTED_NUMBER_OF_FACEBOXES, <<-EOL
It looks like you added a facebox. Please use <details-dialog> instead.

If you must increment EXPECTED_NUMBER_OF_FACEBOXES in this test, please
/cc @github/ui-frameworks-reviewers in your pull request, as we may be able to help! Thanks.
EOL

    assert_equal EXPECTED_NUMBER_OF_FACEBOXES, count, <<-EOL
It looks like you removed a facebox. YOU ARE AWESOME! 💖 💖 💖 💖 💖
Please decrement EXPECTED_NUMBER_OF_FACEBOXES in this test and treat yourself to
something special.  You deserve it.
EOL
  end
end

Our new lifecycle of Web Components

The road from an application-specific front-end behavior to an open-source Web Component starts with a Catalyst component inside the monolith codebase. Components that are good candidates for extraction get generalized into a robust, strictly behavioral, dependency-free Web Component.

In the monolith, engineers might prototype ideas and ship them slowly using feature flags while continuously revising them. After the component has been tested in production for some time, we will look for opportunities to lift the component into its own repository. We also regularly assess the codebase to find reusable patterns, generic behaviors, or components that otherwise have a compelling reason to be lifted into their own repositories.

Start with Catalyst

We encourage developers to write Catalyst components while developing user interfaces within the dotcom monolith. The benefits of utilizing Catalyst from the start are that the library abstracts away some common pitfalls of writing Web Components and enforces best practices.

Registering a Web Component can incur some boilerplate, but we make it easier with naming conventions and a sprinkle of TypeScript decorators. Actions in Catalyst make event listening easier than managing global event listeners. Mutating targets for existing HTML is better than rendering HTML templates in the browser.

Extracting a component from the monolith

While contained within our application, components might have application-specific code added to them as they get used in different contexts. Application-specific code is OK when you have specific needs that you need to fulfill, but if a component is supposed to work in other contexts, it needs to be flexible and generalized. Most often, this comes in the form of hard-coded options that should be made configurable. Generalizing a component so that it is more portable is critical to enabling re-use by other teams.

Before extracting the Catalyst component, we remove the Catalyst-specific functionality and convert it to a plain Web Component. Why remove the library that the team claims makes writing Web Components easier? While Catalyst is beneficial for developers, we want our components to have zero dependencies. Requiring developers outside of the GitHub organization to understand Catalyst before contributing code back to the component is extra friction that we don’t want to incur.

Open source components mean specific requirements

While monolith components might be tightly coupled to specific application logic, have third-party dependencies, and lean on existing tests, we have a different set of standards for open source components. Our open source components should have close to 0 dependencies, be framework and library agnostic, lightweight, style free, decoupled from any other components, and should do only one thing and one thing well.

While we want our components to be dependency-free, we also want the same robustness guarantees from the monolith—and that includes types. We include TypeScript definitions with our components, also written using ES modules, to enable bundlers to consume it easily. We also ensure there is a full test suite and linter setup using our standardized configurations.

An excellent example of a component that has gone through the open-source lifecycle is the <typing-effect> element. A product engineering team within GitHub recently prototyped a terminal-inspired UI in which text appeared as if someone were typing it. In a previous project, we used the excellent and robust typed.js for a typing animation, and the team initially reached for that library again.

The parts of the UI that the team already built were lightweight, and our tooling identified that adding typed.js to the page would increase the bundle size fivefold. The UI Systems team asked the product engineering team to consider other options. We found that the functionality we needed for this application was limited enough that it was worth trying to build it ourselves.

The product engineering team wrote the first version of our own typing animation for the new UI. Using Catalyst, it took less than a day and fewer than 40 lines of code. Realizing that other teams could use this effect, we decided to put it through the lifecycle steps. We refactored the component to have zero dependencies, “ejected” it out of the Catalyst library, and open-sourced the component as <typing-effect>.

Results

Overall, we’re thrilled with the changes that we’ve made to the GitHub front-end since our last post. According to the internal developer surveys that we’ve conducted, our developers are pleased with Catalyst and ViewComponent!

Developers enjoy the encapsulation of ViewComponent, making it easier to test UI and increasing developer confidence. Developers feel Catalyst is a welcome change from “old-style” JavaScript without the massive leap to a different framework or paradigm.

What’s next?

We’re continuing to open source more generic open-source behavioral Web Components under the name “GitHub Elements.” We have a collection of these elements on https://github.com/github/github-elements, which syncs to our page on webcomponents.org.

We’re excited about Web Components’ future and continue to monitor proposed changes to the HTML spec. The two proposals we are most excited about these days are the Template Parts and Declarative Shadow DOM proposals. These proposals would make it even easier for engineers to ship Web Components and would solve some common pain points that we have with the current state of Web Components. We’ve implemented the minimum viable bits of Template Parts in a ponyfill, which is being used in production today, and we’re keen to see it gain traction from the broader community.

Special thanks

Thanks to Keith Cirkel for kick-starting this post, Ben Scofield and Joel Hawksley for reviewing it, and Nick Holden for working with us to extract the <typing-effect> element.

Written by

Kristján Oddsson

@koddsson