or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-dts-generator

Generates a single d.ts bundle containing external modules from TypeScript files.

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/dts-generator@3.0.x

To install, run

npx @tessl/cli install tessl/npm-dts-generator@3.0.0

dts-generator

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.

Package Information

Package Name: dts-generator
Package Type: npm
Language: TypeScript
Installation: npm install dts-generator

Core Imports

import 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;

Basic Usage

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
});

Architecture

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:

TypeScript Language Services Integration: Uses the official TypeScript compiler for accurate type analysis
Module Resolution: Flexible module ID and import resolution with custom callbacks
File Processing: Glob-based inclusion/exclusion with tsconfig.json integration
Bundle Generation: Single output file with consolidated declarations

Capabilities

Declaration Bundle Generation

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>;

Configuration Options

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;
}

Module Resolution Callbacks

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;
}

Command-Line Interface

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>;

Usage Examples

Project-based Generation

import generate from "dts-generator";

// Generate from tsconfig.json project
await generate({
  name: 'my-library',
  project: './src',
  out: 'dist/my-library.d.ts'
});

File-specific Generation

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']
});

Advanced Configuration

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}`;
  }
});

External Dependencies

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']
});

Command-Line Usage

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"

Error Handling

The generate function throws errors for:

Configuration errors: Missing required options, invalid file paths
TypeScript compilation errors: Syntax errors, type errors in source files
File system errors: Permission issues, missing directories
Module resolution errors: Unresolvable imports, circular dependencies

All errors include detailed diagnostic information from the TypeScript compiler when applicable.