What to put in package.json types field for typescript based libs

Question

I'm a bit confused as to how best develop multiple typescript modules in parallel with code navigation and still publishing the right way. So what should I really put in package.json "types" field?

According to: Typescriptlang.org/publishing.html

I should put a reference to my generated index.d.ts like so:

{     "name": "awesome",     "author": "Vandelay Industries",     "version": "1.0.0",     "main": "./lib/main.js",     "types": "./lib/main.d.ts" } 

If I then develop a module in parallel that depends on this one with npm link, code navigation in for example vscode makes me just jump into this definitions file. Which is not what I want.

I want to go into the source file to be able to edit in the dep in parallel. No tsconfig setting with sourcemaps, inlined or not have helped in this regard. I might be missing something here. The only way I've managed my work flow to work decently is to actually point to the source main.ts file instead:

{     "name": "awesome",     "author": "Vandelay Industries",     "version": "1.0.0",     "main": "./lib/main.js",     "types": "./src/main.ts" } 

That however would make thing break when published right ?

At least if I put src under .npmignore. I'm failing to understand the best way to have a nice workflow with multiple typescript modules.

I mean, I wouldn't want to have to mangle package.json as part of release process…?

Answer 1

TypeScript Project References

As far as I can tell, TypeScript Project References will fill your requirements:

• VS Code navigation goes to the *.ts source file not to the *.d.ts file.
• The package.json types value references the *.d.ts file.

That provides developer tooling without changing how/what you publish.

Demo

I created a simple demo project in GitHub. Here are the high-points of how to set up project references with code navigation.

package01

The tsconfig.json allows another TypeScript project to reference it (composite) and for code navigation to work (declarationMap). In the package.json, the NPM scope (@shaunluttin) is not entirely necessary; I included it to avoid naming collisions.

tsconfig.json

{   "compilerOptions": {     "target": "es5",     "composite": true,     "declarationMap": true   } } 

package.json

{   "name": "@shaunluttin/package01",   "version": "1.0.0",   "main": "index.js",   "types": "index.d.ts" } 

package02

The tsconfig.json references package01. That's what sets up the tooling. The package.json depends on package01 in the same way it normally would.

tsconfig.json

{   "compilerOptions": {     "target": "es5"   },   "references": [     {       "path": "../package01"     }   ] } 

package.json

{   "name": "@shaunluttin/package02",   "version": "1.0.0",   "main": "index.js",   "types": "index.d.ts",   "dependencies": {     "@shaunluttin/package01": "1.0.0"   } } 

NPM Link

For local development, the two packages are connected with npm link.

cd package01 npm link  cd ../package01 npm link @shaunluttin/package01 

Final Thoughts

The documentation mentions a handful of caveats that are too involved to list in this answer.