Publishing a Typescript module to NPM
Tags: npm, typescript
Published: 2017-12-20 20:39:22

---
title: Publishing a Typescript module to NPM
published: true
description: This guide aims at summarizing all aspects of publishing a Typescript module to NPM in a concise step-by-step manner while providing enough context to understand while certain things are done in one or another way. If you have never published a Typescriptript module, this guide will help you.
tags: npm, typescript
---

![https://60devs.com/img/guide-publishing-a-typescript-module-to-npm/poster.png](https://60devs.com/img/guide-publishing-a-typescript-module-to-npm/poster.png)


This guide aims at summarizing all aspects of publishing a Typescript module to NPM in a concise step-by-step manner while providing enough context to understand while certain things are done in one or another way. If you have never published a TypeScript module, this guide will help you.

## Step 1. Create the folder structure

 - create a new folder for your module
 - run `git init` to initialize a git repository
 - in the module folder create the following files or folders:
    - `index.ts`, which is the entry file to your module
    - `package.json`, which contains metadata for your module as required by NPM
    - `tsconfig.json`, which contains configuration for TypeScript compile
    - `.gitignore` to ignore certain files for the git repository
    - (optional) `lib` directory for your internal TypeScript modules
    - (optional) `test` directory for your tests

`index.ts` should export the public interface of your module, for example:

```typescript
export async function myFunction() {
  throw new Error('Not implemented');
}
```

`.gitignore` should contain at least:

```
dist # compiled version of your module will be placed here by typescript compiler
node_modules # local dependencies of your module will be put by npm here
```

## Step 2. Configure Typescript

Typescript configuration is managed using `tsconfig.json` which was created in the previous step. The following is the minimum configuration you can start with:

```
{
  "compilerOptions": {
    "module": "commonjs",
    "target": "es5",
    "outDir": "./dist",
    "moduleResolution": "node",
    "declaration": true
  },
  "include": [
    "test/**/*.ts",
    "lib/**/*.ts",
    "index.ts"
  ]
}
```

Compiler options tell the TypeScript compiler that it will be working with node modules and that it should compile your Typescript code to EcmaScript 5 and generate type declaration files. The `include` attribute defines that only files from the `test` and `lib` folders and `index.ts` will be compiled by Typescript. The compiled code will be placed into the dist folder. Compiling to ES5 allows your module to be used with a broader range of NodeJS versions. TypeScript users will be able to use type information corresponding to the compiled code thanks to the generated type definition files.

## Step 3. Configure NPM

`package.json` is responsible for defining what NPM will publish to the global registry. Additionally, it allows defining scripts to make sure the latest version of your code is properly compiled before publishing and only the compiled version is published to NPM. The minimal `package.json` to start with is:

```js
{
  "name": "$TODO-module-name",
  "version": "0.0.1",
  "description": "Describe your project TODO",
  "main": "dist/index",
  "typings": "dist/index",
  "scripts": {
    "prepublishOnly": "npm run compile",
    "compile": "npm run clean && tsc -p .",
    "watch": "tsc -w -p .",
    "clean": "rm -rf dist"
  },
  "bugs": {
    "url": "http://github.com/$TODO-github-username/$TODO-module-name/issues"
  },
  "repository": {
    "type": "git",
    "url": "http://github.com/$TODO-github-username/$TODO-module-name.git"
  },
  "keywords": [
    "your keywords TODO"
  ],
  "author": "your name <your.contact.email@service.com> TODO",
  "license": "MIT",
  "devDependencies": {
    "@types/node": "^8.0.0",
    "typescript": "^2.6.1"
  },
  "files": [
    "dist/index.js",
    "dist/index.d.ts",
    "dist/lib"
  ]
}
```

Important attributes are `main` and `typings` which allow consuming your module from both JavaScript and TypeScript. Note that these attributes point to the `dist` directory. Only `dist` directory will be published to NPM as defined by the `files` attribute. If you want to publish more files you will need to list them in the `files` list.

Another important part is the `prepublishOnly` script. This script invoked every time you run `npm publish` and compiles your module. For convenient development, you can use `npm run watch` to automatically re-compile as soon as you make changes to your .ts files.

Make sure your adjust all attributes marked with TODO before publishing. Also run `npm install` to install Typescript and node types as your development dependencies. NPM scripts will use the local version so you don't need to install Typescript globally.

## Step 4. Publishing

Run npm publish to publish your changes to NPM:

```
npm publish
```

Don't forget to commit and push the final version to you git repository.

## Further reading

- how `.gitignore` works https://git-scm.com/docs/gitignore
- `tsconfig.json` reference https://www.typescriptlang.org/docs/handbook/tsconfig-json.html
- `package.json` reference https://docs.npmjs.com/files/package.json
- `npm publish` docs https://docs.npmjs.com/cli/publish

Was this guide helpful? Tell me what you think.