TypeScript Declaration File Resolver

2.1.3 · active · verified Sun Apr 19

dts-resolver is a utility library designed to accurately locate and resolve TypeScript declaration files (.d.ts) for JavaScript and TypeScript dependencies within a project. It leverages the high-performance `oxc-resolver` engine to efficiently navigate `node_modules` and package `exports` maps, providing correct paths to type definitions. The current stable version is 2.1.3. The package has a moderately active release cadence, frequently incorporating bug fixes and performance improvements, and keeping up with its underlying resolver. Its key differentiator is its reliance on `oxc-resolver`, offering a robust and modern approach to declaration file resolution, crucial for build tools, IDEs, and other development workflows that need to understand the type landscape of a project's dependencies.

Common errors

```
Error: Cannot find module 'oxc-resolver' from '<your-project-path>'
```
cause `oxc-resolver` is a peer dependency of `dts-resolver` and must be installed explicitly in your project.

fix Install `oxc-resolver`: `npm install oxc-resolver` or `yarn add oxc-resolver`.
```
TypeError: createResolver is not a function (or similar CommonJS error)
```
cause `dts-resolver` is distributed as an ESM-first package, and attempts to use `require()` directly in a CommonJS context without proper transpilation will fail.

fix Ensure your project uses ESM imports (`import ... from '...'`) or is properly configured to transpile ESM to CommonJS if you are in a legacy CommonJS environment. Update your `package.json` to include `"type": "module"` for ESM support.

Warnings

breaking Version 2.0.0 introduced `oxc-resolver` as a mandatory peer dependency. Projects must explicitly install `oxc-resolver` alongside `dts-resolver`.
Fix: Run `npm install oxc-resolver` or `yarn add oxc-resolver` in your project alongside `dts-resolver`.
gotcha The `cwd` option in `createResolver` is crucial for correct path resolution, especially in monorepos or projects with non-standard directory structures. Ensure it points to the root of the project where `node_modules` is expected.
Fix: Always pass an explicit `cwd` to `createResolver` if your execution context might differ from `process.cwd()`. For most cases, `process.cwd()` is sufficient.

Install

npm install dts-resolver npm
yarn add dts-resolver yarn
pnpm add dts-resolver pnpm

Imports

createResolver
wrong:
```
const { createResolver } = require('dts-resolver');
```
correct:
```
import { createResolver } from 'dts-resolver';
```
The library is primarily designed for ESM environments. While CommonJS might work with transpilation, direct `require` is not the idiomatic or recommended way. No default export exists.
ResolverOptions
```
import type { ResolverOptions } from 'dts-resolver';
```
Type imports are typically used for defining configuration objects or function parameters.

Quickstart

Demonstrates how to initialize `dts-resolver` and resolve the TypeScript declaration file path for a specified npm package.

import { createResolver } from 'dts-resolver';
import path from 'node:path';

async function resolveTypesForPackage(packageName: string) {
  const resolver = createResolver({
    cwd: process.cwd(), // Define the current working directory for resolution
    // You can add custom conditions if your project uses them, e.g., ['node', 'require', 'types']
    // conditions: ['node', 'require', 'types'],
    // Optionally disable resolving node modules if you only want local files, though usually not desired for dts resolution
    // resolveNodeModules: true,
  });

  try {
    const declarationPath = resolver(packageName);
    if (declarationPath) {
      console.log(`Resolved declaration for '${packageName}': ${declarationPath}`);
      console.log(`Located in directory: ${path.dirname(declarationPath)}`);
    } else {
      console.log(`Could not resolve declaration for '${packageName}'.`);
    }
  } catch (error) {
    console.error(`Error resolving '${packageName}':`, error);
  }
}

// Example usage for a common package
resolveTypesForPackage('fast-glob');
// Example for a package that might not have direct types or different structure
resolveTypesForPackage('lodash');

view raw JSON →