TypeScript: TypeScript won't import JSDoc types from .js file in node_modules

Please, reopen the issue. Thumbs up this message if you want it to be reopened. Thanks.

For anyone else who has found this issue after it closed, hopefully this helps:

Same Problem

I have the same problem as @rbiggs. I’ve created a module called @imin/shared-data-types. This module uses almost entirely JSDoc to define its TypeScript types. Within the module, all the files are able to use the types correctly. VSCode recognises if there’s a type error and so does tsc. That’s great ✔️

However, as soon as I’m importing this code to another project, the types disappear. VSCode and tsc both recognise the types as any ❌

Hope?

@phaux 's solution (https://github.com/microsoft/TypeScript/issues/33136#issuecomment-528657072) was very helpful to me. I set my tsconfig.json to:

{
  "compilerOptions": {
    "noEmit": true,
    "allowJs": true,
    "checkJs": true,
    "downlevelIteration": true,
    "maxNodeModuleJsDepth": 1
  },
  "include": [...]
}

And VSCode and tsc were finally able to recognise the types!

Before:

After:

Wonderful ✔️

The only problem is that when I ran tsc I was shown a LOT of new errors.

This is because now every single import is being type checked. Many JavaScript libraries come a-cropper when examined under TypeScript’s inscrutable gaze. Fair enough! But I don’t have time to fix all these issues with external libraries. ❌

What I want is for TypeScript to just check the modules that I made that I know have been typed properly using JSDoc. How can I do that?

The solution

Just add the modules to tsconfig.json’s include list. e.g.:

{
  "compilerOptions": {
    "noEmit": true,
    "allowJs": true,
    "checkJs": true,
    "downlevelIteration": true
  },
  "include": [
    "src/**/*.js",
    "node_modules/@imin/shared-data-types/**/*.js",
  ]
}

This works! ✔️ ✔️ ✔️

Typescript version: 3.6.2

This issue should be re-opened given that TypeScript does not resolve JS files with JSDoc from node_modules.

All proposed solutions in this issue are workarounds. Using the TypeScript compiler to emit declaration files is redundant, given that the JS files contain the declaration already. Moreover, I experienced:

• jump to source requires .d.ts.map files (bloats the package)
• the declarations don’t contain all comments from the JS file

All of those issues would exist if declaration files wouldn’t be required for JSDoc JS files.

There’s an option in TS compilerOptions called maxNodeModuleJsDepth and it’s set to some low value by default. Try setting that to a higher value.

I think TypeScript should simply support main and types fields in package.json being set to the same file if the file is JS with JSDoc:

{
  "main": "./main.js",
  "types": "./main.js"
}

Last time I checked it didn’t work. Project which imports such module doesn’t get the types.

Yup. You do need the latest TypeScript installed somewhere, either locally or globally. Latest version is 3.7.5. Set up your tsconfig.json file. Then setup an NPM script to run TypeScript to check you files. With this above options in the tsconfig file it will also create the d.ts files for your JavaScript. That means you don’t have to worry about TypeScript importing you JSDoc types properly. It will always find and parse d.ts files. Here’s a link to a tsconfig file for one of my Gitub repos: https://github.com/composi/core/blob/master/tsconfig.json

Actually, @lukehesluke, that’s what I wound up doing as well, using include to tell TypeScript to include my JavaScript modules with JSDoc comments. One thing I also had to do what make sure the main index file imported any types being used in sub-files so that when TypeScript hit the index.js file for the module, it also found the path to the types.

However, now I no longer bother with any of that because TypeScript now supports creating d.ts files from JavaScript files with JSDoc comments. So when I run tsc, it automatically generates .d.ts files for everything. This solves the problems that TypeScript still has with following the paths of types defined with JSDoc in complex JavaScript modules. Well, it doesn’t fix the issue. It gets around the problem because by default TypeScript always looks for d.ts files. Since my modules are written in JavaScript with JSDoc comments, there weren’t any. Now I can let TypeScript create them for me while its also type checking my JavaScript.

You just need to update your projects tsconfig.json file for this to work. Here’s what I’m currently using for compiler options:

{
  "compilerOptions": {
    "target": "es6",
    "allowJs": true,
    "checkJs": true,
    "moduleResolution": "node",
    "alwaysStrict": true,
    "strictNullChecks": false,
    "emitDeclarationOnly": true,
    "declaration": true,
    "outDir": "types",
    "removeComments": false
  }
}

Note that I tell TypeScript to output the d.ts files into a folder called types. Then in my package.json file I declare that as the location for the project’s types:

"typings": "types"

With these updates to my JavaScript projects, TypeScript will find the d.ts files for my JavaScript projects. And these are created by TypeScript based on my JSDoc comments. Win win.

I guess I should mention how I check my types and produce the d.ts files. Because I have all the instructions for TypeScript in the project’s tsconfig.json file, all I have to do is run a simple npm script which I define in my package.json:

"scripts": {
  "checkjs": "tsc"
}

Then in the terminal I just run npm run tsc. This runs a type check on the JavaScript using my JSDoc comments and then produces d.ts files as well.

Last time I checked it didn’t work. Project which imports such module doesn’t get the types.

Fast forward to 2024 and it still doesn’t work and issue is still closed… nothing is fixed here, just hacky and annoying workarounds in sight.

I tried using a d.ts like you suggested to point TypeScript toward the type definitions, but that did not work. Instead, this is what works for me. I have the following expected exports in the module’s index.js file, followed by @typedef pointing to the type definitions in JSDoc that I want TypeScript to be aware of globally:

export { h } from './h'
export { render } from './render'
export { run } from './runtime'
export { union } from './union'
export { batchEffects } from './effects'
export { Fragment } from './fragment'

/**
 * Make types available to programs that use them.
 */
/**
 * Type of virutal node used to define elements to create.
 * @typedef { import('./vnode').VNode } VNode
 */
/**
 * A program which is executed by the `run` function.
 * @typedef { import('./runtime').Program } Program
 */
/**
 * Message dispatched by the `send` function to the program's `update` method.
 * @typedef { import('./runtime').Message } Message
 */
/**
 * Type of state, which can be of any type.
 * @typedef { import('./runtime').State } State
 */
/**
 * Function for sending messages to the program's `update` method.
 * @typedef { import('./runtime').Send } Send
 */

This allows the user to import h, render, etc. and get the correct types in Visual Studio Code.

I have found a solution that seem to work well: move index.js to src/ folder, and create index.d.ts at root that point to it:

// src/index.js
export function delay() {}

// index.d.ts
import { delay } from './src'
export { delay }