or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-rollup-plugin-dts

A rollup plugin that bundles TypeScript definition files (.d.ts) into consolidated declaration files.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/rollup-plugin-dts@6.2.x

To install, run

npx @tessl/cli install tessl/npm-rollup-plugin-dts@6.2.0

index.mddocs/

Rollup Plugin DTS

Rollup Plugin DTS is a Rollup plugin that bundles TypeScript definition files (.d.ts) into consolidated declaration files. It uses the TypeScript compiler API to intelligently process and merge multiple declaration files while preserving type information and module relationships.

Package Information

  • Package Name: rollup-plugin-dts
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install --save-dev rollup-plugin-dts

Core Imports

import { dts } from "rollup-plugin-dts";

For legacy support (default import - both exports are identical):

import dts from "rollup-plugin-dts";

Type-only imports:

import type { Options } from "rollup-plugin-dts";

CommonJS:

const { dts } = require("rollup-plugin-dts");

Basic Usage

import { dts } from "rollup-plugin-dts";

const config = [
  // Your regular build configuration
  {
    input: "src/index.ts",
    output: [{ file: "dist/my-library.js", format: "cjs" }],
    plugins: [/* other plugins */],
  },
  // Declaration file bundling configuration
  {
    input: "./src/index.d.ts", // or generated .d.ts files
    output: [{ file: "dist/my-library.d.ts", format: "es" }],
    plugins: [dts()],
  },
];

export default config;

Capabilities

DTS Plugin

The main plugin function that creates a Rollup plugin for bundling TypeScript declaration files.

/**
 * Creates a Rollup plugin that bundles TypeScript declaration files
 * @param options - Plugin configuration options
 * @returns Rollup plugin instance
 */
function dts(options?: Options): Plugin;

Usage Examples:

import { dts } from "rollup-plugin-dts";

// Basic usage with no options
export default {
  input: "types/index.d.ts",
  output: { file: "dist/bundle.d.ts", format: "es" },
  plugins: [dts()],
};

// With configuration options
export default {
  input: "types/index.d.ts", 
  output: { file: "dist/bundle.d.ts", format: "es" },
  plugins: [
    dts({
      respectExternal: true,
      includeExternal: ["some-types-package"],
      compilerOptions: {
        baseUrl: "./",
        paths: {
          "@/*": ["src/*"]
        }
      },
      tsconfig: "./tsconfig.build.json"
    })
  ],
};

Configuration Options

Plugin configuration interface for customizing bundling behavior.

interface Options {
  /**
   * Controls external library classification. When true, uses rollup's external
   * configuration instead of automatically marking all node_modules as external.
   * @default false
   */
  respectExternal?: boolean;
  
  /**
   * List of external module names to include types from instead of marking as external.
   * Useful for bundling specific @types packages or external library types.
   * @default []
   */
  includeExternal?: Array<string>;
  
  /**
   * TypeScript compiler options for path-mapping and module resolution.
   * Commonly used for baseUrl and paths configuration.
   * @default {}
   */
  compilerOptions?: ts.CompilerOptions;
  
  /**
   * Path to custom tsconfig.json file for TypeScript configuration.
   * By default, will try to load 'tsconfig.json' from the current directory.
   */
  tsconfig?: string;
}

Configuration Examples:

// Path mapping support
const config = dts({
  compilerOptions: {
    baseUrl: "./",
    paths: {
      "@utils/*": ["src/utils/*"],
      "@types/*": ["types/*"]
    }
  }
});

// Include external types
const config = dts({
  includeExternal: ["@types/node", "typescript"],
  respectExternal: false
});

// Custom tsconfig
const config = dts({
  tsconfig: "./tsconfig.declarations.json"
});

Advanced Usage Patterns

Multiple Entry Points

// Handle multiple entry points
export default {
  input: {
    main: "types/index.d.ts",
    utils: "types/utils.d.ts", 
    helpers: "types/helpers.d.ts"
  },
  output: {
    dir: "dist/types",
    format: "es"
  },
  plugins: [dts()],
};

Working with Generated Types

// Bundle TypeScript-generated declaration files
export default [
  // First, build your TypeScript source
  {
    input: "src/index.ts",
    output: { file: "dist/index.js", format: "cjs" },
    plugins: [typescript({ declaration: true, outDir: "temp" })],
  },
  // Then bundle the generated .d.ts files
  {
    input: "temp/index.d.ts",
    output: { file: "dist/index.d.ts", format: "es" },
    plugins: [dts()],
  },
];

JSON Module Support

// When using resolveJsonModule in TypeScript
export default {
  input: "src/index.ts",
  output: { file: "dist/bundle.d.ts", format: "es" },
  plugins: [
    dts({
      compilerOptions: {
        resolveJsonModule: true
      }
    })
  ],
};

Key Features

Automatic External Handling

The plugin automatically marks all external libraries from node_modules as external, preventing them from being bundled. This behavior can be controlled with the respectExternal option.

TypeScript Integration

Uses the TypeScript compiler API for:

  • Intelligent module resolution
  • Type-aware bundling
  • Support for TypeScript language features
  • Proper handling of declaration files

Multi-Program Support

Creates separate TypeScript programs for different entry points when they have different compiler configurations or are in different directories.

Reference Processing

Handles TypeScript triple-slash references:

  • /// <reference path="..." /> for file references
  • /// <reference types="..." /> for type references

Namespace Conversion

Converts JavaScript-style namespace exports to proper TypeScript namespace declarations in the final output.

Error Handling

The plugin will emit TypeScript compilation errors and halt the build if:

  • TypeScript compilation fails with errors
  • Required source files cannot be found
  • Invalid TypeScript syntax is encountered

Common errors include:

  • Missing type dependencies
  • Circular dependencies in declaration files
  • Invalid module resolution paths
  • Incompatible TypeScript compiler options

Compatibility

  • Node.js: Requires Node.js 16 or higher
  • Rollup: Compatible with Rollup 3.29.4+ and 4.x
  • TypeScript: Supports TypeScript 4.5+ and 5.x
  • Module Formats: Outputs ES module format declaration files