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.
Top comments (0)