Creating an NPM Package for Distribution

Setting Up the Project

These instructions start from scratch, creating a new project and taking the necessary steps to produce a redistributable package.

First, we need to initialise a new NPM project.

npm init -yCode language: plaintext (plaintext)

Since we’re doing a TypeScript project in this case, we need to generate a TypeScript configuration file.

tsc --initCode language: plaintext (plaintext)

In the tsconfig.json file (the TypeScript configuration file), uncomment the property that will cause TypeScript definition files to be generated for the code. Also, set the TypeScript output directory to “./dist”.

"declaration": true,
"outDir": "./dist"Code language: plaintext (plaintext)

Now, open the package.json file and add a property for the TypeScript definition file details, just under the existing “main” property.

"types": "dist/index.d.ts"Code language: plaintext (plaintext)

Assuming you are using Git, NPM will automatically exclude files in .gitignore from being published, but if you have defined a .npmignore file then this will overwrite git-ignore behaviours.

Documenting Your Package

Write a Readme.md file as this will show up in the feed as a description. It’s a good idea to provide good quality instructions on usage, and doesn’t hurt to add a to more comprehensive documentation if you have any.

Here is a good article on formatting your readme file. The MD file extension indicates it is a mark-down formatted file. HINT: if you are using Azure DevOps and are too lazy to read all about mark-down formatting then DevOps Wiki articles use mark-down formatting so you could draft the readme in a DevOps Wiki page and copy it to your readme.md file afterwards.

Developing the Code

Now, pause while code is being developed and tested. (We’ll skip this step in the article, and the wider configuration of the code project, and jump straight to packaging.)

Preparing to Publish

It is a good idea to check your package is going to work as expected. To do this we’ll first need to build it and then package it up into a local tarball file.

npm run build
npm packCode language: plaintext (plaintext)

You can also check that it all works as expected, run the following in the package root folder:

npm linkCode language: plaintext (plaintext)

If everything works as expected, go to another project folder and run:

npm link <your-package-name-here>Code language: plaintext (plaintext)

The package name will be whatever was set in the package.json file as the “name”, and usually defaults to the root folder name.

Publishing

Before publishing, you have to tell NPM where your package is being uploaded to. Add a new file to the root project folder called “.npmrc”. Add a registry location (URL) to the file. Here is an example for a private NPM registry hosted on Azure DevOps:

registry=https://YourTenantHere.pkgs.visualstudio.com/_packaging/YourDevOpsProjectHere/npm/registry/
always-auth=trueCode language: plaintext (plaintext)

Depending on the server you are targeting you may need to perform additional actions. For example, if using Azure DevOps you’ll want to enable authentication to allow you to upload the package:

npm i vsts-npm-auth
vsts-npm-auth -config .npmrcCode language: plaintext (plaintext)

Finally, run the following to publish your package:

npm publish

That’s it – you’ve just published your NPM package.