Writing npm modules in TypeScript

Here is a sample Node module written in TypeScript : https://github.com/basarat/ts-npm-module

Here is a sample TypeScript project that uses this sample module https://github.com/basarat/ts-npm-module-consume

Basically you need to :

• compile with commonjs and declaration:true
• generate a .d.ts file

And then

• Have your ide read the generated .d.ts.

Atom-TypeScript just provides a nice workflow around this : https://github.com/TypeStrong/atom-typescript#packagejson-support

With TypeScript 4.x, TypeScript 3.x or TypeScript 2.x, the following steps describe what you have to do to create a library (npm package) with TypeScript:

• Create your project as you normally would (with tests and everything)
• Add declaration: true to tsconfig.json to generate typings.
• Export the API through an index.ts
• In the package.json, point to your generated typings. For example if your outDir is dist, then add "types": "dist/index.d.ts" to your package json.
• In the package.json, point to your main entry file. For example if your outDir is dist and the main entry file is index.js, then add "main": "dist/index.js" to your package.json.
• In the package.json, whitelist the files you'd like to ship to npm: files: ["/dist"]. An alternative approach is blacklisting with .npmignore, but it's harder to keep up to date.
• Publish to npm with npm publish. Use semver specifications for updates (patch / bug fix npm version patch, non-breaking additions npm version minor, breaking api changes npm version major)

Since it got me a while to sift through all the outdated resources on this topic on the internet (like the one on this page...) I decided to wrap it up in how-to-write-a-typescript-library with an up-to-date working minimal example.

This is a more recent answer using TypeScript 1.8.10:

My project structure is:

||--- src|--- test|--- dist     <= My gulp file compiles and places the js, sourcemaps and .d.ts files here|      |--- src|      |--- test|--- typings.gitignore.npmignoregulpfile.jspackage.jsonREADME.mdtsconfig.jsontslint.jsontypings.json

I added the following in .npmignore to avoid including extraneous files and keep the bare minimum to have the package imported and working:

node_modules/*.log*.tgzsrc/test/gulpfile.jstsconfig.jsontslint.jsontypings.jsontypingsdist/test

My .gitignore has:

typings# ignore .js.map files*.js.map*.jsdist

My package.json has:

"main": "dist/src/index.js","typings":  "dist/src/index.d.ts",

Now I run:npm pack

The resultant file (when unzipped) has the following structure:

||--- dist|       |--- src|              ||              index.js|              index.js.map|              index.d.ts|package.jsonREADME.md

Now I go to the project where I want to use this as a library and type:npm install ./project-1.0.0.tgz

It successfully installs.

Now I create a file index.ts in my project where I just installed the npmimport Project = require("project");

Typing Project. gives me the Intellisense options which was the point of this whole exercise.

Hope this helps someone else in using their TypeScript npm projects as internal libraries in their bigger projects.

PS: I believe that this approach of compiling projects to npm modules which can be used in other projects is reminiscent of the .dll in the .NET world. I could well imagine projects being organised in a Solution in VS Code where each project produces a an npm package which can then be used in another project in the solution as a dependency.

Since it took a fair amount of time for me to figure this out, I have posted it in case someone is stuck here.

I also posted it for a closed bug at:https://github.com/npm/npm/issues/11546

This example has been uploaded to Github: vchatterji/tsc-seed