Introduction to publishing a NPM library

Javascriptnpm

Very quick introduction on how to publish your own NPM library.

Quick overview

This note is not meant to be ran blindly.
It's meant to give you a broad enough overview of the subject to start digging deeper by yourself using the resources listed below.

Create the NPM project

First you need to start from a npm package:

npm init

This will prompt you and create files including: package.json:

package.json
{
  "name": "get-current-time",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC"
}

See the main field? This field will point to the file being accessed when you will install and import this library.

index.js
const getCurrentTime = () => {
  return new Date().toISOString();
};

module.exports = getCurrentTime;

Publishing

# Login, you will not push stuff to npm if you do not login to npm
npm login

# ... and publish!
npm publish

Consume your library

Now you can use your library as any other.

Install it:

yarn add get-current-time

npm i get-current-time

And use it:

whatever.js
const getCurrentTime = require("get-current-time");

console.log("Current time is: ", getCurrentTime());

You should have a good overview of what it takes to publish a library.\

Limitations & resources

This setup has a lot of limitations and is too simple to release a good library today.
Let's see together some of the limitations and possible solutions:

Package name collisions

package.json
{
  "name": "get-current-time",
   ...
}

get-current-time can only ever be taken once, so you are prone to name collisions.

To solve this use scopes. See doc from npm article

Doing so will change it to:

package.json
{
  "name": "@my-username/get-current-time",
   ...
}

Much better!

Versioning

You will also have to handle package versioning, meaning if you publish your code on version 1.0.0, that's it, no more update using this version.
Let's say you want to fix a bug, you will have to bump the version to 1.0.1 and then publish.
Is it a major change that impacts how user uses the library? bump a major version to 2.0.0\

package.json
{
  // You will have to update version if you want to publish updates
  "version": "2.14.3",
  ...
}

Versioning is up to library authors, however there are good resources and efforts around standardization.
Here are some great resources to learn more:

npm version - npm
About semantic versioning - npm
Understanding npm versioning - Benny Code

Code & export complexity

In real life you should use typescript for your library and will probably use multiple files.
Additionally you will also have to handle ESM, CJS and Typescript exports for import/require.

My must have to handle this complexity is tsup. A great library that bundles your code for a very friendly export.

Publish ESM and CJS - Anthony Fu

Testing

Testing is not required, especially at start.

However If you plan on your package to be:

  • reliable
  • contributed to
  • maintainable

You may want to look into adding tests.

A note will be added around this topic so stay tuned

Automation

You will need automation when your library becomes serious, gets contributed to and need to be reliable.

Use a CI to automate tests, package publishing and changelogs.

Github Actions Publish NodeJS packages

Great article(s)

https://zellwk.com/blog/publish-to-npm/ - Zell
Overall great introduction to publishing a library also using the np package to help you publish your package.