typescript
nx
npm

This article exclusively concentrates on the process of creating libraries with Nx and publishing them on Npm. It is not an in-depth exploration of Nx or any other mentioned technologies. In addition, only a manual process is described not a fully automated one.

Publishing Nx Generated TypeScript Libraries on Npm

If you find yourself needing to reuse code across multiple applications, I have great news for you. Today, we're going to create TypeScript library using Nx, and we'll publish it on Npm. In our specific case, it will be @greenstack/core.

Nowadays, there are many excellent tools designed for such tasks, and Nx is one of them. Let's begin by creating an Nx project!

Creating Nx Project

Before we start setting up the Nx project, it's important to ensure we're in sync with the versions of Node and Npm I have locally. If your versions differ, make sure that the version of Nx you plan to use is compatible with your version of Node. You can check the minimum required versions in the documentation.

So, I've:

node: 18.18.0
npm: 10.5.0

All the progress we're making will be tracked in this: greenstack repository.

It's time for some magic. Open your repository, navigate to the terminal, and simply enter the following commands in CLI: npm i -g nx and npx create-nx-workspace@latest [name-of-repository]. You'll be prompted to pick up some configuration settings. Confirm additional packages to be installed:

NX Workspace Package NX Workspace Package Install

Then, the CLI will ask you to pick up some settings connected with the type of your workspace, stack setup, and Github Actions. Follow these:

Settings Overview Options to Select

We've selected none for the first question, it's because we want to have a minimal, empty Nx workspace. We'll add libraries via generation commands soon.

Next, we've picked integrated repository because this particular setup, allows us to have a single package.json to handle all libraries or applications versions. It's important if you want to avoid additional maintenance connected with different version mismatches. Imagine if the consumer application will have 2 different versions of some package - it will be hell!

Lastly, we've picked up Github Nx Cloud setup, because we'll have our repository stored on Github and we want to have setup for Github Actions. It will give us in addition:

  1. Caching to speed up builds/checks
  2. Cost management
  3. Analytics
  4. Parallel computation

Here you have the full setup that I've picked up.

Complete Nx Setup NX Setup Guide

Now, to continue the next steps let's navigate to the created directory. In my case it's greenstack. Every next command needs to be executed from this place. To achieve it type cd [name-of-repository].

Creating Plain TypeScript Library

Thanks to the command that we used at the beginning: npm i -g nx, now we've access to powerful generation commands. Now, we may type: npx nx g @nrwl/js:lib core --importPath=@greenstack/core --publishable. Here is what I've picked up when CLI asked me:

TypeScript Library Creation TypeScript Library Created

You may prefer other options, I'm using Vite daily, so I've picked up this to maintain the building process of my library.

Preparing Library Build

Our library contains only one function that looks like this:

export function core(): string {
  return 'core';
}

Before we publish it on Npm, we need to build it first. To achieve that, we need to type the following command: npx nx build core. The core is the name of the library. This is the result:

TypeScript Library Build Result Build Result

After the process is finished, you'll see the magic dist directory under which every library build will be stored.

The Dist Directory The Dist Directory Structure

Publishing TypeScript Library on Npm

First of all, we need to sign in to the Npm account. To achieve it type npm login and sign in via browser or credentials - up to you.

Now we need to create an organization on Npm. If you want to publish your packages just like name-of-package, instead of @organization/name-of-package, you can skip this step. However, for this article, we want to have all packages available to be installed under @greenstack/name-of-library.

Creating organization on Npm is straightforward. Just go to Npm, click the following Add organization link, and fill out the form. At the end you'll see the following screen:

Npm Organization Creation Process Creating Npm organization

The last step is just a simple command. We need to navigate to greenstack/dist/core directory and paste the following line in the terminal: npm publish --access public. Now our package is available on Npm!

TypeScript Library is on Npm TypeScript Library Deployed on Npm

Updating Library Code and Version

Let's say you provided changes to your library and want to publish a new version of it on Npm. The process stays the same always:

  1. You need to manually change the version of the library package.json. We'll change the version from 0.0.1 to 0.0.2.
  2. The command npx nx build [name-of-library] must be executed again.
  3. You need to navigate to dist/name-of-lib and run npm publish.

Then, the new version will be available on Npm.

Version Updated The New Version of Package is Available

Sometimes due to caching NX is not updating package.json under dist/name-of-lib directory. If this happens to you, just change it manually. Here is an issue that describes this problem: Issue with package.json version during build.

Installation and Testing

To test if it works or not, just type in your application npm install @organization/name-of-lib. It will install the latest version that you've published.

Summary

Now you know how to publish your packages generated by Nx on Npm. The process described in the article can be automated via custom scripts or with packages like semantic-release. However, it's not a part of this article due to the complexity of this topic.