How typescript finds the location of type declaration file

TypeScript uses several mechanisms to find and load type declaration files automatically. When you import a module, TypeScript follows a series of steps to locate the appropriate type definitions. Here's an overview of how TypeScript finds declaration files:

Steps to Locate Declaration Files

1. TypeScript Built-in Definitions:

   • TypeScript includes built-in type definitions for the standard JavaScript environment (like Array, Map, etc.). These are always available without any additional configuration.

2. Triple-Slash Directives:

   • TypeScript files can include triple-slash directives (/// <reference path="..." />) to explicitly reference other declaration files.

3. types or typings Field in package.json:

   • When a package includes type definitions, it often specifies them in the types or typings field of its package.json file. For example:

     {
       "name": "my-package",
       "version": "1.0.0",
       "types": "index.d.ts"
     }
     

4. @types Packages:

   • For many popular JavaScript libraries, the type definitions are maintained separately in the DefinitelyTyped repository and distributed via @types packages. When you install a package like lodash, you can install its type definitions with:

     npm install --save-dev @types/lodash
     

   • TypeScript automatically looks for @types packages in the node_modules/@types directory.

5. Declaration Files in the Module:

   • If the module includes its own .d.ts files, TypeScript will use those. These are typically located in the root of the module or specified by the types field in package.json.

6. node_modules Resolution:

   • TypeScript follows the Node.js module resolution strategy. When you import a module, TypeScript looks for type definitions in the following order:
     • Look for a package.json file in the module root and check the types or typings field.
     • Look for an index.d.ts file in the module root.
     • Traverse up the directory tree, looking for node_modules directories and repeating the previous steps.

Example: Locating Lodash Type Definitions

When you import Lodash in your TypeScript file like this:

import _ from 'lodash';

TypeScript will follow these steps:

1. Check for a lodash Package:

   • Look in node_modules/lodash/package.json for a types or typings field.
   • Lodash does not include its own type definitions, so this step does not yield results.

2. Check for @types Package:

   • Look in node_modules/@types/lodash for type definitions.
   • The @types/lodash package provides the type definitions for Lodash.

3. Use the Type Definitions:

   • Once TypeScript finds the type definitions in node_modules/@types/lodash, it uses them to provide type checking and IntelliSense for Lodash.

Installing and Using @types Packages

To ensure TypeScript finds and uses the correct type definitions, you install the @types package corresponding to the module:

npm install lodash
npm install --save-dev @types/lodash

or

yarn add lodash
yarn add @types/lodash --dev