React is one of the most amazing libraries that has been released in the last few years, not only because of the library itself and its great features but also, most importantly, due to the ecosystem that has been built around it.
Following the React community is very exciting and inspiring; there are new projects and tools to learn about and play with every single day. Not just that, there are conferences and meetups where you can talk to people in real life and build new relationships, blog posts that you can read to improve your skills and learn more, and many other ways to become a better developer.
The React ecosystem encourages best practices and love for open source developers, which is fantastic for the future of our careers.
In this chapter, we will cover the following topics:
- How to contribute to the React library by opening issues and pull requests
- Why it is important to give back to the community and share your code
- How to publish an npm package and how to use semantic versioning
Technical requirements
To complete this chapter, you will need the following:
- Node.js 12+
- Visual Studio Code
Contributing to React
One thing that people often want to do when they've used React for a while is to contribute to the library. React is open source, which means that its source code is public and anyone who's signed the Contributor License Agreement (CLA) can help to fix bugs, write documentation, or even add new features.
You need to make sure that any bug you post in React's GitHub repository is 100% replicable. Once you verify this, and if you want to file an issue on GitHub, you can go to https://github.com/facebook/react/issues/new. As you'll see, the issue comes with some pre-filled instructions, with one of those being to set up the minimal demo. The other questions help you to explain the problem and to describe current and expected behaviors.
It is important for you to read the Facebook Code of Conduct before participating or contributing to the repository, at https://code.facebook.com/codeofconduct. The document lists good behaviors that are expected from all community members and that everyone should follow. Once the issue is filed, you have to wait for one of the core contributors to examine it and tell you what they've decided to do with the bug. Depending on the severity of it, they might fix it, or ask you to fix it.
In the second case, you can fork the repository and write code to solve the problem. It is important to follow the coding style guides and write all the tests for the fix. It is also crucial that all the old tests pass to make sure the new code does not introduce regressions in the code base. When the fix is ready and all the tests are green, you can submit a pull request, and wait for the core team members to review it. They may decide to merge it or ask you to make some changes.
If you did not find a bug but you still want to contribute to the project, you can look into the issues tagged with the good first issue label on GitHub: https://github.com/facebook/react/labels/good%20first%20issue. This is a great way to start contributing and it is fantastic that the React team gives everyone, especially new contributors, the possibility of being part of the project.
If you find a good first bug issue that has not already been taken by someone, you can add a comment on the issue saying that you are interested in working on it. One of the core members will get in touch with you. Make sure to discuss your approach and the path you want to take with them before you start coding so that you do not have to rewrite the code multiple times.
Another way of improving React is by adding new features. It is important to say that the React team has a plan to follow, and the main features are designed and decided by the core members.
That said, if you have some good ideas about features that should be added to the library, the first thing to do is open an issue and start talking with the React team. You should avoid spending time writing code and submitting a pull request before asking them, because the feature you have in mind might not fit into their plans, or might conflict with other functionalities they are working on.
Distributing your code
Contributing to the React ecosystem does not only mean pushing code into the React repository. To give back to the community and help developers, you can create packages, write blog posts, answer questions on Stack Overflow, and perform many other activities.
Suppose, for example, you created a React component that solves a complex problem, and you think that other developers would benefit from using it instead of investing time in building their solutions. The best thing to do is to publish it on GitHub and make it available for everyone to read and use. However, pushing the code to GitHub is only a small action within a big process, and it comes with some responsibilities. So, you should have a clear idea in mind about the reasons behind your choice.
The motivation behind why you want to share your code contributes to improving your skills as a developer. Sharing your code, on the one hand, forces you to follow best practices and write better code. On the other hand, it exposes your code to feedback and comments from other developers. This is a big opportunity for you to receive tips and improve your code to make it better.
Other than the suggestions related to the code itself, by pushing your code to GitHub, you benefit from other people's ideas. In fact, you might have thought about a single problem that your component can solve, but another developer may use it in a slightly different way, finding new solutions for it. Moreover, they might need new features and they could help you implement them, so that everyone, yourself included, can benefit from it. Building software together is a great way to improve both your skills and your packages, and that is why I strongly believe in open source.
Another significant opportunity that open source can give you is letting you get in touch with smart and passionate developers from all around the world. Working closely with new people who have different backgrounds and skillsets is one of the best ways to keep our minds open and improve ourselves.
Sharing code also gives you some responsibilities and it could be time-consuming. In fact, once the code is public and people can use it, you have to maintain it.
Maintaining a repository requires commitment because the more popular it gets and the more people use it, the higher the number of questions and issues. For example, developers may encounter bugs and open issues, so you have to go through all of them and try to reproduce the problems. If the problems exist, then you have to write the fix and publish a new version of the library. You could receive pull requests from developers, which could be long and complex, and they need to be reviewed.
If you decide to ask people to co-maintain the project and help you with issues and pull requests, you have to coordinate with them to share your vision and make decisions together.
Knowing the best practices when pushing open source code
We can go through some good practices that can help you make a better repository and avoid some of the common pitfalls.
First of all, if you want to publish your React component, you have to write a comprehensive set of tests. With public code and many people contributing to it, tests are very helpful for many reasons:
- They make the code more robust.
- They help other developers understand what the code does.
- They make it easier to find regression when new code is added.
- They make other contributors more confident in writing the code.
The second important thing to do is add a README with a description of the component, an example of its use, and documentation of the APIs and props that can be used. This helps users of the package, but it also avoids people opening issues and asking questions about how the library works and how it should be used.
It is also essential to add a LICENSE file to your repository to make people aware of what they can and cannot do with your code. GitHub has a lot of ready-made templates to choose from. Whenever you can, you should keep the package small and add as few dependencies as you can. Developers tend to think carefully about size when they have to decide whether to use a library or not. Remember that heavy packages have a bad impact on performance.
Not only that, depending on too many third-party libraries can create problems if any of them are not maintained or have bugs.
One tricky part in sharing React components comes when you have to decide on the styling. Sharing JavaScript code is pretty straightforward while attaching the CSS is not as easy as you may think. In fact, there are many different paths you can take to provide it: from adding a CSS file to the package to using inline styles. The important thing to keep in mind is that CSS is global and generic class names may conflict with ones that already exist in the project where the component is imported.
The best choice is to include the fewest possible styles and make the component highly configurable for end users. In this way, developers will be more likely to use it because it can be adapted to their custom solutions.
To show that your component is highly customizable, you can add one or more examples to the repository to make it easy for everyone to understand how it works and which props it accepts. Examples are also useful so that you can test new versions of the component and see whether there are unexpected breaking changes.
As we saw in Chapter 3, React Hooks, tools such as React Storybook can help you create living style guides, which are easier for you to maintain and for the consumer of your package to navigate and use.
An excellent example of a highly customizable library that uses Storybook to show all these variations is react-dates from Airbnb. You should take that repository as the perfect example of how to publish React components to GitHub.
As you can see, they use Storybook to show the different options of the component:
Last but not least, you might not just want to share your code – you may also want to distribute your package. The most popular package manager for JavaScript is npm, which we've used throughout this book to install packages and dependencies.
In the next section, we will see how easy it is to publish a new package with npm.
Other than npm, some developers may need to add your component as a global dependency and use it without a package manager.
As we saw in Chapter 1, Taking Your First Steps with React, you can easily use React by just adding a script tag pointing to https://unpkg.com/. It is important to give the users of your library the same option.
So, to offer a global version of your package, you should build the Universal Module Definition (UMD) version as well. With webpack, this is pretty straightforward; you just have to set libraryTarget in the output section of the configuration file.
Publishing an npm package
The most popular way of making a package available to developers is by publishing it to npm, the package manager for Node.js.
We used it in all the examples in this book and you have seen how easy it is to install a package; it is just a matter of running the npm install package, and that is it. What you may not know is how easy it is to publish a package as well.
First of all, let's say you move into an empty directory and write the following in your terminal:
npm init
A new package.json file will be created and some questions will be displayed. The first one is the package name, which defaults to the folder name, and then the version number. These are the most important ones because the first is the name that the users of your package will refer to when they install and use it; the second helps you release new versions of your package safely and without breaking other people's code.
The version number is composed of three numbers separated by a dot, and they all have a meaning. The last number of the package on the right represents the patch, and it should be increased when a new version of the library that contains bug fixes is pushed to npm.
The number in the middle indicates the minor version of the release, and it should be changed when new features are added to the library. Those new features should not break existing APIs. Finally, the first number on the left represents the major version, and it has to be increased when a version containing breaking changes is released to the public.
Following this approach, called Semantic Versioning (SemVer), is good practice and it makes your users more confident when they have to update your package.
The first version of a package is usually 0.1.0.
To publish an npm package, you must have an npm account, which you can easily create by running the following command in the console, where $username is the name of your choice:
npm adduser $username
Once the user is created, you can run the following command:
npm publish
A new entry will be added to the registry with the package name and the version you specified in package.json.
Whenever you change something in your library and you want to push a new version, you just have to run $type, where one patch is minor or major:
npm version $type
This command will bump the version automatically in your package.json file and it will also create a commit and a tag if your folder is under version control.
Once the version number is increased, you just have to run npm publish again, and the new version will be available to users.
Summary
In the last stop on this trip around the React world, we have seen some of the aspects that make React great – its community and its ecosystem – and how to contribute to them.
You learned how to open an issue if you find a bug in React, and the steps to take to make it easier for its core developers to fix it. You now know the best practices when making code open source, and the benefits and the responsibilities that come with it.
Finally, you saw how easy it is to publish packages on the npm registry, and how to choose the right version number to avoid breaking other people's code.