How to build Polymer components with Github and Travis CI

Lately, we have been extracting dozens of Polymer components for standalone usage. We open sourced lots of those along the way. So you can check them out as examples.
This blog post summarizes the steps we take to extract a Polymer component from our existing JavaScript applications.

Github and Travis CI

Before we get started, some words on Github and Travis CI: We love hosting our components on Github and found Travis the perfect match to continuously test if the components still do what they are supposed to do. In fact, we even moved away from Bitbucket/Bamboo because Github/Travis works so magically together for our Polymer components. As a bonus, both systems offer free options if you open source your components. A great starting point to try it out yourself!

So here are the steps that we take to extract a Polymer component:

Step 1: Prepare existing code

First, we bring the component in shape so it can be easily extracted into a separate Github repository:

1. Review specifications: We spend a considerable amount of time to define the right scope of the component (or collection of components). Ideally, we built on the specification of an existing standard. For example, for our UI components we always consult the Material Design specification if our component fits into an existing concept.
   This pays off big time: We not only get a well-defined scope and naming but we might even find an existing component that already implements what we need.
2. Refactor code: Next, we refactor the application code to move the future component into a separated file/package. For example, unrelated functionality might get moved out of the component and connected via data binding/events.
3. Adjust to specification: Now, we apply everything we learned from reviewing the specification: Starting from renaming the component itself to matching the properties and styles. Ideally, in the end our documentation only needs to refer to the external specification.
   We don’t aim to implement the specification completely but to provide a sound subset (read here how we open source).

Step 2: Create standalone component

Having the component prepared, we can move it into a separate Github repository:

1. Create Github repository: When creating the Github repository choose a license (for us: Apache License 2.0) and add a meaningful description, e.g. ”A Material Design chip”.
   Since the Polymer world is currently split into the incompatible pre-v1.0 and post-v1.0 camps, we state our target as well in the description, e.g. ”A Material Design chip (Polymer 1.x)”.
2. Add component code: Copy the refactored component code into the root folder of the new Github repository.
3. Create demo: Add a simple example that demonstrates the core functionality into the demo folder (see example). The demo acts as the executable user documentation.
   For simplicity, we include non-trivial setup code only if it demonstrates something component-specific. For example, we typically avoid property bindings because it complicates the demo code although data binding is trivial for real usage.
4. Add bower.json: The bower.json must declare all packages on which the component depends. The keywords node should contain “web-components” and “polymer” to have the component auto-discovered by catalogs like customelements (see example).
5. Add documentation: The documentation should describe the purpose of the component and state all properties & styles that are exposed to consuming components (see example). A screenshot will work wonders to give other people a quick idea what the component is about. Check the screenshot into the doc folder and reference it from the readme.md.
   For public repositories, also state the license to simplify reusage by other projects/companies.

Step 3: Enable continuous testing

Next, we ensure that our component keeps doing what it’s supposed to do:

1. Create tests: Hopefully that’s just copy-and-pasting existing tests. If not, it means writing tests…
   In any case, we review if there are relevant scenarios that aren’t covered so far. It turns out that the smaller granularity of a standalone component often simplifies the testing of corner cases.
2. Add Travis configuration file: Add to the root folder a file called .travis.yml, which instructs Travis to execute the tests (see example)
3. Let Travis monitor new pushes to the Github repository: Log into Travis and activate the new Github repository

Step 4: Auto create Polymer documentation

Having Travis testing in place, we ask Travis to also auto generate the Polymer documentation pages whenever a new version is build:

1. Add the gpages_build.sh script which uploads the Polymer documentation to Github pages (see example)
2. Make the script executable on Github:
   git update-index — chmod=+x gpages_build.sh
3. Add triggering the script to the Travis configuration (see example)
4. Add to README.md a link to the documentation (see example)
5. Restart the Travis build and check that the documentation is reachable

Step 5: Use component

By now, we have a properly documented and tested component. In the last step we’ll integrate the component into our application:

1. Release the component on Github: Ensure that the version number mentioned in bower.json matches the release number.
2. Declare in bower.json a dependency on the new component
3. Remove the code of the old component from the application
4. Change the HTML imports from the old to the new component

Et voila, the component is extracted and used by the application!

Want to learn more about Polymer? Have a look to all our Medium posts on Polymer.

Photo: Jakob Montrasio