Documentation unclear for "Help! My Types Are Missing!"

[ptrk8]

I'm currently going through the documentation and I'm getting a little confused by the "Help! My Types Are Missing!" section as a Typescript newbie.

Everything makes perfect sense until I hit the following section.

For module definitions, you can use paths:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "custom-module-type": ["types/custom-module-type"]
    }
  }
}

What should be the path's name if my module's name is "special-module"? From the above section, I'm led to believe that the path name should be "special-module-type" but that doesn't seem right... Also, shouldn't the path value begin with "typings/...." given our example project structure (shown below)?

Example project structure:

<project_root>/
-- tsconfig.json
-- typings/
  -- <module_name>/
    -- index.d.ts

Some clarification and explanation around this would be appreciated.

[cspotcode]

ts-node --files does not change TypeScript's behavior at all, so everything you need to know about configuring TypeScript, including "baseUrl" and "paths", you can learn from TypeScript's official documentation, the TypeScript Community Discord, or any other online resource.

ts-node without the --files flag changes only one thing: it overrides your tsconfig.json "files" and "include" arrays. If you do ts-node ./index.ts, then it overrides your tsconfig like this:

  "files": ["index.ts"], // only includes the entry-point
  "include": [], // is empty
  // all the rest of your tsconfig is the same

Remember that "paths" affects the way TypeScript resolves types, but it does not affect the way node resolves files when it loads them.
So if require("foo") does not work in node, then configure "paths" will not help. It will only fix TypeScript errors.

With that explanation out of the way, check out the official TypeScript documentation for paths:
https://www.typescriptlang.org/docs/handbook/module-resolution.html#path-mapping

[ptrk8]

@cspotcode thanks so much for the explanation. I don't think I explained my misunderstanding as well as I could so I will try again.

In order to make sure ts-node can detect my types, I followed your instructions step by step.

This involved adding the following to my tsconfig.json file:

{
  "compilerOptions": {
    "typeRoots" : ["./node_modules/@types", "./typings"]
  }
}

Having the below project structure:

<project_root>/
-- tsconfig.json
-- typings/
  -- <module_name>/
    -- index.d.ts

And having the following module declaration file:

declare module '<module_name>' {
    // module definitions go here
}

These steps alone were enough to get ts-node to find my types and run smoothly.

However, the documentation contains an additional step (below) and I'm not sure what its purpose is for.

For module definitions, you can use paths:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "custom-module-type": ["types/custom-module-type"]
    }
  }
}

Just to make things easier for you, my first question is - what do you mean by "module definitions"? Do you just mean "module declaration files" like the one below?

declare module '<module_name>' {
    // module definitions go here
}

[cspotcode]

Yes, I believe that's what it means: declarations that describe the shape of a module. In particular, it would be used to describe the types of something installed via npm into your node_modules, but which does not bundle its own TypeScript declarations.

You're always dealing with 2x problems:
a) node must be able to load the module so it can execute
b) TypeScript must be able to find type declarations for the module

Both problems start with import CMT from "custom-module-type";

For a), node does not understand your tsconfig "paths" configuration*, so it will look in node_modules just like it always does, and it will find executable .js

For b), if the module had bundled its own type declarations, TypeScript would be looking in the same place as a). Unfortunately this module did not, so we are instead telling TypeScript that "custom=module-type" can be resolved as <baseUrl>/types/custom-module-type. TypeScript will look here to find type declarations.

node and TypeScript are looking in 2 different places. In this situation, that's what we want, because node needs executable JS, whereas TypeScript needs type declarations which were not included with the library.

If you want tons of insight into what TypeScript is doing when it resolves files, try tsc --traceResolution. It will log very detailed information about how TypeScript is locating every module when it does type-checking.

• unless you use something like tsconfig-paths which hooks into node's resolver to change its behavior

[ptrk8]

@cspotcode thank you again for putting the time in to write such a detailed response.

You mention that the following paths configuration is for us to resolve problem (b).

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "custom-module-type": ["types/custom-module-type"]
    }
  }
}

However, isn't the following (without the above) enough to resolve problem (b) and ensure that Typescript can find our custom type definitions?

{
  "compilerOptions": {
    "typeRoots" : ["./node_modules/@types", "./typings"]
  }
}

[cspotcode]

I'm not sure, but if it's working for you, then you can certainly keep doing that. The official documentation might offer some insight: https://www.typescriptlang.org/tsconfig#typeRoots

There may be differences between typeRoots and paths. For example, paths are used to resolve imports, whereas I believe typeRoots and types are eagerly loaded by the compiler before any import resolutions are attempted.

I recommend asking any follow-up questions on the TypeScript Community Discord. I have limited time to answer questions, so I tend to focus on questions that are specific to ts-node. This question is about TypeScript in general, so you will get better answers from the experts on Discord.

I don't want to discourage you from asking questions. Rather, I hope to point you to the best resources to get the answers you need.

[nikksan]

The example is super confusing, why would you rename typings to types for the final step and rename the dynamic <module_name> for custom-module-type. Makes you wonder if it's not some deep-level magic happening there.

Eventually ended with this, which worked for me.

"baseUrl": ".",
"paths": {
   "<module_name>": ["./typings/module_name"]
}

[cspotcode]

This bit of the docs is pretty ancient; we'd welcome a PR improving this page.