Building and Publishing your Web Component in 9 Steps
This is a quick tutorial on how to build your Web Component, push it to GitHub with a demo and finally publish it to bower (optional). We will be building an upper-case tag, which will make the text-content inside it appear in upper case.
So let us get started.
If you are new to Web Components, refer Web Components – The Future Web and Web Components, PhoneGap Build and WordPress – A Hybrid App for your Blog.
Step 1 : Create a new folder where you would like to store all your Web Components. Let us call it myWebComponents and open terminal/prompt here.
Step 2 : Install the required dependencies globally. Run
|npm i -g bower yo generator-polymer||sudo npm i -g bower yo generator-polymer|
Step 3 : Inside myWebComponents folder, create a new folder with the name of your tag (upper-case) and CD into that folder. Now run
You will be asked 2 questions
Then Yeoman will scaffold the project for you. Once the components are installed, you should see a folder structure like
All the dependencies will be at the root of the project and only the custom tag related files will be inside the custom tag folder (upper-case). This way, you can author multiple tags, sharing the same dependencies. A pretty genius architecture.
Important : When you are working with your components, make changes to upper-case.html, upper-case.css and demo.html. The index.html uses a <core-component-page></core-component-page> which is responsible for generating the index.html from the comments present inside the upper-case.html. Another genius component.
Note : Make changes to index.html only if you would like to manage the documentation yourself.
Step 4 : Make the required changes to the components. In the current case, there are two changes. Open upper-case.css and replace the contents with below
This will take care of converting the contents inside the tag to upper case.
Next open demo.html and update the custom tag to
<upper-case>this is a sample text</upper-case>
Step 5 : Test your changes. You can push the entire myWebComponents folder to a *AMP server or if you have Python installed, you can run the below command from the myWebComponents folder (not from upper-case folder).
python -m http.server
|python -m SimpleHTTPServer|
Then launch http://localhost:8000/ and select the upper-case link
When you click on the demo link on the top, you should see something like
git add -A
git commit -am "Initial Version"
git remote add origin https://github.com/arvindr21/upper-case.git
git push origin master
This will push the code to GitHub.
Step 7 : Generate the docs, demo and push it to GitHub pages. The Polymer team has put together an awesome tool to do this for us. CD back to myWebComponents and run
git clone git://github.com/Polymer/tools.git
Next, create a temp folder inside myWebComponents folder for processing the docs, demo generation and pushing it to GitHub pages. Execute
mkdir temp && cd temp
and then run
../tools/bin/gp.sh <github-username> tag-name
In my case
../tools/bin/gp.sh arvindr21 upper-case
This will push the code to gh-pages branch of upper-case repo. You can navigate to http://arvindr21.github.io/upper-case and check the demo and docs.
You can delete the contents of the temp folder when done.
Step 8 : Tag/Version the code. To publish our awesome code to bower, we need to version the code. This version will be downloaded on the user’s machine when he runs
Back to GitHub upper-case repo and click on releases, located above the source code. And then you should see the below for the first time
Step 9 : Publish the component to Bower (publish the component only if you think it would be helpful for others). Back to terminal/prompt, CD into the upper-case folder and run
bower register tag-name git-repo-url.git
In my case
bower register upper-case https://github.com/arvindr21/upper-case.git
Bower will ask you to confirm the registration. Enter Y. And thats is it!! Your Web Component is reusable!!
Once you are done with the enhancements, make sure you have tested it thoroughly. Next follow the below steps to re-publish the changes to the world.
Step 1 : Update the comment docs in the tag-name.html (upper-case.html).
Step 2 : Update the demo.html
Step 3 : Push changes to GitHub
git commit -am "added awesome features"
git push origin master
Step 4 : Run Step 7 from above to push the new demo to gh-pages.
Step 5 : Tag a new version. Open the release tab and create a new version (refer step 8 above) (to v.0.0.2).
Thats it!! Now when the user runs bower upper-case , the latest version will be downloaded.
Thanks for reading! Do comment.