Good Practices for build Web Components
Note: The best practices presented here are about polymer, but you can follow these recommendations for any Web Components(link is external) or other type of component based on Libraries or frameworks (like React(link is external) or any other).
Tip: For open source projects see the Open Source Checklist(link is external).
Table of contents
- Make reusable and composable
- Cover the basics
- Make maintainable
- Improve performance
- A11y
- Make customizable
- Document all
- Publish to the world
- Resources for learning
Make reusable and composable
- Learn the 17 Rules of Unix philosophy(link is external).
- Learn about Atomic Design(link is external).
Cover the basics
- Make Responsive(link is external).
- When necessary, think in Progressive enhancement(link is external).
Make maintainable
- Follow the Semantic Versioning(link is external).
- Use
_
as a prefix convention for private methods. - Lint with eslint(link is external).
- Lint with polylint(link is external).
- Write unit tests with Web Component Tester WCT(link is external).
- Write the UI regression test(link is external) with whatever you want.
- Run the tests in all browser with Selenium(link is external) and Source Labs(link is external).
- Integrate all tests with CI(link is external).
Improve performance
- Optimize first paint(link is external).
- Write a test for first paint(link is external) performance.
- Implement do less & be lazy(link is external) concepts.
A11y
- Add Aria(link is external) labels.
- Use the focus(link is external) event.
- Think in tab index(link is external) order.
- Test all with Accessibility Developer Tools(link is external).
customizable(link is external)
Make- Use custom properties(link is external) and expose the API for users with docs.
- Use @apply rule(link is external) for most generic style and expose the API for users with docs.
Document all
- Provide a quick demo (like webcomponents.org inline demo(link is external)).
- Provide a full demo (Polymer iron-demo-helpers(link is external) is recommended).
- Describe how to download and use the component.
- Describe how to style the component.
- Specify the component support.
- Describe your API. (example(link is external))
- Describe how to run the development environment.
- Describe how to run all the tests.
Publish to the world
- Publish in bower(link is external).
- Publish in webcomponents.org(link is external) following the requirements(link is external).
Resources for learning
- Practical lessons from a year of building web components - Google I/O 2016(link is external) - @notwaldorf(link is external)
- Production-Ready Polymer Elements - A How-To-Guide (Polymer Summit 2016)(link is external) - @danfreedman(link is external)
- Polymer's Styling System (The Polymer Summit 2015)(link is external) - @notwaldorf(link is external)
- A11ycasts(link is external) - @rob_dodson(link is external)