bbgrabbag/demo-component

Publishing React Components in NPM (Intro to Webpack)

Goal

• Write, Test, and Publish your own React Component.
• Learn how to use webpack to build an ES6 / JSX friendly dev environment.
• Learn basic documentation best practices.

Summary

We will be creating a single React component that will be directly importable into any ReactJS / NodeJS project using NPM.

We will use webpack to transpile JSX and ES6 into ES5 so that it is browser-compatible.

In order to test our React component as we develop, we will make a separate React environment using create-react-app.

Successful open source projects require clear, concise, and informative documentation. We will go over the basics of writing good documentation so other developers know how to implement your project successfully.

Setup

git clone https://github.com/bbgrabbag/demo-component.git

Your project directory should have the following folders / files:

/project-folder
    /src
        index.js
    .babelrc
    .gitignore
    .nvmrc
    package.json
    README.md
    webpack.config.js

You will want to alter the fields in package.json to reflect what your project is actually about (repository, description, author, etc.).

Webpack

What is it?

Webpack is a module bundler. It simply takes as input a set of code modules, combines them, and outputs a new file.

We are using webpack for two reasons:

1. React Components are very modular.
2. Webpack, combined with a transpiler like Babel, allows us to write ES6 and JSX without worrying about browser incompatibility.

Installing Dependencies and Configuring Webpack

• npm install

Add this configuration object in .babelrc, which defines which presets and plugins to use when babel is transpiling:

{
  "presets": ["env"],
  "plugins": [
    "transform-object-rest-spread",
    "transform-react-jsx"
  ]
}

The configuration object in webpack.config.js defines the rules for how to bundle / transpile our ES6 code:

//webpack.config.js

let path = require('path');
module.exports = {
    //defines the path to the input module:
  entry: './src/index.js', 
    //defines the filename and path for the output:
  output: {
    path: path.resolve(__dirname, 'build'),
    filename: 'index.js',
    libraryTarget: 'commonjs2' 
  },
    //defines the rules for how to transpile .js and .css files:
  module: {
    rules: [
      {
        test: /\.js$/,
        include: path.resolve(__dirname, 'src'),
        exclude: /(node_modules|bower_components|build)/,
        use: {
          loader: 'babel-loader',
          options: {
            presets: ['env']
          }
        }
      },
      {
        test: /\.css$/,
        use: [ 'style-loader', 'css-loader' ]
      }
    ]
  },
  externals: {
    'react': 'commonjs react' 
  }
};

In order to implement webpack we need to add a couple scripts in package.json:

"scripts":{
    "test": "echo \"Error: no test specified\" && exit 1",
    "start": "webpack --watch",
    "build": "webpack"
}

Now, when we run npm start webpack will automatically bundle our code every time it detects a change while we edit. npm run build will simply bundle it on command.

Once all your files are all set up, simply run:

• npm run start
• npm link (this allows you to import your component into the test environment)

Building the Component

The /src folder is where you will write all your code. Let's make a simple React Component:

// demo-component/src/index.js
import React, { Component } from 'react'

export default class DemoComponent extends Component {
    render() {
        return (
            <div>
                <h1>DEMO COMPONENT!!!</h1>
            </div>
        )
    }
}

That was easy.

Notes on Designing Components

This is just a demo but there are a few things to keep in mind when building a React Component for the open source community:

• Reusability
  • Your component should be easily importable into any part of someone's project.
• Configurability
  • Anticipate a wide area of use cases; don't pigeon-hole your user.
  • Create a balance between ease-of-use and complexity. It should work out of the box with little tinkering, but also provide for more advanced functionality if needed.
• Independence
  • Don't assume the existence of other dependencies, or at least make it clear when they are needed.
  • Should function on its own without relying on an implicit environment.

Testing the Component

Components can be major projects on their own. It would be a pain to attempt to write all our code at once, publish it, and then import it into a new project only to find out we have an error.

I'm going to assume the reader has a basic knowledge of how to set up a React environment using create-react-app. In a separate project folder called test-env create a new React app and make a component called Tester.js. Render it from src/index.js and run npm start to get the environment going. Don't forget to import the Demo component!

// /test-env/src/Tester.js

import React from 'react';
import DemoComponent from "demo-component";

export default function Tester(props){
    return(
        <div>
            <DemoComponent />
        </div>
    )
}

You should see a message displayed on the screen in your browser!

As you make changes to DemoComponent, you should see them update immediately in your browser as long as your test environment is running.

Documentation Principles

Clarity

It is very important that someone using your component knows exactly what is does, why it's useful, and how to interface with it. Your README.md needs to make this explicit from the outset.

Provide an Example

You should provide a simple example of code which demonstrates a real use case.

Props Glossary

If your component uses props provide a table of each prop, its default value, and a brief description:

Prop	Default Value	Description	Required
propName	null	Lorem Ipsum	true

Gotchas

Explain any other gotchas or caveats that may not be obvious to the developers using your module. For example, if you style a module to only fit the height / width of its containing element, mention it!

Publish

Once you are happy with how your component works and your documentation is complete, you're ready to publish!

It's insanely simple. From your project folder run:

• npm run build
• npm publish

Anytime you need to make an edit to your package make sure to adjust the version property in package.json.

Congrats!