NPM DTS Single File Generator

Common errors

• Error: Cannot find module 'typescript'

  cause The `typescript` package is not installed as a local dependency in the project where `npm-dts` is being run.
  fix Run `npm install --save-dev typescript` in your project's root directory.

• Error: ENOENT: no such file or directory, stat 'your/path/index.ts'

  cause The entry file specified by `--entry` (or the default `index.ts`) does not exist at the expected path relative to the `tsconfig.json`'s `rootDir`.
  fix Verify the path provided to `--entry` is correct and relative to your TypeScript `rootDir`. Check your `tsconfig.json` for `compilerOptions.rootDir` and ensure the entry file exists.

• TypeScript compilation failed with errors.

  cause There are unhandled compilation errors in your source TypeScript files that `npm-dts` cannot resolve, preventing successful declaration file generation.
  fix Before running `npm-dts`, ensure your project compiles without errors by running `tsc --noEmit`. Address all reported TypeScript errors in your source code.

Warnings

• gotcha It is critical that `typescript` is installed as a local `devDependency` or `dependency` in the project where `npm-dts` is executed. `npm-dts` relies on the local `tsc` binary and its associated modules.
  Fix: Ensure `typescript` is listed in your `package.json` under `devDependencies` (e.g., `npm install --save-dev typescript`).
• gotcha The `--entry` option's path resolution can be complex when `rootDir` is not explicitly set in `tsconfig.json`. TypeScript might infer `rootDir`, leading to unexpected 'file not found' errors if the `--entry` path doesn't align with the inference.
  Fix: Explicitly set `compilerOptions.rootDir` in your `tsconfig.json`, or provide the `--entry` path relative to the inferred `rootDir` (e.g., `src/index.ts` if `src` is your `rootDir`).
• gotcha Using the `--force` option can result in a partially generated or incorrect declaration file if underlying TypeScript compilation errors are significant. It forces generation despite non-critical errors.
  Fix: It is best practice to resolve all TypeScript compilation errors in your source code before running `npm-dts` for reliable type generation. Use `--force` only when absolutely necessary and carefully inspect the generated output.

Install

• npm install npm-dts npm
• yarn add npm-dts yarn
• pnpm add npm-dts pnpm

Imports

• generate
  wrong:

  const { generate } = require('npm-dts');

  correct:

  import { generate } from 'npm-dts';

  Primarily a CLI tool; the `generate` function allows programmatic use for advanced build workflows. ESM is preferred.

Quickstart

Demonstrates how to integrate `npm-dts` into a `package.json` script to generate a single `index.d.ts` file after TypeScript compilation for a library project.

// package.json (inside your library project)
{
  "name": "my-library",
  "version": "1.0.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts", // Point to the generated declaration file
  "devDependencies": {
    "typescript": "^5.0.0", // Required peer dependency for npm-dts
    "npm-dts": "^1.3.0"
  },
  "scripts": {
    "build:ts": "tsc", // Standard TypeScript compilation
    "build:dts": "npm-dts generate --output dist/index.d.ts", // Generate bundled d.ts
    "build": "npm run build:ts && npm run build:dts"
  },
  "files": [
    "dist"
  ]
}

// src/index.ts (example source file)
export function greet(name: string): string {
  return `Hello, ${name}!`
}

export interface User {
  id: number;
  name: string;
}

export class Greeter {
  constructor(private message: string) {}
  sayHello(): string {
    return this.message;
  }
}

// To run this after project setup:
// 1. npm install
// 2. npm run build
// This will compile TS to JS, then bundle all .d.ts files into a single dist/index.d.ts.