Publishing my first NPM package

For the past few weeks I’ve been working on a side project and documenting it in a series of blog posts. It’s been a pretty lengthy project so I wanted to take a quick break and write about my first experience publishing a package to NPM. The more I work in the code editor, I begin to see the need for helper functions that have common usage regardless of the project. My previous solutions for this were to re-write the helper function from scratch or, moderately more efficiently, copy and paste one I had written in a different project.

Today I decided it was time to at least start collecting these helpers in their own repo so I didn’t have to go hunting down that one project from months ago where I think I last used the function. I created a GitHub repo https://github.com/lucsedirae/helper-library and loaded the couple of helpers into an index.js file that I am constantly searching for to get it started.

Then the thought occurred to me that it would be nice to just install this index.js file via NPM and be able to import the functions like I would any other NPM published dependency. I wasn’t sure where to start so I did some Googling and discovered the process was actually really easy and NPM gives you unlimited public access packages with their basic free tier membership.

Initializing package.json

The first step after cloning down my repo that I initialized from the GitHub website GUI was to run npm init from the root directory of my new repo on my local machine. This executes a command line script that asks for basic information about your package and creates a package.json file in the project directory. It’s important to have a readme file, a license file, and make sure the NPM “entry point” is the name of the file you want to store your functions in. The default entry point suggested by the npm init script is index.js so that’s what I went with.

Inside index.js I wrote out the couple of helpers I am always searching for. The one I needed this morning was formatDate(). It’s a simple function that takes in an incoming UTI time stamp value, creates a new JavaScript date value using the Date constructor and then returns that new value using the toLocaleDateString method. I have some plans to expand the functionality of this over time so I use it regularly as a helper instead of doing both of those other processes inline for each use case. This is a much lighter-weight solution than importing a time-handling library like moment.js and keeps my codebase clean.

I pushed these initial functions up to my GitHub repo and was ready to publish the package to NPM.

Publish to NPM

Before you can actually publish your package you need to create an NPM account. You can do this from their website at https://www.npmjs.com/ or from the command line by running npm adduser. Make sure to select a password longer than 10 characters. NPM will send you an email to confirm your address and once you have clicked on their confirmation link you are ready to publish.

Publishing was as easy as running npm publish --access public from the command line inside the root directory of the package you wish to publish. Once that script completed, I was able to test my publication inside a project. My package is published as my GitHub user name so I navigated to the project I wanted to use the function in and ran npm i lucsedirae. Then I imported the function in the file where I needed it to run:

import { formatDate } from 'lucsedirae';

Then called the function:

const todaysDate = formatDate(Date.now());

And voila! It worked like a charm!

Caution!

I noticed after running npm i lucsedirae that there were a lot of vulnerability notices in the terminal. I haven’t had a chance to dig into how to fix these issues but I do plan on doing so to expand my understanding of NPM and its package publishing environment. So, with that said, I would not recommend using a package like this in a production environment. When I publish my project I will replace that import with the helper functions hosted in a utils file inside the project until I better understand the security implication with using my own NPM package. But as a learning experience and a way to store common helper functions for practice projects, I was really satisfied with the results.