dts-generator is a TypeScript declaration file (.d.ts) generator that creates single bundle files containing external module declarations from TypeScript module files. It leverages the TypeScript language services to consolidate multiple TypeScript modules into a single .d.ts file with declare module 'foo' declarations, enabling distribution of a single declaration file alongside compiled JavaScript.
npm install dts-generatorimport generate from "dts-generator";
import type { Options, ResolveModuleIdParams, ResolveModuleImportParams } from "dts-generator";When using TypeScript-specific options:
import * as ts from "typescript";
import generate from "dts-generator";For CommonJS:
const generate = require("dts-generator").default;import generate from "dts-generator";
// Basic programmatic usage
await generate({
name: 'my-package',
project: '/path/to/package-directory',
out: 'my-package.d.ts'
});
// Advanced configuration
await generate({
name: 'my-library',
main: 'my-library/main',
project: './src',
out: 'dist/my-library.d.ts',
exclude: ['**/*.test.ts'],
prefix: 'my-namespace',
verbose: true
});dts-generator processes TypeScript files through the TypeScript compiler API to extract declaration information, then restructures the output into external module format. The tool supports:
Main generation function that processes TypeScript files and creates a consolidated .d.ts bundle.
/**
* Generate a TypeScript declaration bundle from source files
* @param options Configuration options for the generation process
* @returns Promise that resolves when generation is complete
*/
function generate(options: Options): Promise<void>;Complete configuration interface supporting all generation scenarios.
interface Options {
/** Base directory for the package being bundled (deprecated, use project) */
baseDir?: string;
/** Project directory containing tsconfig.json */
project?: string;
/** List of files to bundle */
files?: string[];
/** Glob patterns to exclude from the bundle */
exclude?: string[];
/** External module reference paths for triple-slash references */
externs?: string[];
/** External @types package dependencies for triple-slash references */
types?: string[];
/** End-of-line character for output formatting */
eol?: string;
/** File inclusion patterns (deprecated) */
includes?: string[];
/** Indentation string for output formatting */
indent?: string;
/** Module ID for the package's main export */
main?: string;
/** TypeScript module resolution strategy */
moduleResolution?: ts.ModuleResolutionKind;
/** Package name used with main option */
name?: string;
/** Output file path for the generated bundle */
out: string;
/** Output directory for intermediate files */
outDir?: string;
/** Prefix for module names in the generated bundle */
prefix?: string;
/** Root directory for source files */
rootDir?: string;
/** TypeScript compilation target */
target?: ts.ScriptTarget;
/** Message callback for logging and progress updates */
sendMessage?: (message: any, ...optionalParams: any[]) => void;
/** Custom module ID resolution function */
resolveModuleId?: (params: ResolveModuleIdParams) => string;
/** Custom module import resolution function */
resolveModuleImport?: (params: ResolveModuleImportParams) => string;
/** Enable verbose logging output */
verbose?: boolean;
}Interfaces for customizing module resolution during bundle generation.
interface ResolveModuleIdParams {
/** The identifier of the module being declared in the generated d.ts */
currentModuleId: string;
}
interface ResolveModuleImportParams {
/** The identifier of the module currently being imported in the generated d.ts */
importedModuleId: string;
/** The identifier of the enclosing module currently being declared in the generated d.ts */
currentModuleId: string;
/** True if the imported module id is declared as a module in the input files */
isDeclaredExternalModule: boolean;
}Entry point function for the CLI tool.
/**
* Command-line interface main function
* @param argv Command line arguments array
* @returns Promise resolving to exit code or void
*/
function main(argv: string[]): Promise<number | void>;import generate from "dts-generator";
// Generate from tsconfig.json project
await generate({
name: 'my-library',
project: './src',
out: 'dist/my-library.d.ts'
});import generate from "dts-generator";
// Generate from specific files
await generate({
baseDir: './src',
files: ['index.ts', 'utils.ts', 'types.ts'],
out: 'dist/library.d.ts',
exclude: ['**/*.test.ts', '**/*.spec.ts']
});import generate from "dts-generator";
import * as ts from "typescript";
await generate({
name: 'my-complex-library',
main: 'my-complex-library/main',
project: './src',
out: 'dist/my-complex-library.d.ts',
prefix: 'MyLib',
target: ts.ScriptTarget.ES2015,
moduleResolution: ts.ModuleResolutionKind.NodeJs,
verbose: true,
sendMessage: (msg) => console.log(`[dts-gen] ${msg}`),
resolveModuleId: ({ currentModuleId }) => `custom/${currentModuleId}`,
resolveModuleImport: ({ importedModuleId, isDeclaredExternalModule }) => {
return isDeclaredExternalModule ? importedModuleId : `custom/${importedModuleId}`;
}
});import generate from "dts-generator";
// Include external type references
await generate({
name: 'my-library',
project: './src',
out: 'dist/my-library.d.ts',
externs: ['../other-library/types.d.ts'],
types: ['node', 'mocha']
});The package provides a command-line interface accessible through the dts-generator binary:
# Basic CLI usage
dts-generator --name my-package --project ./src --out my-package.d.ts
# With exclusions and external types
dts-generator --name my-lib --project ./src --out dist/my-lib.d.ts --exclude "**/*.test.ts" --types node --verbose
# Multiple exclusions
dts-generator --name my-lib --project ./src --out my-lib.d.ts --exclude "**/*.test.ts" --exclude "**/*.spec.ts"The generate function throws errors for:
All errors include detailed diagnostic information from the TypeScript compiler when applicable.