dts-bundle-generator

You can control how external dependencies from node_modules or @types are handled in the generated bundle:

• --external-inlines: An array of package names to inline their typings directly into the output file.
• --external-imports: An array of package names to import using standard import { ... } from 'library-name' syntax. By default, all libraries are imported except those inlined or from @types.
• --external-types: An array of package names from @types to import via triple-slash reference directives.

Important: When using arguments that accept arrays (like --external-inlines or --external-imports) before the positional input files, use the -- separator to prevent the tool from misinterpreting the input files as part of the array.

# Example: Inlining one package and importing others
./node_modules/.bin/dts-bundle-generator \
  --external-inlines=@mycompany/internal-project \
  --external-imports=@angular/core rxjs \
  -- path/to/your/entry-file.ts

# Example: Using external types (e.g., jquery)
./node_modules/.bin/dts-bundle-generator --external-types=jquery path/to/your/entry-file.ts

The dts-bundle-generator CLI is used to bundle TypeScript declaration files (.d.ts) into a single file. You can provide one or more entry files. If you provide multiple entry files, you cannot use the --out-file option; instead, the generator will create a .d.ts file for each entry in its corresponding directory.

Basic Usage:

# Generate a bundle for a single entry file
dts-bundle-generator path/to/your/entry-file.ts

# Generate a bundle for multiple entry files
dts-bundle-generator path/to/file1.ts path/to/file2.ts

# Specify a custom output file for a single entry
dts-bundle-generator path/to/entry.ts --out-file path/to/output.d.ts

# Use a specific configuration file
dts-bundle-generator --config path/to/config.json path/to/entry.ts

# Use a specific tsconfig.json for compilation
dts-bundle-generator --project path/to/tsconfig.json path/to/entry.ts

# Use triple-slash references for specific @types packages
dts-bundle-generator --external-types jquery react -- entry-file.ts

#!/usr/bin/env node

# Example usage from CLI documentation
$0 path/to/your/entry-file.ts
$0 path/to/your/entry-file.ts path/to/your/entry-file-2.ts
$0 --external-types jquery react -- entry-file.ts

A sample JSON configuration demonstrating multiple entries, library inlining, and output formatting.

{
    "compilationOptions": {
        "preferredConfigPath": "./tsconfig.json"
    },

    "entries": [
        {
            "filePath": "./src/index.ts",
            "outFile": "./out/index.d.ts",
            "libraries": {
                "inlinedLibraries": ["@my-company/package"]
            },
            "output": {
                "inlineDeclareGlobals": false,
                "sortNodes": true,
                "umdModuleName": "MyModuleName"
            }
        },
        {
            "filePath": "./src/second.ts",
            "outFile": "./out/second.d.ts",
            "failOnClass": true,
            "libraries": {
                "allowedTypesLibraries": [],
                "importedLibraries": [],
                "inlinedLibraries": []
            }
        },
        {
            "filePath": "./src/third.ts"
        }
    ]
}

A sample JavaScript configuration using @ts-check and importing types from dts-bundle-generator/config-schema to provide autocompletion and validation.

// @ts-check

// If won't use `@ts-check` - just remove that comments (with `@type` JSDoc below).

/** @type import('dts-bundle-generator/config-schema').OutputOptions */
const commonOutputParams = {
    inlineDeclareGlobals: false,
    sortNodes: true,
};

/** @type import('dts-bundle-generator/config-schema').BundlerConfig */
const config = {
    compilationOptions: {
        preferredConfigPath: './tsconfig.json',
    },

    entries: [
        {
            filePath: './src/index.ts',
            outFile: './out/index.d.ts',
            noCheck: false,

            output: commonOutputParams,
        },

        {
            filePath: './src/second.ts',
            outFile: './out/second.d.ts',
            failOnClass: true,

            libraries: {
                inlinedLibraries: ['@my-company/package'],
            },

            output: commonOutputParams,
        },
    ],
};

module.exports = config;

You can provide configuration to dts-bundle-generator using a configuration file. The configuration object must follow the BundlerConfig structure, which includes a list of entry points and optional compilation options.

BundlerConfig Structure

entries (Required)

An array of ConfigEntryPoint objects. Each entry defines what to bundle and how.

ConfigEntryPoint properties:

• filePath (Required): The path to the input TypeScript file.
• outFile (Optional): The path where the generated .d.ts file will be saved. If omitted, the output file will have the same name as the input file but with a .d.ts extension.
• noCheck (Optional): A boolean that, if set to true, skips the validation of the generated .d.ts file.
• failOnClass (Optional): A boolean indicating whether to fail if a class is encountered.
• libraries (Optional): Configuration for handling libraries:
  • allowedTypesLibraries: Array of strings.
  • importedLibraries: Array of strings.
  • inlinedLibraries: Array of strings.
• output (Optional): Configuration for the output format:
  • inlineDeclareGlobals: boolean
  • inlineDeclareExternals: boolean
  • sortNodes: boolean
  • umdModuleName: string
  • noBanner: boolean
  • respectPreserveConstEnum: boolean
  • exportReferencedTypes: boolean

compilationOptions (Optional)

Global settings for the compilation process.

CompilationOptions properties:

• followSymlinks: boolean
• preferredConfigPath: string (Path to a preferred configuration file)

Example Configuration

{
  "entries": [
    {
      "filePath": "src/index.ts",
      "outFile": "dist/index.d.ts",
      "noCheck": false,
      "output": {
        "sortNodes": true
      }
    }
  ],
  "compilationOptions": {
    "followSymlinks": true
  }
}

Use OutputOptions within an EntryPointConfig to control how the generated .d.ts file is structured and styled.