Join GitHub today
GitHub is home to over 31 million developers working together to host and review code, manage projects, and build software together.Sign up
Building a Web Component
This article will cover all the different aspects of building a web component, from basic to advanced.
Before you start, make sure you've completed all the steps in Before you build it.
Creating a repo
First, make sure that you and your designer have decided that the component you're building should be shared. To help answer that, see: Web Components 101: Should I build a shared component?
If you decide it's not time to make it shared, your component should live within your project and not require its own repo.
Next, what type of component is it?
Design components belong in the BrightspaceUI organization and typically each have their own repo.
Application data-driven/hypermedia components belong in the BrightspaceHypermediaComponents organization, but repos are organized by entity type (user, activity, organization, etc.), so probably your repo has already been created for you.
If you're missing permissions to create a repo, reach out on the
#web-platform Slack channel.
What flavour of Polymer?
Our web components are built using the Polymer library. To learn more about Polymer, see: Web Components 101: Polymer. There are three versions of Polymer and depending on where your component will be used, choosing the correct version is important.
Elements in Polymer 3 look almost identical to Polymer 2, except that they're hosted inside
.js files instead of
With the launch of Polymer 3 in May, 2018, the Polymer team announced that version 3.0 would be the last version of Polymer. Instead, they'll be focusing their efforts on
LitElement, a lighter weight component wrapper. Once we get to Polymer 3, we'll re-evaluate if
LitElement is the best next step.
Create a Polymer 3 element when: you are starting a new FRA, you are adding to a FRA that either is Polymer 3 or will be updated to Polymer 3 before that element is needed, or you know that your element will be needed in Brightspace Integration (BSI).
Polymer 2 Class-based
v1 set of polyfills, which means it can start to take advantage of native custom element and shadow DOM support in browsers.
Create a Polymer 2 element when: you know that your element only needs to work inside projects which are currently using Polymer 2. Consider helping to update that FRA to Polymer 3 rather than creating another element that will need to be updated later!
Polymer 1.x/2.x Hybrid
Hybrid elements work in projects built with either Polymer 1 or 2. They're very similar to the original Polymer 1 elements, except that they've undergone a few changes to address breaking changes in the custom element and shadow DOM APIs.
Create a hybrid element when: you know that your element needs to work in a project that still uses Polymer 1 or 2. Consider helping to update that FRA to Polymer 3 rather than creating another element that will need to be updated later!
Quick start with
polymer init generators
To instantly get all the boilerplate code and setup files you need, we've created Yeoman generators.
These automatically integrate with
polymer init command. So first, make sure you have
polymer-cli installed globally:
npm install -g polymer-cli
For a Polymer 3 class-based element:
npm install -g generator-polymer-init-d2l-polymer-3-element
Now simply run
polymer init from an empty directory and choose the appropriate template from the list.
To see and contribute to the code behind these generators:
Once the initialization code is finished, it'll run
npm install to get all the necessary dependencies. That's it! Have a gander through the repo files and look in the generated
README for instructions on running a local demo of the component, running tests, and so on.
From here, you can leverage the Polymer Documentation to start building out your component's functionality. Also, check out the advanced topics below for more...
Hopefully at this point you have a basic web component built and working. Now, let's dive into some more advanced topics...
Linting, unit tests and running your tests cross-browser in Sauce Labs are all covered in: Testing.
Hopefully your component will get used by hundreds of other developers in thousands of application pages and viewed by millions of users! To help those developers out, follow the simple tips in: Documenting.
By building a component that other developers are going to put into their applications, they're trusting that your component is fast. Learn how to not let them down in: Performance Tips.
Does your component render or parse dates, times or numbers? Does it display text to the user? Does it contain CSS or icons that should be mirrored in right-to-left locales? If so, you need to understand: Localization.
Wiring up to locally run a web component & BSI on your dev LMS
Do you want to see how your component will behave in the LMS without having to push to master, publish releases, and update version numbers? Check out Wiring up to locally run a web component & BSI on your dev LMS