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 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 or . npm create-react-app 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 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. commonplace 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 for build process and for transpilation (we discuss Rollup vs Webpack later on in this article) Rollup Babel Must come with an app using the standard example create-react-app 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 or ) surge.sh now.sh Now that our goals are clearly defined, check out the we’ll be starting from: boilerplate repo _react-modern-library-boilerplate - Boilerplate for publishing modern React modules with Rollup_github.com transitive-bullshit/react-modern-library-boilerplate Walkthrough In order to use the , we recommend following this walkthrough to start out. Don’t worry if these steps seems complicated, as it’s meant to be very verbose. boilerplate Getting Started Let’s create an example npm module called that exposes a single component, 💩. We'll assume an example github username of , where your github username will be used for specifying the repository in and resolving the example github pages deployment. react-poop-emoji PoopEmoji github-haxor package.json Local Development Now you’re ready to run a local version of rollup that will watch your component and automatically recompile it into whenever you make changes. src/ dist/ We’ll also be running our create-react-app that's linked to the local version of your module. example/ react-poop-emoji Now, anytime you make a change to your component in or to the example application's , will live-reload your local dev server so you can iterate on your component in real-time. src/ example/src create-react-app 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 in and added to the externals array in your rollup config. Note that this boilerplate defaults to setting , , and as peer dependencies, which is probably what you want unless you really know what you’re doing. peer dependencies package.json react react-dom prop-types 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 that showcases your library and then run to deploy the resulting bundle. This can be done with the command: create-react-app gh-pages npm run deploy Note that it’s important for your to have the correct property set, as uses this value as a prefix for resolving static asset URLs. example/package.json homepage create-react-app We recommend adding a link to the resulting github pages example to your readme. The Dude eloquently describing the engineering principle. KISS FAQ Why use Rollup over Webpack? For a deeper explanation, I recommend reading Rich Harris’ article . 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. Webpack and Rollup: the same but different Why use create-react-app for the example? 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. create-react-app 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 for more context around this movement. issue Where are the tests? I recommend that you piggyback off of create-react-app’s built-in 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. test harness setup 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: , 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. react-background-slideshow Example boilerplate module (animations sped up for ) react-background-slideshow demo Where to go from here? I’d like to throw a shout out to , 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. js.coach If you find this walkthrough or accompanying useful, please ⭐️ ️️ the repo to help other developers find it. boilerplate 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 😃

Harmony

Alongside

Facebook

Harris

2022 - HackerNoon Contributor of the Year - Developer Tools

2022 - HackerNoon Contributor of the Year - Typescript

Check out my site for more

Nominated for 2022 - HackerNoon Contributor of the Year - Typescript

Nominated for 2022 - HackerNoon Contributor of the Year - Developer Tools

Too Long; Didn't Read

Get free API security automated scan in minutes

Publishing Baller React Modules

Publishing Baller React Modules

Too Long; Didn't Read

Companies Mentioned

Coin Mentioned

@transitive-bullshit

RELATED STORIES