Usually when you want to use some React components, you probably search for them on Npm and it’s really awesome that React is embracing the Npm ecosystem. Let's take a look how you might want to prepare a React Npm package to be able to use it in your projects, publish on Npm, and share it with others.
What we’ll cover here:
- files and folders structure
- configuration for tests
- configuration for linting
- configuration for transpilation
Files and folders structure and relations
Let's take a look at the boilerplate which we will describe here. You can find it here: react-npm-boilerplate. This is based on excellent work by the Kadira.io team. They've built a boilerplate for standard Npm packages called npm-base. The version for React has a couple of changes but generally this is almost the same. So when you want to prepare a standard Npm module, you can use
npm-base, and when you need to create the React component, take a look at
Let's get back to the file and folder structure. As you can see, in the
react-npm-boilerplate repository we have some configuration files in the root directory. We'll talk about them later. For now, the most important files are
package.json. As you probably know,
package.json is a standard Npm configuration file. In the
index.js file, we have the main export. It points to the
dist folder which will be created after the
prepublish task has been run. It’s configured in the
scripts/prepublish.sh file and what it does is basically transpilation to ES5. It will place all transpiled files in the
dist folder. We'll talk about that later.
You will work in the
src folder. You can write your React component code there. If you look in the repo, you’ll find an example component just to make it simpler to start. Also in the
src folder we have the
__tests__ folder. There are your tests which we'll cover later. For now it's good to know where the test files are located.
You can find the ESLint configuration file in the root directory which you can of course change and adjust to your needs, this is just the config which I used recently.
This is basically all about the file structure. In short, you need to work in
src folder and then transpile with
prepublish task into
dist folder. You can run many tasks like testing and linting. It will take your files from
__tests__ folders and process them.
Next, we’ll take a closer look at the
package.json where all tasks configuration is.
Tests are really important here. We want to be able to run automatic tests for our React component. We may even want to run them in the background with the
--watch flag, so every change will be validated by our automatic test cases. Ok, but what exactly do we have here? We use awesome tools like Mocha and Enzyme to test React components. If you don't know them, you can read all about these projects on the Internet. Basically they are projects which provides many useful tools for testing. All test files should be located in the
__tests__ folder. This is how it is configured. You can change it if you want in
package.json file and some other places.
Test tasks are configured in the
package.json file. You can run them by:
npm test- if you want to run tests and linting
npm run testonly- if you want to run only tests
npm run test-watchif you want to run tests, watch all files and rerun the tests if something changes
Tests uses Mocha runtime and Enzyme library. Sinon and Chai are also used here. You can find example test cases in the
src/__tests__ folder. In the
package.json file, we have provided Mocha options. This is important because here we can include paths for test files, but also all options and environment configuration for Mocha which should be provided. In our case ,we want to pass some important setup before we run tests. Here we need the
scripts/mocha_runner file. You can open it and see what it’s about. Because we need to test DOM in the Node command line environment, we should use the JSDOM library which will emulate DOM for us. This is important because some tools from the Enzyme library need this configuration, like for example the mount tool.
Everything you need to test your React component is configured in this boilerplate. You have also a test case for an example React component. There are three main tools used from Enzyme. You can see it in the
When you finish your test cases, you can always run
npm run testonly in the console to check how it’s going.
.eslintrc and you'll find all rules there. You can of course modify it and adjust it for your needs. You'll find all possible configuration rules on the ESLint official website. In this boilerplate, I've provided rules which I usually use.
We have also some linting tasks configured here. They are:
lint- run eslint command for src folder
lint-fix- fix all ESLint problems
test- you can also run ESLint with tests
You can also write your React components using ES2015. Then, when you are ready, you can transpile it to the ES5 standard. All files will land in the newly created
dist folder and these files will be used as your main component files after publishing it to Npm.
The transpilation process is possible with Babel tools which are responsible for providing proper ES5 transpiled code. The configuration is quite simple. We use some of Babel's tools which are listed in the
package.json file. We also use a special runtime file -
scripts/prepublish.sh - which is attached as a prepublish Npm task. So whenever you run
npm publish or
npm pack, the
prepublish hook should be run and all your files from the
src folder should be transpiled and copied into the
dist folder. You can of course run it by hand by
npm run prepublish.
prepublish.sh file is quite simple. You can open it and see how it looks. Basically we have here the
babel command line tool call which takes some options. We provide a plugin for transpilation transformations by using the
--plugin flag. As a default, we use the
transform-runtime plugin. But if you need to, you can also use, for example
transform-es2015-modules-umd, when you need a Universal Module Definition pattern in your transpiled ES5 files. Just remember to add this plugin to your
package.json dependencies. You will find its full name in the Npm repository. Of course this is just an example and you can find more transformation plugins on Babel's website. Next we also need to pass output paths - here it is
dist directory and we also want to ignore the
Basically this is all you need to transpile your files to ES5 format. Of course you can read more about Babel and its configuration on their website.
Some closing words
This is a short and general description of a Npm package boilerplate which is designed to use with React when building React components with ES2015. It provides testing and linting configuration and also Babel transpilation. You can use it as a starting point in your work when you decide to create React reusable components that you want to publish on Npm. This boilerplate is based on awesome npm-base repository. Check it out too.
For more information about the topic, I encourage you to read about these tools:
Boilerplate described here:
Let me know what you think about it. Feel free to put your questions in the comments below. I’m also on Twitter.