John Biundo for NestJS

Posted on Aug 19, 2019

Publishing NestJS Packages with npm

#nestjs #npm #package #nest

John is a member of the NestJS core team, primarily contributing to the documentation.

This is the first in a multi-part series on building re-usable npm packages for NestJS. This article focuses on the mechanics of the process:

building a simple npm package
consuming and testing it locally in a NestJS app
publishing it to NPM

This article lays the foundation for future articles in this series, which delve into more complex NestJS packages.

Intro

We all interact with the npm registry on a daily basis. Usually the registry itself, and how it works, are conveniently relegated to the background - we don't have to think about the details when we run npm install. But sometimes we need to work with the registry more directly - perhaps we're publishing a core infrastructure/utility package for private use across teams within an organization, or maybe we're releasing an open source package for public use.

Publishing a package for the first time, then seeing it install with npm install is pretty fun.

And it's surprisingly easy. While there are plenty of general npm tutorials out there, I've created this tutorial, along with a package starter repository that you can quickly clone to set things up in a standard way, and skip past some of the little hurdles. While there really isn't anything Nest-specific about this, TypeScript can introduce a wrinkle or two not typically covered in other npm tutorials. And combined with the the NestJS environment, you can enjoy a productive iterative development/deployment workflow if you follow a few basic steps. That's what I'll cover here. Follow along, and you should be able to publish a basic NestJS package in about 15 minutes.

As to why you want to do this, I can think of at least two great reasons:
1) Learning how to publish a package demystifies one of the things we tend to take for granted. It probably ought to be on the resume of any self-respecting full stack developer. 😃
2) Whether you publish to the npmjs.com registry, or a private one, publishing an npm package is the standard way of creating and sharing re-usable packages.

Again, while the sample package we'll build in this tutorial is trivial, this article lays the foundation for several more articles that will go into detail on much more sophisticated modules. Stay tuned!

Pre-requisites

If you plan to follow the steps in this article, make sure you have an account at www.npmjs.com (you can use a free one for this exercise, and indeed, unless you want to publish private packages, you can stick with a free account). You could also publish to a private npm registry like verdaccio, but setting that up is beyond the scope of this article.

Setting up for development

If you're live-coding along with reading this article, I have a couple of brief recommendations.

First, note that we'll actually be working on two separate but related bits of code. One for the npm package, and one for a companion NestJS app that will consume and exercise the package.

I recommend sticking with the names used below to keep things properly synchronized. If you're building your own real package with its own unique name, just make sure to synchronize the name you choose across the various places it occurs (folders, package.json, npmjs, git, etc.).

Next, I recommend you open two command line windows (as well as two editing sessions) to work on both bits of code simultaneously. This will help you get the feel of a useful development pattern for building a package in an iterative fashion. The rest of this tutorial will refer to these two command line windows. If you prefer to work in a single command line window, just pay careful attention to what folder you're in as you execute each step!

Setting up the folders

In terminal window 1, create a new folder. This will be the parent folder for both parts of the project: the package we're building, and our small companion NestJS app.

mkdir nestmod && cd nestmod

Clone the module starter repo

In terminal window 1, start by cloning the nestjs-package-starter repo. This is a starter repo that sets up a lot of the default details for your NestJS related npm package. These details can be a bit tedious to get right.

git clone https://github.com/nestjsplus/nestjs-package-starter.git

Once completed, this step should result in a brand new package template in the nestjs-package-starter sub-folder.

Now install its dependencies. Still in terminal window 1:

cd nestjs-package-starter
npm install

Create the test app

In your second terminal window, make sure you start out in the top level folder you created (I created nestmod above so that's what I would use; use whatever folder you created to follow along with the tutorial). Scaffold the small NestJS app we'll be using to exercise our package.

nest new test-app

Choose your preferred package manager (npm or yarn), and wait a moment while the Nest CLI builds your starter app.

Your folder structure should look similar to this now:

nestmod
└─── nestjs-package-starter
│   └───node_modules
│   └───src
│   ...
└─── test-app
│   └───node_modules
│   └───src
│   ...

Build the package

Take a moment to poke around in the nestjs-package-starter folder. Here are a few things to notice:

1) The src folder has two files:

test.ts is the entire functionality of our package; it exports one simple test function we'll import into our Nest test-app to prove to ourselves that we've actually installed and are using the package.
index.ts exports the test.ts function from the folder (it's a barrel file).

2) The package.json file has a number of interesting parts. We'll delve into several of these throughout the tutorial. One to notice now is the different types of package dependencies that are apparent:

regular dependencies are those required to run our code; these should be anything in addition to, but not including NestJS itself. For example, if we were using the dotenv package in our code, this is something that is not provided by NestJS itself, so it would belong in dependencies.
peerDependencies: since this is a NestJS-based package, we use this section to declare that it is compatible with Nest version 6 (a minimum of 6.0.0). This means we assume that the person using the package has a compatible NestJS environment that we can rely on. Mentioning just the @nestjs/common package is sufficient for this purpose. Specifying a version of ^6.0.0 gives us broad compatibility with any minor versions of NestJS the user may have installed.
devDependencies: these are the packages we need only for development; since we expect to build a Nest-based package, we need Nest in our development environment, along with testing utilities, TypeScript, etc. These dev dependencies should be pretty much identical to the regular devDependencies you have when building a normal Nest app. For example, compare these to the devDependencies entry in the test-app and they should be identical.

In terminal window 1, make sure you're still in the folder where you cloned the nestjs-package-starter, and build the package with:

npm run build

The npm build script is trivially simple: it just runs the TypeScript compiler in the folder configured as the rootDir in our tsconfig.json file. Speaking of which, let's take a quick look at tsconfig.json, which kind of "teams up" with package.json to control how our package is built.

The most notable things in the tsconfig.json file are:

declaration: true ensures that our type files are generated, which helps consumers of the package benefit from TypeScript type checking and editor features like intellisense.
the two Decorators flags ensure that TypeScript decorators work properly.
outDir controls where our compiled code is published.
rootdir, along with the top-level include and exclude entries, control which source code is compiled.

Take another quick peek at package.json, and note the "main": "dist/test.js" entry. This is the last piece of the "packaging puzzle". The build script compiles our TypeScript into JavaScript in the dist folder; the barrel file (index.ts) ensures that our function is exported and publicly visible; the "main" entry in our package.json tells the module loader where to discover the exported symbols from our package when it's imported.

So we've now compiled the TypeScript and prepared it for deployment in a package.

Install the package into the test app

You now have a full-fledged npm package, though it's only available locally. You can use the package in test-app with a familiar-looking npm command.

In terminal window 2, change to the folder created by the nest new test-app command, where our test app lives.

cd nestmod/test-app

Use npm to install the package we just built into our test app.

npm install ../nestjs-package-starter

The main difference from a normal npm install, I'm sure you've noticed, is that you are referring to a combination of a path (the .. part) and a name (the nestjs-package-starter part), rather than the typical usage (when pulling from the npmjs.com registry) which uses just a package name. This illustrates the simple process enabled by npm for developing packages: npm install works exactly the same for local packages as it does for remote packages downloaded from npmjs.com. You can see this clearly by noticing that in testapp/package.json, there's an entry like:
"@nestjsplus/nestjs-package-starter": "file:../nestjs-package-starter"

Use the package in the test app

The template package exports a single simple test function. Examine nestjs-package-starter/src/test.ts to see it:

// nestjs-package-starter/src/test.ts
export function getHello(): string {
  return 'Hello from the new package!';
}

Now that you've installed the new package in test-app, it's available like any npm package, and you can use it in the normal fashion. Open test-app/src/app.controller.ts and import the function; make sure the file looks like this:

// test-app/src/app.controller.ts
import { Controller, Get } from '@nestjs/common';
import { getHello } from '@nestjsplus/nestjs-package-starter';

@Controller()
export class AppController {
  @Get()
  getHello(): string {
    return getHello();
  }
}

In terminal window 2, start test-app (using start:dev is recommended here so we can make iterative changes):

npm run start:dev

In a browser, head on over to http://localhost:3000 and see the message coming from the imported package function.

If you've followed along so far, let's do one more thing that shows how easy it is to continue to iterate. Make a simple change to the getHello() function exported by the package (I like to change it to return 'Buon Giorno!' 😄).

Now, make sure the test app is still running in dev mode (e.g., npm run start:dev) in terminal window 2, then, in terminal window 1, rebuild the package with:

npm run build

Notice that in terminal window 2, since we're linked to the local package, the dev server will automatically restart as the package is rebuilt (it may show errors for a few seconds while the process completes). This highlights a key thing to keep in mind: whenever you make local changes to the package, you must rebuild it before it's visible to consumers of the package. Obviously this means you must rebuild before you publish it.

To make sure this last bit happens, take another look at the package.json file. The prepare script is a special script recognized by the npm publish command. Whenever you publish (which we'll do in a moment), the prepare script will be run before publishing. Note that there are several other such npm "hooks" available that will let you do things like run lint, check in/tag source code to your git repo, etc. See here for details.

When you refresh your page at localhost:3000, you should see your nice warm Italian greeting!

Publish the package

We're now ready to push our newborn package out of the nest and onto the 'net (ugghh, sorry for the bad pun). To complete this step, you'll need a free account at www.npmjs.com. If you don't have one, go to the signup page to get one.

Give the package a unique scoped name for npm

A few notes about npm

npm names
All npm packages have a name. If the name starts with @, it's a scoped name. Scoped names are useful to create a unique namespace for your packages. If you and I both publish nestjs-package-starter to npmjs.org, there will be a collision. Whoever publishes first owns the name. But if I publish a scoped package name, such as @johnbiundo/nestjs-package-starter, you can publish your own copy at @yournpmjsname/nestjs-package-starter, and they both happily co-exist. Anyone that wants mine will do npm install @johnbiundo/nestjs-package-starter, and anyone that wants yours will do npm install @yournpmjsname/nestjs-package-starter. Read more about scopes here.
npm public packages
npm lets you publish packages for free as long as they're public. If you want to publish private packages (say for sharing only within your company), you'll need a private account. Alternatively, you can set up an internal private registry with a registry server like verdaccio.
npm orgs
In addition to publishing packages scoped under your name, you can create a free npm org to give your packages a more custom name (scope). For example, I publish several packages under the org @nestjsplus. Read more about npm orgs here.

Once you're ready, open the package.json file for the package and change the following entries:

name: your scoped package name, something like @mynpmjsname/my-new-package.
version: choose a starting version number; I comment a bit more about this below, but something like 1.0.0 will work fine for now.
author: your name and email, in a format like John Biundo <john@email.com>.

Later, you'll want to customize other things like the description, license, keywords, repository links, etc. None of those are very TypeScript or NestJS-specific, so we won't cover them here, but a little Googling will turn up lots of good articles and help for them.

Once ready, publish the package

Note: Each time you re-publish the package, you'll have to change the version field in package.json (or the publish step will fail). It's best practice to use semantic versioning ("semver") for npm packages.

In terminal window 1, run:

npm publish

The output of this step shows you exactly what files are bundled up and sent to npmjs.org to create your package, as well as the version number and some other metadata.

Search for your package on www.npmjs.com

Head on over to https://www.npmjs.org, and search for your package.

Install the published npm package in your test app

Now that the package is live on npm, you can install it as you would any package.

In terminal window 2, first, uninstall the local one we created and installed about 10 minutes ago.

npm uninstall @nestjsplus/nestjs-package-starter

Now, install your shiny new npm package from the internet. Change the names as appropriate below:

npm install @yournpmjsname/your-package

Finally, edit your test app to reflect the new npm package name (paying attention to using the correct "scoped" name if you published that way). For example:

// src/app.controller.ts
import { Controller, Get } from '@nestjs/common';
import { getHello } from '@yournpmjsname/your-new-package';

@Controller()
export class AppController {
  @Get()
  getHello(): string {
    return getHello();
  }
}

Fire up the app, and you'll be using your new package!

Now that you know how easy it is to publish an npm package, stay tuned for the next articles in this series where we'll cover building more interesting NestJS modules.

Feel free to ask questions, make comments or suggestions, or just say hello in the comments below. And join us at Discord for more happy discussions about NestJS. I post there as Y Prospect.

Top comments (23)

Mário Monteiro • Sep 8 '19

Another great post @john
Thanks

Can I use this technique to create a a shared module package.
I have a Lerna monorepo project with two implementations one rest and one graphql, and I really want to create a common shared package, for example to Share the auth module in both rest and graphql packages. Can I extract the auth and users modules (same as nestjs docs) into a package(local ir registery), and reuse it in this two packages, and maybe other new projects?

Or is a better way to share common packages in nestjs to not Dry and duplicate same code?

Thanks

John Biundo • Sep 8 '19

Hi, I think you just posted this question on the discord channel? Here's what I wrote there:

I assume you want to keep the packages private, so I think you have a couple of options. One is to use a private npm registry -- either with a paid account at npmjs.com, or hosting one locally (I have experimented with Verdaccio, and it seems excellent, though I've only just played around with it). Another is to consider a monorepo. I candidly don't have any experience with a monorepo, but a lot of folks on here do actively use one, so I'm sure one or more will chime in if you want to go that route. Good luck!

Hopefully some of the other community members will chime in with thoughts.

Mário Monteiro • Sep 8 '19

Thanks @john

I already use monorepo and Verdaccio.
But the question os not related with publish. I try to ask about extract auth and users modules to a new package to share in my 2 projects. Ex I want to create for ex a package like @acme/nestjs-auth and re,-use it, that why I ask it. Sorry if I cant explain better, you already note that I have some issues with English eheheh

Thanks

John Biundo • Sep 8 '19

No worries @Mário.

So I may not be understanding, but it seems like you're asking about re-using a package in another project. To me, that sounds exactly like what I was addressing. So, you would npm publish @acme/nestjs-auth (if you want it public, that's exactly the recipe outlined in this article; if you want it private, I addressed that above), then, in project A, you'd npm install @acme/nestjs-auth and inside your project a, import { blah } from @acme/nestjs-auth. You could do the same inside project b.

If you just mean sharing a module within a project, that is a separate topic, and is about the Nest module system.

I hope that clarifies somewhat. Ask further if I'm missing the point!

Mário Monteiro • Sep 9 '19 • Edited

Thanks John,
Yes Im asking about sharing a module within a project

@rubin sent me a GitHub link in discord that seems will Help me with issue. Thanks John for your paciente and kind answear :)

Looking forward for next great nestjs posts.

Samuel • Jan 17 '20

Hi Mário, how are you doing?

I need to do exactly what you asked for, how did you dealed with the problem?

Thank you.

Mário Monteiro • Jan 17 '20

Hello Samuel

I don't remember, I must check my project, but the of out friend @rubin put me in the right track.

When I get to home I Will check it....

O see that @rubin repo link os not on this thread, I paste it later

solidarynetwork • Jan 18 '20

Hello Samuel

here are my notes
includes the link to repo that I follow to get it working from our friend @rubiin

I hope this helps :)

NOTES

Tooling

NPM Install Peers

CLI command to install npm peerDependencies. This can be useful when developing modules.

$ sudo npm install -g npm-install-peers
$ npm-install-peers

Publish

# build
$ npm run build
# publish
$ npm publish
# unPublish
# https://docs.npmjs.com/unpublishing-packages-from-the-registry  
# npm unpublish <package-name>@<version>
$ npm unpublish @koakh/nestjs-auth-quick-config@1.2.2

Us in NestJs from file system, ideal for developing

# create symbolic link
$ cd NodeNestJsHyperLedgerConvectorRestStarter/node_modules/@koakh
$ ln -s ../../../../../Node/@NestPackages/@koakh/nestjs-auth-quick-config/

After changes don't forget to npm run build

Use in NestJs lerna project from NPM registry

# install dependency
$ npx lerna add @koakh/nestjs-auth-quick-config --scope @convector-sample/server-graphql
$ npx lerna clean
$ npx lerna bootstrap

Install in App

app.module.ts

ex from graphql project

import { AuthQuickConfigModule } from '@koakh/nestjs-auth-quick-config';

@Module({
  imports: [
    RecipesModule,
    PersonModule,
    ParticipantModule,
    GraphQLModule.forRoot({
      installSubscriptionHandlers: true,
      autoSchemaFile: 'schema.gql',
    }),
    AuthQuickConfigModule.register({
      jwtSecret: 'secretKey',
      jwtExpiresIn: '1h',
      getByUsername: (username: string) => 'admin',
    }),
  ],
})

unicop • Jun 19 '21

@john Biundo

For who prefer to use yarn, it will help if you will add yarn add link:../ for creating the symlink for the auto refresh.
run on the package tsc -w will make it more easy for development to do changes in the package and auto-refresh the server automatically.

Maroje Macola • Jul 13 '21

@unicop thanks for the tip when using yarn :)

In my case, to make it work, I had to add symlink to the package itself, not the root folder in which reside both nestjs app & package (i.e. I executed yarn add link:../nestjs-package-starter)

JORGE GUTIERREZ • May 13 '20 • Edited

Hello first great the article just a question after following the steps install @ nestjs / swagger, but it gives me an error when I build node_modules/@nestjs/common/cache/interceptors/cache.interceptor.d.ts:1:28 - error TS2307: Cannot find module 'rxjs'.

JORGE GUTIERREZ • May 13 '20

ERROR

Alex Martins • Sep 11 '23

Hi guys,
First, congratulations on the excellent post.
What is the best way to create a nest model as an npm package that needs to receive some repository reference to save and get data from the database?

Have I to inject the Prisma reference? - In this case, I think I'll have migrations issues.
Or should I work just with DTO and save on the main App?
or there's a better way?

Thanks

Daniel Stefanelli • Feb 14 '21

Hi @johnbiundo ,

Great post.

I implemented something similar what you explain in this post but I notice that I can't navigate between classes imported from another package in my IDE. Maybe Is there something I'm missing?

Ruslan Gonzalez • Aug 25 '19

Amazing! Outstanding lecture!

John Biundo • Aug 26 '19

Thanks Ruslán González. Glad you found it useful!

Ruslan Gonzalez • Sep 8 '19

I am reading again this post because I love it... !!!

Will Chantry • Apr 5 '20

Great post! Looking forward to mixing this up with a lerna monorepo. I have a specific desire to make a mixed cli and app tool and I want to share my database module/service in a non nestjs and nest environment and this will help a lot getting started. (I want to make the scripts very light and only have them install required dependencies so I don't think the nestjs monorepo atrategy will work for me).

Carlos Caballero • Aug 19 '19

Hey!

Thanks for your post!

Zach • May 1 '21

Thanks for sharing. Mind I ask if there is way to publish single library generated by nest generate library? or What's the best way to sharing modules between different nestjs project?