A guide + boilerplate for publishing modern React modules with Rollup
React & NPM living together in harmony.
Publishing an open source React / Preact component or library to npm can be very rewarding, but getting started with the setup is still more daunting than it should be, especially compared to the relatively easy process of creating a React app via create-react-app or create-preact-app.
Kylo Ren attempting to publish his first React module…
Because JS module formats and ES features are all over the place and are unlikely to be normalized anytime soon, npm modules must support both the lowest common denominator format (commonjs) as well as modern ES6 modules without relying on commonplace language features like JSX and class properties that most of the React community takes for granted. For this reason, it’s pretty difficult to take a component you’ve written for an app and publish it directly to npm.
The purpose of this article is to help React authors easily publish their own, high quality component modules.
Goals
There are some existing React library boilerplates, but none of them fulfilled the following goals which we set out to accomplish:
- Support all possible JS language features during development
- Build process to convert source to commonjs and es module formats required for practical usage on npm
- Use Rollup for build process and Babel for transpilation (we discuss Rollup vs Webpack later on in this article)
- Must come with an example app using the create-react-app standard
- Allow the use of npm modules within your library, either as dependencies or peer-dependencies
- Support importing CSS in your module (note that CSS support will be a noop if you’re using a css-in-js approach)
- Thorough documentation
It’s particularly important for module authors to include a simple, self-contained example app alongside the module itself, as it serves two useful purposes:
- As a local, hot-reload server for developing your module
- Easily publishable to github pages so users can quickly demo your module (or comparable hosting alternatives like surge.sh or now.sh)
Now that our goals are clearly defined, check out the boilerplate repo we’ll be starting from:
transitive-bullshit/react-modern-library-boilerplate_react-modern-library-boilerplate - Boilerplate for publishing modern React modules with Rollup_github.com
Walkthrough
In order to use the boilerplate, we recommend following this walkthrough to start out. Don’t worry if these steps seems complicated, as it’s meant to be very verbose.
Getting Started
Let’s create an example npm module called react-poop-emoji that exposes a single component, PoopEmoji 💩. We'll assume an example github username of github-haxor, where your github username will be used for specifying the repository in package.json and resolving the example github pages deployment.
Local Development
Now you’re ready to run a local version of rollup that will watch your src/ component and automatically recompile it into dist/ whenever you make changes.
We’ll also be running our example/ create-react-app that's linked to the local version of your react-poop-emojimodule.
Now, anytime you make a change to your component in src/ or to the example application's example/src, create-react-app will live-reload your local dev server so you can iterate on your component in real-time.
Git Stuffs
When you’re ready to push your component for the first time to github, make sure you’ve customized all your readme and metadata, then initialize your git repo normally:
NPM Stuffs
When you’re ready to publish your module to npm, make sure your dependencies are up-to-date. Any npm module dependencies that you don’t want to be included in the published bundle should be marked as peer dependencies in package.json and added to the externals array in your rollup config. Note that this boilerplate defaults to setting react, react-dom, and prop-types as peer dependencies, which is probably what you want unless you really know what you’re doing.
Github Pages
And finally, we recommend deploying your example to github pages so your users can quickly play around with a live version of your library before installing it.
Deploying to github pages is straightforward. We create a production build of our example create-react-app that showcases your library and then run gh-pages to deploy the resulting bundle. This can be done with the command:
npm run deploy
Note that it’s important for your example/package.json to have the correct homepage property set, as create-react-app uses this value as a prefix for resolving static asset URLs.
We recommend adding a link to the resulting github pages example to your readme.
The Dude eloquently describing the engineering KISS principle.
FAQ
Why use Rollup over Webpack?
For a deeper explanation, I recommend reading Rich Harris’ article Webpack and Rollup: the same but different. In short, the majority of the community now favors using Rollup for libraries and Webpack for apps. That being said, I believe you should stick with whatever you’re more comfortable with, as there really isn’t that big of a difference between the two as long as you’re comfortable using one versus the other.
Why use create-react-app for the example?
create-react-app has become a standard that nearly every react developer is familiar with. Its internal design choices and tradeoffs represent a great deal of collaboration among many of the best developers in the React community.
We feel that by taking advantage of such a standard application framework, module authors can provide the simplest possible example app that both acts as a mature, local development vehicle while iterating on your module as well as being easily publishable as an example showcase.
See this CRA issue for more context around this movement.
Where are the tests?
I recommend that you piggyback off of create-react-app’s built-in test harness setup for testing your library. That being said, feel free to submit a PR and I’d be happy to add some separate, standardized testing to the boilerplate.
What’s the purpose of creating boilerplate? Won’t it be outdated in a month?
This is legitimately a great question. I’d like to thank myself for asking it 😝
Even though the JS community typically moves too fast for its own good, I believe these types of point-in-time best practice boilerplates still serve a useful learning purpose and jumping off point for both aspiring open source authors and veterans alike. I was personally frustrated that it was so difficult to find a quality, up-to-date starting point after publishing several open source react modules, so I wanted to take what I had learned and give back to the community that has taught me so much.
If you have any suggestions on how to improve this boilerplate or walkthrough, or if something’s out-of-date a month from now, feel free to raise an issue or, even better, submit a PR!
How can I use use Typescript in my components?
Rollup has excellent Typescript support. For details on how to integrate Typescript with this boilerplate, see this issue.
What does a published module look like?
Here is an example react module created from this guide: react-background-slideshow, a sexy tiled background slideshow for React. It comes with an example create-react-app hosted on github pages and should give you a good idea of the type of module you’ll be able to create starting from this boilerplate.
Example boilerplate module react-background-slideshow (animations sped up for demo)
Where to go from here?
I’d like to throw a shout out to js.coach, which is my favorite resource for finding high quality, open source React components. If you’re looking for further inspiration or are trying to find a solid solution without reinventing the wheel, chances are there will be some relevant modules listed on their index.
If you find this walkthrough or accompanying boilerplate useful, please ⭐️ ️️ the repo to help other developers find it.
Disclaimer: the author is a software engineer at Facebook, but this article discusses an independent open source project, and my views do not reflect the views of Facebook or its engineering staff as a whole. E.g., I write about this type of stuff for fun 😃