Compile to .d.ts on publish to npm

[voxpelli]

JSDoc types only gets validated in the very project one is in. Any JSDoc types in node_modules are ignored by default, only .d.ts files gets imported by TypeScript by default.

While one can make TypeScript pick up JSDoc types in node_modules by setting "maxNodeModuleJsDepth" to a value more than 0, that is both very slow + tends give false errors by picking up JSDoc comments that have been added in code for pure documentation purposes and which haven't been validated in any form.

The better way is to always publish .d.ts with ones project when one publishes it to npm.

How?

The way I have typically done it can be seen in eg async-htm-to-string and micropub-express:

1. Add a declaration.tsconfig.json extending your tsconfig.json

   {
     "extends": "./tsconfig",
     "exclude": [
       "test/**/*.js"
     ],
     "compilerOptions": {
       "declaration": true,
       "noEmit": false,
       "emitDeclarationOnly": true
     }
   }

2. Ignore the generated .d.ts in your .gitignore

   *.d.ts

3. Add a build step to your package.json "scripts":

   From micropub-express build-step using npm-run-all:

   "build:0": "run-s clean",
   "build:1-declaration": "tsc -p declaration.tsconfig.json",
   "build:2-add-ignores": "ts-ignore-import '**/*.d.ts'",
   "build": "run-s build:*",

   And the clean step:

    "clean:declarations": "rm -rf $(find . -maxdepth 2 -type f -name '*.d.ts')",
    "clean": "run-p clean:*",

4. Add a prepublishOnly step to your package.json "scripts":

   "prepublishOnly": "run-s build",

   This will generate the types when you publish to npm

5. Maybe add a "types" to your package.json:

   "types": "main.d.ts", where main should be the same as the name on your "main" field. If not set it will default to index.d.ts, but maybe rather be explicit than implicit?

6. Optionally add a manually crafted .d.ts, eg. advanced-types.d.ts for complex types:

   • Change clean:declarations to rm -rf $(find . -maxdepth 2 -type f -name '*.d.ts' ! -name 'advanced-types.d.ts')
   • Add !/advanced-types.d.ts on a line after *.d.ts in your .gitignore

7. npm publish (or similar if you prefer, maybe np?)

[Raynos]

Opinions differe about whether npm package authors should put a *.d.ts in the npm package. Always is too strong of a word.

There are pros & cons to shipping a JavaScript npm package with a *.d.ts file.

Pros

• Users who want a *.d.ts file get it without having to install from @types/express etc.

Cons

• The existance of a *.d.ts file breaks go to definition for JavaScript projects, this is a long stanging TypeScript bug that's not been fixed for years. As a software user I'd really prefer to be able to go to the source code definition over going to a *.d.ts file, especially if the information already exists as JSDoc comments
• The information is duplicated between JSDoc comments and *.d.ts.
• The user can already import and access the type information by adding the dependency to their "files" and using --maxNodeModuleJsDepth 0 as their tsc command.

As a publisher of JavaScript code to npm I'd rather not break the user experience for the 80% of JS users that dont care about typescript/jsdoc, which is what the existance of *.d.ts does. That being said, if TypeScript ever fixes this bug then it doesn't hurt to ship a *.d.ts.

For the 20% of users who are using TypeScript / JSDoc, they can already whitelist the JSDoc source code in "files". This integrates the dependency natively with TypeScript and it means that go to definition works as expected, text editor understands JSDoc and the typescript type checker understands the types of the dependency.

Maybe the real answer is to publish the artifact twice to npm, once with and once without the *.d.ts file.

[voxpelli]

This is what’s so great about writing this down 🙌

I don’t agree that one should avoid publishing .d.ts, but you have good points indeed, so I’ll happily disagree with you on conclusion but cheer you on in your highlights!

[voxpelli]

I forgot to mention what ts-ignore-import does. It's a tool that by default adds a // @ts-ignore to all dependencies imported into ones generated .d.ts.

Why?

If one has lots of modules that interoperate with one another or if one relies on big complex types like eg @types/express, then it might be undesirable to include those types as dependencies of ones module. To ensure that the types will still work, despite the possibly missing type, one can add a // @ts-ignore to the import. That will make the import resolve to any instead, so everything will work, one just wont get any type info for that specific module. Then if the project that includes ones module do add the types as a direct dependency, or if it for any other reason becomes available, then it will automatically become available and typed.

I created that module when working at @Sydsvenskan as we for interoperability reasons referenced types from quite a few of our modules and if we had needed to add all those modules as dependencies, then in the end all modules would almost depend on all modules when it was actually only the types that were referenced. We also got some issues with @type/express some times getting partially updated in our dependency tree and the multiple copies of @type/express not being compatible with itself. Having all modules use an optional top @types/express instead removed that issue.

[Gozala]

Hi All,

I have been generating typedefs on release and publishing them with a package. As of recently go to definitions are fixed by typedef maps and typeVersions in package.json can be used to map all source files to corresponding .d.ts file generated from them.

In my experience that provides best experience to lib users as they get all the typings in vscode and/or TS projects without having to do any configuration. And jump to definition also take then to the source js instead of .d.ts files

Here’s one example of such setup https://github.com/multiformats/js-multiformats/blob/master/package.json

[voxpelli]

This is awesome @Gozala, I don't know how I have missed the declarationMap: true. I added it now to one of my projects and tested it and go to definition works as it should now: voxpelli/async-htm-to-string@5a78478

I didn't need to do anything with typeVersions to get it to work, which is good as it should really only be necessary for types that have dependencies on certain TypeScript versions, like my recent addition to type-fest: https://github.com/sindresorhus/type-fest/blob/d232c19cd5e06a70216c562cae09c6391da55c38/package.json#L43-L49

Again, thanks for sharing!

[Raynos]

I tried 'multiformats/cid' and go to definition does not go to source code only the *.d.ts.

I tried async-htm-to-string and go to definition does go to the source code but the the line number it goes to is confusing, it looks like the declarationMap gets confused and sends me to the wrong line.

In both modules I tried the behavior when i delete the *.d.ts , in async-htm-to-string it behaves better and goes to the definition like i would expect with more accurate line numbers.

In multiformats it does nothing. My suspicision here is that TypeScript does not understand a packages that has no index.js, no "main" field and only an exports field in the package.json ( microsoft/TypeScript#33079 ).

That being said I did try to use the multiformats project with require() instead of ESM import, so maybe ESM import "works"

[voxpelli]

@Raynos For me, using VS Code 1.52.0, it jumps to the correct definition for me, though it jumps to the start of the JSDoc-comment rather than the start of the code, but that's okay with me, in a way that's actually more correct as thatäs where the definition starts.

[Raynos]

I saw that behavior as well when using go to definition on html or renderToString, it jumped to the block comment above the function source code instead of jumping to the function declaration statement.

The behavior that was confusing for me was go to definition on require('async-htm-to-string') which jumped to the JSDoc definition of RenderableElementFunction instead of going to the file or the module.exports = assignment statement.

The behavior without the *.d.ts was less confusing to me. Since it jumps to the module.exports statement and it jumps to the start of the file when hitting go to definition, it seemed to be more internally consistent.

[DominusKelvin]

I think I will give this a try. Thanks 😊

[Gozala]

I didn't need to do anything with typeVersions to get it to work, which is good as it should really only be necessary for types that have dependencies on certain TypeScript versions, like my recent addition to type-fest: https://github.com/sindresorhus/type-fest/blob/d232c19cd5e06a70216c562cae09c6391da55c38/package.json#L43-L49

@voxpelli typeVersions are used to support more than one .d.ts file, which sadly types field in package.json does not. (unless there are some tricks I’m unaware of). E.g import { Foo } from ‘foo/src/bar.js’. does not work unless .d.ts file has bunch of declare module things, which is not what tsc produces.

[voxpelli]

Right, I rarely have modules where I officially support anyone requiring a sub-file, so haven't run into that

[Gozala]

I tried 'multiformats/cid' and go to definition does not go to source code only the *.d.ts.

I’ll have to go check what’s up with that, that package was probably not the best example as it also tries to do both ESM & cjs and I suspect that creates problems.

[voxpelli]

Same with async-htm-to-string, it's my only module so far that tries to do both ESM & cjs, but there may of course be differences in how we have implemented it, wasn't extremely straightforward.

[hugomrdias]

you can try https://github.com/multiformats/js-multihash go to definition should work as expected

[voxpelli]

I see in multiformats/js-multihash/tsconfig.json that it uses ipfs/aegir/src/config/tsconfig.aegir.json

Any particular takeaways from that configuration and that setup that you like @hugomrdias? Both in this context and in #2

[hugomrdias]

Nothing super specific, that set of rules seems to be a good starting point to start typing a large commonjs multi repo/org with JSDoc. The only thing special there is the emit options, those are meant to work together with our tooling here and avoid multiple tsconfig files in the repos.

We are now updating the config to be more strict with this PR ipfs/aegir#697

We also keep a md file with some docs to help maintainers type each repo.

Integration with typedoc is also there but still a bit experimental and hacky because typedoc doesnt handle commonjs very well yet.

[Raynos]

I can confirm that multihashes works with go to definition. It's commonJS and works with a javascript file using require.

[voxpelli]

It works better than with async-html-to-string? Would need to compare source map generation then :/

[Raynos]

They work similar, it's multiformats that did not work with commonJS / require because of ESM stuff.

Both multihashes & async-html-to-string have the behavior where it jumps to the first block comment instead of the start of the file, so it looks like go to definition is jumping randomly to 1/3rd of the file but thats just "source maps for d.ts".

I'd be a lot happier if typescript updated the source map generation to jump to the module.exports = expression instead of the first JSDoc comment in the file.

[voxpelli]

@Raynos We should look into opening an issue about it in the TypeScript repo