Introduction

So, you want to publish your first reusable Polymer element? Fantastic! This guide will walk you through that process. First, we’ll cover setting up the official boilerplate for working on a reusable Polymer element on your local system. We’ll then walk through deploying a version of your element to GitHub pages.

This guide will ensure your master branch contains the bare-minimum of code that needs to be consumed by other apps or elements and your gh-pages (GitHub pages) branch contains a landing page for your element. This branch will contain checked-in dependencies, demos and documentation.

Note: We assume you have git, Node and Bower installed on your system.

Create

1. Create a new directory on your system for working on Polymer elements (e.g "development").

2. Download the seed-element boilerplate and unzip it in your working directory.

3. Rename the element and its files accordingly. For example, if your element is called <test-element> and you’ve renamed the seed-element directory to test-element, your file list should look a little like this:

1. Next, run bower install inside your element directory to install dependencies. They will end up inside the development directory if all goes well. You can now locally develop and serve your element up for testing purposes.

Develop and Test

Add the logic specific to your new element and verify its functionality. Good unit tests are essential to your verification plan but a good way to quickly sanity test your component is to access your demo.html file via a local web server. There are several ways to do this but one easy method is to run a simple web server that ships with Python, using the following commands:

$ cd ..  # You'll want to run the web server from the parent directory.
$ python -m SimpleHTTPServer

This starts a web server on port 8000, so you can test your new element by navigating a browser to the URL localhost:8000/test-element/demo.html.

Deploy

Pushing your work to GitHub

Once you’re happy with your element, you’ll want to push the code for test-element to GitHub and tag a new version of it.

Click here to create a new repository on GitHub. Try to keep the name of the repository consistent with the naming of your element (e.g if your element is <test-element>, your repository should be called test-element).

Next, follow the steps below:

# Inside your development folder, navigate to your element directory
cd test-element

# Initialize a new Git repository for test-element
git init

# Add the commits for your current code
git add .
git commit -m 'My initial version'

# Add a remote pointing to the GitHub repository you created.
git remote add origin https://github.com/<username>/test-element.git

# Push your code to master by running
git push -u origin master

Next, you’ll want to tag a version of your element on GitHub. You can either do this directly through the GitHub UI or via the terminal.

Via the terminal

# Once you feel you have a version of your element you can release, tag it
# Below we’re tagging version 0.0.1
git tag -a v0.0.1 -m '0.0.1'

# Then, push your tag to GitHub
git push --tags

Via the GitHub UI

Navigate to the main GitHub page for your element and click the “releases” link in the main navigation. It is highlighted in red below:

This will navigate you to the Releases page. For a project without any releases, this page will display a message similar to the one below.

Click the ‘Create a new release’ button to proceed.

This will display a Release drafting page where you can enter in version and release information for your element. Below, we’ve entered in v0.0.1 as the tag we would like to create and set the master branch as our target.

Once you are happy with the information you have entered into the above form, click the ‘Publish release’ button to complete tagging and publishing a release of your element. Boom!

Publishing a demo and landing page for your element

Great—you now have a tagged release for your element. Next up, let’s create a meaningful demo and landing page for your element.

While optional, we recommend modifying the demo.html page to provide a real-world example of your element. Developers can get a feel for how your element behaves, and can use your demo as a jumping off point for integrating your element in their own projects.

This is also your chance to share documentation for your element’s public interface. index.html uses our core-component-page element to parse out documentation from your element as long as you’re using our custom flavour of JSDoc comments. seed-element includes boilerplate for these comments out of the box. (You can check the core-doc-viewer issue tracker for a list of known issues with specific types of JSDoc comments.)

This allows us to:

• Provide a summary of what your element does.
• Automatically group your documentation by attributes, methods and events.
• Show an example of your element in action.
• Link up to an element demo.

Take a look at demo.html and the rendered JSDocs in index.html in your browser to make sure you’re happy with your customizations. You’ll need to access them via http: URIs served from a local web server; they won’t display properly if opened directly via file: URIs.

Once demo.html and the docs in index.html look good locally, make sure that you’ve pushed any changes to your repo’s master branch. Also, make sure that you’ve updated throughout your project the name and paths from the original seed element to your element, including the ones in bower.json. We can now use a special script to push a landing page for your element to GitHub pages. Inside your terminal, walk through running the following commands:

# Navigate back to your development directory
cd ..

# git clone the Polymer tools repository
git clone git://github.com/Polymer/tools.git

# Create a temporary directory for publishing your element and cd into it
mkdir temp && cd temp

# Run the gp.sh script. This will allow you to push a demo-friendly
# version of your page and its dependencies to a GitHub pages branch
# of your repository (gh-pages). Below, we pass in a GitHub username
# and the repo name for our element
../tools/bin/gp.sh <username> test-element

# Finally, clean-up your temporary directory as you no longer require it
cd ..
rm -rf temp

This will create a new gh-pages branch (or clone and clear the current one) then push a shareable version of your element to it.

Share

You can now share the link to your element hosted on GitHub pages with the world. As we used the seed-element repo, Polymer will give you a styled component page out of the box that looks a little like this:

You can check out the live version of this page for the seed-element project.

Where to go next?

Now that you’ve published your Polymer element to GitHub, you may be interested in learning how to distribute your element using Bower.