typeRoots is not finding custom declaration file

[lwilli]

TypeScript Version:
Version 2.6.2

Search Terms:
declaration file for module exporting function, external module, npm package, third-party module

Code
src/testFile.ts:

import getFieldList = require('graphql-list-fields');

src/@types/graphql-list-fields/index.d.ts:

// Doing just this below (as suggested by the Typescript Handbook does not work 
// and results in the tsc error under **Actual behavior** below
import { GraphQLResolveInfo } from 'graphql';
declare function getFieldList(info: GraphQLResolveInfo): string[];
export = getFieldList;

// The code below is what actually works instead of the above
/*
declare module 'graphql-list-fields' {
    import { GraphQLResolveInfo } from 'graphql';
    function getFieldList(info: GraphQLResolveInfo): string[];
    export = getFieldList;
}
*/

Expected behavior:
Compiling without errors.

Actual behavior:
Error when running tsc:

src/testFile.ts(1,31): error TS7016: Could not find a declaration file for module 'graphql-list-fields'. '/node_modules/graphql-list-fields/index.js' implicitly has an 'any' type.
Try `npm install @types/graphql-list-fields` if it exists or add a new declaration (.d.ts) file containing `declare module 'graphql-list-fields';`

graphql-list-fields is an NPM package that I'm trying to use, which currently has no published type declarations.

After reading through the Typescript Handbook's section on declaration files, I found that I am trying to write a declaration file for a modular library and should use the module-function.d.ts declaration file template. This is how I came up with the code in index.d.ts above, but the compiler still complains about not having the declaration file for the module 'graphql-list-fields'. After trial and error, we found that adding declare module 'graphql-list-fields' around everything worked without compiler errors.

We tried setting "typeRoots": ["./node_modules/@types", "./src/@types"] in tsconfig.json, as mentioned in the tsconfig docs but that still did not work without declare module 'graphql-list-fields'. This seems to be an issue because tsc is not finding the type declaration in the directories specified in typeRoots.

Related Issues:
3019, 8335

[mhegazy]

"typeRoots" is meant for global code. i.e. something that is declarated in the global namespace, and you want to include it. this is why your declare module 'graphql-list-fields' {.. works, since it just declares a module with that name in the global namespace.

For modules, they have thier own scope, all you need is path mappig..

somethign like:

{
    "compilerOptions": {
        "target": "es5",
        "baseUrl": "./",
        "paths": {
            "*" : ["src/@t`ypes/*"]
        }
    }
}`

[lwilli]

Thanks for clearing that up @mhegazy. I think it would be helpful if this was explained more in the TypeScript docs, possibly under the declaration files section.

[mhegazy]

TypeRoots is really a support we have added for back compat with typings and to allow migration, so we tried to keep it out of the docs as much as possible to avoid confusion.

Not sure if this fits in the declaration file section. we do have a note about it in https://www.typescriptlang.org/docs/handbook/module-resolution.html#path-mapping

I can add a note in the declaration file section about module resolution section as a whole.

give that section a read and let us know if you still find docs in it lacking

[lwilli]

Oh I see. Yeah, that is the page that I needed to begin with. I think it would be nice to have at least a brief mention of path mapping and maybe a link to that doc somewhere under https://www.typescriptlang.org/docs/handbook/declaration-files/introduction.html.

[typescript-bot]

Automatically closing this issue for housekeeping purposes. The issue labels indicate that it is unactionable at the moment or has already been addressed.

[lwilli]

I still think it would be helpful to have the docs updated as stated in my previous comment @typescript-bot

[ericdrobinson]

TypeRoots is really a support we have added for back compat with typings and to allow migration, so we tried to keep it out of the docs as much as possible to avoid confusion.

@mhegazy Having a supported feature with little-to-no documentation is what drives confusion. Please properly document features like this but be liberal with your warning language. For example:

Note: This feature is provided for backwards compatibility with typings to support migration. See the release notes [here] for more information.

This would be vastly preferable to having to scan GitHub Issues, StackExchange, etc. for information.

[kaiwa]

Thx a fucking ton @mhegazy ! 🎉 That path entry for @types was finally the missing piece which made my non-standard project setup work. I spent days on this.