BY ON Apr 22, 2018

How to publish your own typescript libraries to npm

Let's publish our first npm public package, including the required typescript definition files.

As a developer you should always keep looking for different ways to improve your productivity and the quality of your work, so reusing your code it’s a common practice that could help you to achieve partially that goal. Recently I’ve faced a requirement were I needed to replicate almost the same functionality, from a web application made on Angular into an offline desktop application, that’s why I came across with the opportunity to reuse some objects. I won’t enter on details about all the benefits of this approach, but I have to say that my goal on this was trying to keep the maintenance for both applications as simple as possible.

This post assumes that you are familiar with NPM, the Javascript package manager and its command line. If don’t you can read more about it here: What is npm?

On this post I will publish a library that contains a single class only (could be your models objects for example), this is the most basic case in my scenario.

Set up your NPM account

Normally when you’re just installing packages from the npm’s registry there’s no need of this, but if you’re aiming to publish packages you’ll need to register and set up an account on the npm’s site.

If you want to publish private packages you’ll need to pay a fee per month/user, otherwise you will be able to publish public packages only (open source). This will give you a scope which your packages are published under of.

Once you’ve set up your account you can execute npm login command to sign in with your credentials and get ready to publish.

Preparing your library to publish

I’ve started the project from scratch, but If you have it already, just take in consideration the key settings that you have to set up in the following files to be able to publish. Another important thing to note is that I’m including my Typescript definition file in the same bundle as the package. An alternative approach is to publish those definitions under the @types organization on npm, but since that is an additional step, you have to keep it synchronized with your source, that could be a downside.


Let’s review the required settings here:

  • name - Your library’s name. It’s required to be unique and can be optionally prefixed by a scope, e.g. @myscope/mylibrary
  • version - Should be updated every time you want to publish a change. It has to be a valid semver string. You can read more about Semantic Versioning here.
  • main - The primary entry point to our library.
  • types - Your bundled declaration file.

Keep in count that you have to specify here the dependencies of your library if any, in the dependencies section as usual. Also you could see that I have some devDependencies declared since those are required to run the compile script there.


Our Typescript compiler options:

  • module - Module code generation. CommonJS since I’m targeting ES5 in this example.
  • target - ECMAScript target version.
  • rootDir - Root directory of our typescript source files.
  • outDir - Output directory where our transpiled code and definitions will reside.
  • declaration - When true is specified, it will generate the corresponding definition file .d.ts.

You can read more about the available Typescript compiler options at its official docs

Source files

I have a folder called src that holds all the source files, you can call it as you prefer and could organize your objects as you need within. The objects you want to expose need to be declared by the file index.ts (your primary entry point), so they’ll be available for the consumers of your library.

Here I’m only exposing a single class called Person:

And my index.ts looks like this:


We don’t want to include our source files into the published version of our library, so I’ve added the src folder there to be ignored:


To generate your dist folder contents just run npm run compile. I’ve added that custom task trying to keep the illustration simple, but you should know that npm offers a set of lifecycle scripts that are called automatically depending on the command you’re executing on over your package. For example we could set a script called prepublish that will just call our compile script, that way our source gets compiled everytime you run the publish command.


Finally we’re ready to publish our library, to accomplish that you just need to run npm publish from your library’s root folder, if everything was successful you’ll see something like this at the end:

  • typescript-library-to-publish@1.0.0

Basically contains the name of your library and the version published. Now to continue publishing updates, remember that you need to update the version accordingly to your changes based on the semver standard, so the consumers of your library can be aware if those changes could break their applications or not.

Hope this post can be helpful for you. I expect to complement it with another post illustrating a more complex example since I need to publish some Angular services for my current project.