What I learned making my first open source React component

I recently open sourced my react-large-virtualized-list component. It let’s you render very large lists (we’re talking tens or even hundreds of thousands of elements) on screen without compromising performance, by utilising a concept called Windowing (also known as List virtualization). What this means is that the component only renders the portion of the list that is currently visible (within a scrolling “viewport”). This means that you don’t need to pay the cost of rendering thousands of rows of data at once.

“How does windowing work?” by Brian Vaughn

List virtualization is a technique that I use occasionally in my professional work as well as in my personal projects to keep performance high and to decrease the initial rendering time of a page when working with large datasets or complex DOM-structures.

Don’t get me wrong: there are plenty of good components out there already that can do all the legwork for you (like react-virtualized), but I often like building relatively simple components like this myself. Doing so minimises the number of external dependencies and it’s always a great learning opportunity.
As I have been applying list virtualization techniques in multiple projects before, I wanted to capture this functionality in a simple React component and share it with other people so they can use it and hopefully learn from it as well.

Open source is a lot of work. Do people really do this every day!?

I have open-sourced some of my personal projects in the past but I had never open-sourced a specific React-component before, so building React-large-virtualized-list and then open-sourcing it was a great learning experience.

Building the component was relatively fast, as I had applied list-virtualization techniques in some of my React projects before.

But then open sourcing it… that took nearly as long as building the component itself. Because doing good open-source is hard.

Here are a few tips from what I learned as I open-sourced my first React component:

nwb is a good way to get started

When you want to create a new React application, a good way to start is by using create-react-app. This sets everything up for you. Babel, Webpack, a development server, some boilerplate component, commands to create production builds.. all you need to start building a single-page React app.

However, when you want to build an isolated component you don’t need all of the tools and boilerplate that create-react-app provides. In fact, in the Readme.md file of create-react-app it even says:

“If you need to publish a React component consider using nwb.”

– create-react-app readme file

Using nwb you can create a new standalone React component using the following simple command:

nwb new react-component <new-component-name-here>

This sets up everything you need to start working on your component. It creates a src folder for your code, a demo folder for your components’ demo page (plus dev server and hot reloading), a test folder that you should use to write some tests, some build commands for shipping your component… Basically all the tools you need to get started, so you can focus all your time on building your component.

Tip: if you are planning on publishing your component on NPM, make sure the component name is still available. This is wherenpm search will help you. Let’s say you are going to create a fancy React list, you would want to make sure that react-fancy-list has not yet been taken:

npm search react-fancy-list

Unfortunately, react-fancy-list already exists and we have to pick another name for our component.

Make a good demo-page to showcase your component

When making an open-source component, it’s a great idea to make a good demo page so you can show off your component in action. People are visual creatures, and a good demo-page says more than a few hundred words. It shows people that your component is or isn’t what they need to solve their problem.

So show the world what you built.

react-large-virtualized-list, for example, has a demo page (built using Storybook) that shows off different ways you can use the component.
The demo page doubles as documentation. People can see how to integrate the component in their code and read about all the different props they can pass into the component.

This part took a while because nwb‘s demo pages are quite basic..

Creating good documentation takes time

People will find out about your component in different ways. Some will see it on GitHub, others will come to your demo page, many will see it on npmjs.com.
Your documentation has to live in at least two places:

Your README.md file
Your demo page

Both on GitHub and npmjs.com the first thing people see is your README.md file. It shows up as your component’s homepage.

So it better be good. Write a clear, short and to-the-point description of what problem your component solves. Add all the code samples someone needs to get started. Explain why they would want to use it.

If you need some tips, I wrote another post about creating useful software documentation that you can use as a guideline.

Writing documentation might not seem that exciting, but it’s worth it. Without it nobody else will be able use your software, and most likely you won’t remember all the details of what you created anymore either when you come back to it in a year from now.

As with anything, practice makes perfect – the more you do this, the better you will become at writing useful documentation. Maybe try to think of an open-source component that you found to be well documented and take inspiration from there!

Do it more often

People don’t want to learn how to fish. People just want fish.

I find that building things and writing about them is great in many ways. It’s great for improving your skills, it makes you think more clearly about what you are doing and it’s actually also great for your career! It’s a way to help others by sharing your knowledge, creating value for them and expanding your network by creating exposure for yourself.

You know what’s even better?

Giving people tools.

You’re not just telling them how you solve your own problems, you’re helping them solve similar problems too!
Just think of all the times you have used an open-source component or tool, read a blogpost or followed a tutorial. Now imagine if all those people had kept those tools for themselves.. Everyone’s development time would skyrocket, and we would all be spending it on solving the same issues that other people have solved many times before!

Contributing to the open-source community is a great thing to do, it improves your skills and it saves us all time that we can then use to spend on.. creating more open-source software? 😉

I should do it more often too! 🙂

Do you have any tips on open-sourcing your components or projects? Or do you have ideas on what absolutely NOT to do when working on open-source software?
Write it in a comment below!