# Publishing Baller React Modules

A guide + boilerplate for publishing modern React modules with Rollup.

Canonical URL: https://www.transitivebullsh.it/publishing-baller-react-modules

Author: Travis Fischer

Published: 2017-11-01

Updated: 2026-08-24T07:19:00.000Z

Tags: OSS, React.js

![Publishing Baller React Modules](<https://assets.cultural-alignment.com/personal-site/media/217803f2005b1ab4e5f5aacc0121085ede765ad3dc72de1c73d4c970e5694e6c.jpg>)

<a id="4c8af8399674495e843c35b06e70f71e"></a>

## Intro

![React & NPM living together in harmony.](<https://assets.cultural-alignment.com/personal-site/media/c6964d212975244f201f362d666c9fda2c065d72d922f09ca313a97ca55cfd42.png>)

React & NPM living together in harmony.

Publishing an open source React / Preact component or library to [npm](<https://www.npmjs.com/>) 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](<https://github.com/facebookincubator/create-react-app>) or [create-preact-app](<https://github.com/just-boris/create-preact-app>).

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.

![Kylo Ren attempting to publish his first React module…](<https://assets.cultural-alignment.com/personal-site/media/fa6991d4df2d052f20d5f91e8d9bb03519054f338b3092f36471e9d1e560735a.webp>)

Kylo Ren attempting to publish his first React module…

> The purpose of this article is to help React authors easily publish their own, high quality component modules.

<a id="dda26e810dd742568f28aea206e886e2"></a>

### **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](<https://rollupjs.org/>) for build process and [Babel](<https://babeljs.io/>) for transpilation (we discuss Rollup vs Webpack later on in this article)
- Must come with an *example* app using the [create-react-app](<https://github.com/facebookincubator/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:

1. As a local, hot-reload server for developing your module
1. Easily publishable to github pages so users can quickly demo your module (or comparable hosting alternatives like [surge.sh](<http://surge.sh/>) or [now.sh](<https://zeit.co/now>))

Now that our goals are clearly defined, check out the [boilerplate repo](<https://github.com/transitive-bullshit/react-modern-library-boilerplate>) we’ll be starting from:[*react-modern-library-boilerplate - Boilerplate for publishing modern React modules with Rollup*](<https://github.com/transitive-bullshit/react-modern-library-boilerplate>)

<a id="087ba3c2260543ddb8ab9d3dc2960b15"></a>

## **Walkthrough**

In order to use the [boilerplate](<https://github.com/transitive-bullshit/react-modern-library-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.

<a id="fb5e0de0f0dc4189b907ebc0d4e386a9"></a>

### **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.

```bash
# clone and rename base boilerplate repo
git clone https://github.com/transitive-bullshit/react-modern-library-boilerplate.git
mv react-modern-library-boilerplate react-poop-emoji
cd react-poop-emoji
rm -rf .git

# replace boilerplate placeholders with your module-specific values
mv README.template.md README.md
# find and replace react-modern-library-boilerplate with react-poop-emoji everywhere
```

<a id="beb7f93316c040388dac72f6f35d2bb6"></a>

### **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-emoji `module.

```bash
# run example to start developing your new component against
npm link # the link commands are important for local development
npm install # disregard any warnings about missing peer dependencies
npm start # runs rollup with watch flag

# (in another tab, run the example create-react-app)
cd example
npm link react-poop-emoji
npm install
npm start # runs create-react-app hot-reload dev serve
```

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.

```javascript
import React, { Component } from 'react'
import PropTypes from 'prop-types'

// example of built-in support for importing css styles (optional)
import './styles.css'

export default class ExampleComponent extends Component {
  static propTypes = {
    text: PropTypes.string
  }

  render() {
    const {
      text
    } = this.props

    return (
      <div>
        Example Component: {text}
      </div>
    )
  }
}
```

Here we have the default exported component that comes with the boilerplate. Feel free to edit it to your liking before moving on while testing your changes in the live create-react-app dev server.

<a id="6d3a8c12444f480cb2e5290843433776"></a>

### **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:

```bash
# be sure to update docs
vim README.md
vim package.json

# init and push git repo
git init
git add *
git commit -am "init"
# add git remote and push to remote github repo
```



<a id="38a195c3fc974d57a5a042fa9fefcec6"></a>

### **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](<https://nodejs.org/en/blog/npm/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.

```bash
# update dependencies, devDependencies, and peerDependencies
vim package.json
vim rollup.config.js

# build dist and publish to npm
npm publish
```

<a id="f1d48cfd6e2f4faf8a0f6e0fc5a3d499"></a>

### **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:

```bash
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.](<https://assets.cultural-alignment.com/personal-site/media/77b813ef3c8d3b44f69d2e02e3211e210abcd1a4b335cdd30bddb165623dc37a.gif>)

The Dude eloquently describing the engineering [KISS](<https://en.wikipedia.org/wiki/KISS_principle>) principle.

<a id="e3bc73dc61984845b7c8b701dc4ba730"></a>

## **FAQ**

<a id="958fd3e7bb444a4bb8d74165177dfbd0"></a>

### **Why use Rollup over Webpack?**

For a deeper explanation, I recommend reading Rich Harris’ article [Webpack and Rollup: the same but different](<https://medium.com/webpack/webpack-and-rollup-the-same-but-different-a41ad427058c>). 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.

```javascript
import babel from 'rollup-plugin-babel'
import commonjs from 'rollup-plugin-commonjs'
import postcss from 'rollup-plugin-postcss'
import resolve from 'rollup-plugin-node-resolve'

import pkg from './package.json'

export default {
  input: 'src/index.js',
  output: [
    {
      file: pkg.main,
      format: 'cjs'
    },
    {
      file: pkg.module,
      format: 'es'
    }
  ],
  external: [
    'react',
    'react-dom',
    'prop-types'
  ],
  plugins: [
    resolve(),
    commonjs(),
    postcss({}),
    babel({ exclude: 'node_modules/**' })
  ]
}
```

> Rollup configs are generally more concise for library development. This config transpiles and bundles the module’s source and external dependencies to CommonJS and ES6 formats.



<a id="408315fd97b84730b7f982edb6c6b912"></a>

### **Why use CRA for the example?**

[create-react-app](<https://github.com/facebookincubator/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](<https://github.com/facebookincubator/create-react-app/issues/737>) for more context around this movement.

![](<https://assets.cultural-alignment.com/personal-site/media/ff7378d499ef2a70e97d0598b88fd045971d54a3d04ba79c7da00800363f3088.png>)

<a id="6046f4055b5546a5968145a9a03e0dc1"></a>

### **Where are the tests?**

I recommend that you piggyback off of create-react-app’s built-in [test harness setup](<https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#running-tests>) 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.



<a id="c8ac0cafc8f24647b4ea4e7369bf0921"></a>

### **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!

<a id="e7a36adfd00e4c028a7d36da2cc6ec79"></a>

### **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](<https://github.com/transitive-bullshit/react-modern-library-boilerplate/issues/1>).

<a id="6858ff9ce70343b59f255f1ef28feaeb"></a>

### **What does a published module look like?**

Here is an example react module created from this guide: [react-background-slideshow](<https://github.com/transitive-bullshit/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)](<https://assets.cultural-alignment.com/personal-site/media/6cc960b06fe04d7aeecc18f2cad7d4ca094fd4d190680641a996935cf868fe61.gif>)

Example boilerplate module [react-background-slideshow](<https://github.com/transitive-bullshit/react-background-slideshow>) (animations sped up for [demo](<https://transitive-bullshit.github.io/react-background-slideshow/>))

<a id="6b89ba148d2f408e8b79f5d36317e88f"></a>

## Wrapping up

I’d like to throw a shout out to [js.coach](<https://js.coach/react>), 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](<https://github.com/transitive-bullshit/react-modern-library-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. 😃

[GitHub - transitive-bullshit/create-react-library: CLI for creating reusable react libraries.](<https://github.com/transitive-bullshit/create-react-library>)

CLI for creating reusable react libraries. Contribute to transitive-bullshit/create-react-library development by creating an account on GitHub.