Publishing a Typescript module to NPM

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:

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:

{
  "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.