Image for post
Image for post

A Guide to Building a React Component for npm

Markus Englund
Jan 9, 2018 · 6 min read

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.

Image for post
Image for post

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:

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:

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:

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:

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.

Image for post
Image for post

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.

DailyJS

JavaScript news and opinion.

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store