Adding custom type definitions for an untyped npm module in TypeScript 2

Question

Adding custom type definitions for an untyped npm module in TypeScript 2

Despite attempting various methods recommended in other sources, I am struggling to configure a TypeScript project that utilizes an untyped NPM module. Below is a simplified example along with the steps I have taken.

Let's imagine, for this demonstration, that lodash lacks predefined type definitions. Consequently, we will disregard the @types/lodash package and endeavor to manually introduce its typings file lodash.d.ts into our project.

Directory structure

node_modules
- lodash
src
- foo.ts
typings
- custom
  - lodash.d.ts
- global
- index.d.ts
package.json
tsconfig.json
typings.json

Now, let's delve into the files.

File foo.ts

///<reference path="../typings/custom/lodash.d.ts" />
import * as lodash from 'lodash';

console.log('Weeee');

The content of File lodash.d.ts has been directly copied from the original @types/lodash package.

File index.d.ts

/// <reference path="custom/lodash.d.ts" />
/// <reference path="globals/lodash/index.d.ts" />

File package.json

{
  "name": "ts",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "typings": "./typings/index.d.ts",
  "dependencies": {
    "lodash": "^4.16.4"
  },
  "author": "",
  "license": "ISC"
}

File tsconfig.json

{
  "compilerOptions": {
    "target": "ES6",
    "jsx": "react",
    "module": "commonjs",
    "sourceMap": true,
    "noImplicitAny": true,
    "experimentalDecorators": true,
    "typeRoots" : ["./typings"],
    "types": ["lodash"]
  },
  "include": [
    "typings/**/*",
    "src/**/*"
  ],
  "exclude": [
    "node_modules",
    "**/*.spec.ts"
  ]
}

File typings.json

{
    "name": "TestName",
    "version": false,
    "globalDependencies": {
        "lodash": "file:typings/custom/lodash.d.ts"
    }
}

Despite trying multiple approaches to include typings:

Directly importing it in foo.ts
Using a typings property in package.json
Utilizing typeRoots in tsconfig.json with a file typings/index.d.ts
Employing an explicit types declaration in tsconfig.json
Including the types directory in tsconfig.json
Creating a custom typings.json file and executing typings install

Nevertheless, when compiling Typescript:

E:\temp\ts>tsc
error TS2688: Cannot find type definition file for 'lodash'.

What could be the issue here?

typescript npm typescript-typings

Answer 1

Answer №1

Regrettably, the documentation for these concepts is currently lacking. However, I'll explain your configuration to help you understand how it impacts typescript processing and loading typings.

Let's address the error message you're encountering:

Error TS2688: Cannot find type definition file for 'lodash'.

This error doesn't stem from your imports or usage of lodash in your code, but rather from the incorrect utilization of the typeRoots and types properties. Let's delve deeper into this issue.

The typeRoots:[] and types:[] properties are specific to TypeScript 2.0 feature enabling the packaging and loading of typing declarations from NPM packages.

It's crucial to grasp that these properties exclusively work with folders following the NPM package format (i.e., containing a package.json or index.d.ts).

Default setting for typeRoots is:

{
   "typeRoots" : ["node_modules/@types"]
}

This means TypeScript will search for npm-like packages within the node_modules/@types folder for declaration files.

If the folder structure doesn't match npm conventions, such as in your case, errors like the one you received will occur.

You changed the typeRoot to:

{
    "typeRoots" : ["./typings"]
}

This change tells TypeScript to scan the ./typings folder for subfolders and treat each one as an npm module.

When only using typeRoots to point to ./typings without specifying the types:[] property, errors such as:

Error TS2688: Cannot find type definition file for 'custom'.
Error TS2688: Cannot find type definition file for 'global'.

Will arise because TypeScript interprets the subfolders within ./typings as npm packages due to missing index.d.ts or package.json.

In conclusion, TypeScript 2.0's typeRoots and types cater to automatically loading global declarations packaged in npm modules. For standalone loose .d.ts files or custom typings, traditional inclusion methods must be utilized instead of these new properties.

EDIT:

It's worth noting that typeRoots and types serve primarily for auto-loading global declarations. Any explicit module imports will bypass these settings in favor of other resolution options like baseUrl, paths, and moduleResolution.

To manage type declarations not conforming to npm package structures, consider manual inclusion techniques in your compilation context.

Answer 2

Regrettably, the documentation for these concepts is currently lacking. However, I'll explain your configuration to help you understand how it impacts typescript processing and loading typings.

Let's address the error message you're encountering:

Error TS2688: Cannot find type definition file for 'lodash'.

This error doesn't stem from your imports or usage of lodash in your code, but rather from the incorrect utilization of the typeRoots and types properties. Let's delve deeper into this issue.

The typeRoots:[] and types:[] properties are specific to TypeScript 2.0 feature enabling the packaging and loading of typing declarations from NPM packages.

It's crucial to grasp that these properties exclusively work with folders following the NPM package format (i.e., containing a package.json or index.d.ts).

Default setting for typeRoots is:

{
   "typeRoots" : ["node_modules/@types"]
}

This means TypeScript will search for npm-like packages within the node_modules/@types folder for declaration files.

If the folder structure doesn't match npm conventions, such as in your case, errors like the one you received will occur.

You changed the typeRoot to:

{
    "typeRoots" : ["./typings"]
}

This change tells TypeScript to scan the ./typings folder for subfolders and treat each one as an npm module.

When only using typeRoots to point to ./typings without specifying the types:[] property, errors such as:

Error TS2688: Cannot find type definition file for 'custom'.
Error TS2688: Cannot find type definition file for 'global'.

Will arise because TypeScript interprets the subfolders within ./typings as npm packages due to missing index.d.ts or package.json.

In conclusion, TypeScript 2.0's typeRoots and types cater to automatically loading global declarations packaged in npm modules. For standalone loose .d.ts files or custom typings, traditional inclusion methods must be utilized instead of these new properties.

EDIT:

It's worth noting that typeRoots and types serve primarily for auto-loading global declarations. Any explicit module imports will bypass these settings in favor of other resolution options like baseUrl, paths, and moduleResolution.

To manage type declarations not conforming to npm package structures, consider manual inclusion techniques in your compilation context.

Answer 3

Answer №2

Note: this information may be outdated. Please refer to the previous answer for the most current solution.

Although I'm still a bit confused, I managed to find a fix. You can resolve it by using the provided tsconfig.json:

{
  "compilerOptions": {
    "target": "ES6",
    "jsx": "react",
    "module": "commonjs",
    "sourceMap": true,
    "noImplicitAny": true,
    "experimentalDecorators": true,
    "baseUrl": ".",
    "paths": {
      "*": [
        "./typings/*"
      ]
    }
  },
  "include": [
    "src/**/*"
  ],
  "exclude": [
    "node_modules",
    "**/*.spec.ts"
  ]
}

Delete the typings.json file and all content within the typings folder except for lodash.d.ts. Additionally, remove any references starting with ///...

Answer 4

Note: this information may be outdated. Please refer to the previous answer for the most current solution.

Although I'm still a bit confused, I managed to find a fix. You can resolve it by using the provided tsconfig.json:

{
  "compilerOptions": {
    "target": "ES6",
    "jsx": "react",
    "module": "commonjs",
    "sourceMap": true,
    "noImplicitAny": true,
    "experimentalDecorators": true,
    "baseUrl": ".",
    "paths": {
      "*": [
        "./typings/*"
      ]
    }
  },
  "include": [
    "src/**/*"
  ],
  "exclude": [
    "node_modules",
    "**/*.spec.ts"
  ]
}

Delete the typings.json file and all content within the typings folder except for lodash.d.ts. Additionally, remove any references starting with ///...

Answer 5

Answer №3

"*": ["./types/*"] I finally resolved everything after a 2-hour struggle thanks to this line in my tsconfig paths.

{
  "compilerOptions": {
    "moduleResolution": "node",
    "strict": true,
    "baseUrl": ".",
    "paths": {
      "*": ["./types/*"]
    },
    "jsx": "react",
    "types": ["node", "jest"]
  },
  "include": [
    "client/**/*",
    "packages/**/*"
  ],
  "exclude": [
    "node_modules/**/*"
  ]
}

types is the name of the folder, positioned next to the node_module at the same level as the client folder (or src folder) types/third-party-lib/index.d.ts
index.d.ts contains

declare module 'third-party-lib';

Note: The configuration above is just a partial example showcasing types, paths, include, and exclude options within it.

Answer 6

"*": ["./types/*"] I finally resolved everything after a 2-hour struggle thanks to this line in my tsconfig paths.

{
  "compilerOptions": {
    "moduleResolution": "node",
    "strict": true,
    "baseUrl": ".",
    "paths": {
      "*": ["./types/*"]
    },
    "jsx": "react",
    "types": ["node", "jest"]
  },
  "include": [
    "client/**/*",
    "packages/**/*"
  ],
  "exclude": [
    "node_modules/**/*"
  ]
}

types is the name of the folder, positioned next to the node_module at the same level as the client folder (or src folder) types/third-party-lib/index.d.ts
index.d.ts contains

declare module 'third-party-lib';

Note: The configuration above is just a partial example showcasing types, paths, include, and exclude options within it.

Answer 7

Answer №4

While this question may be old, it's important to note that typescript tooling is constantly evolving. One of the most reliable options currently available is to utilize the "include" path settings within tsconfig.json.


  "include": [
        "src/**/*"
    ],

By default, without any specific modifications, all *.ts and *.d.ts files located under src/ will be automatically included. This method proves to be the simplest and most efficient way to incorporate custom type declaration files without having to customize typeRoots or types.

For further information, you can refer to:

https://www.typescriptlang.org/docs/handbook/tsconfig-json.html

Answer 8

While this question may be old, it's important to note that typescript tooling is constantly evolving. One of the most reliable options currently available is to utilize the "include" path settings within tsconfig.json.


  "include": [
        "src/**/*"
    ],

By default, without any specific modifications, all *.ts and *.d.ts files located under src/ will be automatically included. This method proves to be the simplest and most efficient way to incorporate custom type declaration files without having to customize typeRoots or types.

For further information, you can refer to:

https://www.typescriptlang.org/docs/handbook/tsconfig-json.html

Adding custom type definitions for an untyped npm module in TypeScript 2

Answer №1

EDIT:

Answer №2

Answer №3

Answer №4

Similar questions

The GraphQl Code Generator fails to correctly generate the graphql() function in Next.js applications

Asynchronous function in TypeScript is restricting the return type to only one promise type

The value of type 'string' cannot be assigned to type '"menu" | "selectedMenu" | undefined' as it is not compatible with the specified types

What does it mean when a npm package is intended for use exclusively on the server side?

Loading components in an Angular CLI project with the base URL

Top tips for getting npm bin -g to only display the path

How can you determine when the `prepublish` script is triggered by executing `npm install`?

Encountering issues when verifying the ID of Angular route parameters due to potential null or undefined strings

Challenges with date formatting arise for Spanish speakers when the date returns as NaN or an Invalid

Angular V8 build is not functioning correctly because it is broken

Intro.js is not compatible with React and Remix.run

A single npm package designed for diverse assembly languages

Issue encountered in WebStorm: Unable to start Karma server due to a TypeError stating that undefined is not a function when trying to execute

Is it possible for a factory provider to include optional dependencies?

Setting up ESLint and Prettier with TypeScript on Node 20: A Guide

Specify the location of `~/.config` in Bower

Utilizing getServerSideProps in the new app router (app/blah/page.tsx) for maximum functionality

What is the process for updating the registry in the package-lock.json file?

Merge is showing an error message indicating that I am trying to import runtime.js from outside the src directory, even though the file structure remains unchanged

Encountering issues with npm installation due to the errno -2 error