How to create a JavaScript library and publish it to npm
Did you ever write some amazing code that you wanted to use in all your projects and you ended up manually copying it over ? I did. Even if I knew I could do it in a better way, I thought that the whole process of creating and publishing an npm package is very complicated. However, after doing some research I found out that it is not. It is actually quite simple.
At the end of this article, you should be able to create your own minimal JavaScript utilities library and publish it to npm so that you (and others!) can use it in any project.
This guide assumes that you’ve got Node.js installed on your machine and that you are somewhat familiar with the JavaScript ecosystem.
Step 1. Creating the project
We will start from scratch and use npm to start a project.
Create a root folder for your project and name it however you want. Throughout this guide I will use agm-awesome-utils-tutorial as the project name, but you should choose your own name and replace it accordingly.
In this folder, create a src folder with an empty index.js file inside it.
Next open a terminal in the root folder and run npm init to generate a package.json file. Do not worry too much about the configuration options for this as we will modify its contents later.
You should end up with the following structure:
agm-awesome-utils-tutorial
├── src
── index.js
└── package.json
Step 2. Install dev dependencies
Babel
We will write the code using ES6+ syntax, therefore we will use Babel to transpile it for older environments.
npm i -D @babel/core @babel/preset-env
Rollup & Rollup Plugins
We will use Rollup as the JavaScript bundler for this project. If you are not sure what a JavaScript bundler is, why do we need one and what options there are I suggest reading this article. For another good comparison of the most popular JS bundlers as of 2020 check this out.
Additionally, we need some Rollup plugins to make it work with Babel and to produce builds in multiple module formats (UMD, CJS, ESM).
npm i -D rollup rollup-plugin-babel rollup-plugin-commonjs rollup-plugin-node-resolve
Step 3. Configure Babel & Rollup
Babel
Create a .babelrc file in the root folder.
Rollup
Create a rollup.config.js file in the root folder. Pay attention to the input and output properties.
We also need to update the scripts in package.json and configure the entry point for each module format (CJS, ESM, UMD).
Step 4. Write some code
For the purpose of this tutorial, our library will be really simple and contain a single function that capitalizes the first letter of a string.
Add the following code in the index.js file:
Step 5. Write tests
A very important part of creating a library is testing it, to ensure that the code you are publishing works as expected and has no bugs.
In the root folder, create a test folder with a spec.js file inside it.
awesome-utils
├── src
── index.js
├── test
── spec.js
└── package.json
In the spec.js file, we will use the Node.js assert API to test our function.
Run the tests using the test script we previously added in the package.json file.
npm run test
Step 6. Publish to npm
Create npm account
In order to publish the package to npm you will need an npm account. You can create one here.
Log in to your npm account
After creating an account, open a terminal, navigate to the root folder of your project and use the following command:
npm login
You will be asked for you username, password, and email.
Publishing
After successfully logging in, simply run the following command:
npm publish
Each npm package must have a unique name, therefore the publish might fail if you have used the same package name as in this tutorial.
That’s it! Your package should now be published on npm and available for everyone to use!
You should now be able to install it in any project similar to how you install any other dependency.
npm install agm-awesome-utils-tutorial
Your package name will be the one you configured in your package.json file
Next Steps
This guide covered a simple example of creating and publishing a very basic package. In a real world scenario, things can (and will) get slightly more complex.
Here are some improvements to consider for the existing solution:
- Make your code publicly available on Github. Add a license and documentation for your library
- Improve testing using a testing framework such as Mocha or Jest
- Automate the publish process. You can take a look at release-it and semantic-release
All the code for this tutorial is available on Github.