A Guide to Building a React Component for npm
Building and publishing a React component on npm is very different from building a normal React web application. There are a lot of things to take into account, so I’ve made this brief guide to help you get the important things right. It’s based off of my experience building a toggle-switch library called react-switch.
Before you start
Before you start coding you should make sure that the problem you’re trying to tackle hasn’t already been solved by an existing package. Make a thorough search on Google and npms.io, and look through this list of popular react components to make sure you’re not wasting your time.
Set up your project
I have built this boilerplate project which makes it very easy to get started.
The project structure for building a library looks a bit different from your average web app project. It has two separate parts:
- The component library itself.
- A demo page, which is needed to test the component and showcase the component to potential users when it is finished.
Both are written in ES6 and JSX, and have to be separately transpiled by Babel. Go to the boilerplate project for a more in-depth explanation of how it is structured.
After you’re set up, it’s time to start building the component itself. This bit is up to you, but you should keep reading to get vital advice for how to not screw up.
Make it accessible
It’s always important to make websites accessible to users with disabilities. This is doubly true when building a component that you hope will be used on dozens or hundreds of websites. The most significant groups to be concerned about are visually impaired users who may use a screen reader and motor impaired users who can’t use a mouse.
Here are some guidelines:
- Use the WAI-ARIA authoring practices to look up what the best accessibility practices are for the type of component you’re building. They contain detailed descriptions for how to make a variety of different components accessible. Just pick the one you’re building and follow the instructions.
- Try to use your component using only the keyboard. Keyboard accessibility is necessary for people who use a screen reader and those who can’t use a mouse. It also benefits everyone, since using the keyboard is often faster than using the mouse.
- Try to use your component with a screen reader. There are good free alternatives for Mac and Windows. ChromeVox is an chrome extension that works as a basic screen reader. Tab around your component’s demo page and make sure the voice says what it should.
Accessibility is a huge topic that can’t be fully covered here, but if you want to delve in deep you should read Google documention on it.
Keep it tiny
When writing a front-end library keeping the size small is essential. Modern React apps can have dozens of libraries bundled inside their bundle.js file. All this code adds up to extra loading time for the end-user so you should try your best to minimize the footprint of your library.
The most important thing is to make sure you component library doesn’t depend on other big libraries. Avoid CSS frameworks like Bootstrap, animation libraries or stuff like styled-components. Whenever you decide to depend on another library, check out its size on https://bundlephobia.com/ beforehand to make sure it isn’t too big. Use webpack-bundle-analyzer to find out how much space the different parts of your bundle take up.
Write good documentation
Your documentation will most likely consist of two parts - the README and a demo page. The README is the first thing people look at when they find your library. It should at the very least do the following:
- Explain clearly what your package does and what problem it solves in the first paragraph of the README.
- List its main selling points so that people understand why they should choose your package in favor of another similar and more popular package.
- Provide specific instructions for how to install and use your package
- Provide a public API — usually a list of props that the user can give to the component and describe what they do.
- Shields!
The demo should showcase lots of different ways to use your component. You want a prospective user to know that the library will work for their specific use case. Providing working examples along with the source code for them (like this, for example) will make it easy for users to get started. The more examples, the better!
GitHub Pages provides a convenient way to host your demo page free of charge.
Secure a good name
A good package name is important since it can help the search ranking of your library and makes it seem more “official”. You should aim for a name that matches what people type into google when they need the type of package that you’re building. Unfortunately most good names have already been taken, but there is a hack you can sometimes use…
If you find an npm package with a good name that looks abandoned and doesn’t have many downloads, you might be able to snatch it. Just send an e-mail to the owner of the package and ask if they will transfer publishing rights to you. If they don’t, npm can award you the rights if they think you have a better claim. One guy was able to get the name “server” this way. I myself managed to secure react-switch for my toggle-switch component.
Marketing
After publishing your package to npm, you wake up the next day to find that it already has something like 40 downloads. It’s blowing up! And you didn’t even tell anyone about it. Amazing, except for the fact that they’re all bots. A lot of services download all new packages in order to keep track of them for different purposes. If you want real people to use your code, building a technically superior component is not enough. You have to let people know about it.
Here’s how:
- Submit your package to newsletters. If you get accepted you can get a lot of stars. There are a couple of React-specific newsletters: React Status, Fullstack React, and React Newsletter among others. Look through this list, and submit your component to any newsletters that you think might be relevant. If you get rejected, who cares. The component that I made got accepted to React Status and received around 80 stars on GitHub that same week.
- Make a submission to the React subreddit presenting your library. Even though it’s a relatively small subreddit it still draws a lot of traffic. You could also try with the larger JavaScript and Webdev subreddits.
Before you try to make a big splash you should probably make sure that your repository is ready for prime-time. It might be a good idea to first ask for some feedback from someone. The Reactiflux Discord chat is an excellent way to ask questions, and get feedback on your work.
Closing thoughts
This guide is far from complete. It hasn’t explored important topics like writing tests, linting, handling CSS, semantic versioning, maintenance and more. It should however give you a solid base for further exploration.
If you run into any problems or have questions, feel free to write a comment and I’ll do my best to answer.
