TypeScript Declaration Bundler

A tool for bundling TypeScript files (.ts and/or .d.ts) by inlining local imports and optionally inlining types from specified npm packages. Works both as a CLI tool and as a library you can import in your Node.js projects.

Features

Core Bundling

• 🎯 Inline local imports — Automatically resolves and inlines all relative imports (./ or ../)
• 📦 Selective library inlining — Optionally inline types from specific npm packages
• 🔄 External import consolidation — Keeps external imports at the top of the bundled file
• 🎨 Type-only import handling — Properly handles import type statements
• 🔁 Export re-export resolution — Resolves export * from statements

Advanced Capabilities

• 🧩 Ambient module inlining — Optionally inline declare module "..." blocks for external modules
• 🌐 declare global support — Control whether declare global blocks are inlined or preserved
• 🔀 Declaration merging — Correctly handles TypeScript declaration merging scenarios
• 🌳 Tree shaking — Removes unused declarations from the output
• 🏷️ Name collision resolution — Automatically resolves naming conflicts across files

Output Control

• 📛 UMD module name — Generate UMD-compatible output with export as namespace
• 🔤 Sorted output — Optionally sort declarations alphabetically for consistent diffs
• 📜 Banner control — Include or exclude the generated banner comment
• 🔒 Preserve const enums — Respect preserveConstEnums compiler option
• 📚 Triple-slash references — Automatically add /// <reference types="..." /> for @types/* packages

Developer Experience

• 🛠️ Dual usage — Use as CLI tool or import as a library
• ✨ Full TypeScript support — Complete type definitions included
• ⚡ Fast — Built on the TypeScript compiler API for accurate and efficient parsing

Installation

npm install @qlik/dts-bundler
# or
pnpm add @qlik/dts-bundler
# or
yarn add @qlik/dts-bundler

Usage

As a Library

import { bundleTypes } from "@qlik/dts-bundler";
import fs from "fs";

// Basic usage - returns bundled content as string
const bundledContent = bundleTypes({
  entry: "./src/types.ts",
});

// Write to file
fs.writeFileSync("./dist/bundle.d.ts", bundledContent);

// With inlined libraries
const bundledWithLibs = bundleTypes({
  entry: "./src/types.ts",
  inlinedLibraries: ["@my-org/types", "some-package"],
  inlineDeclareExternals: true,
});

fs.writeFileSync("./dist/bundle.d.ts", bundledWithLibs);

As a CLI Tool

bundle-types -e < entry > -o < output > [-i < inlinedLibraries > ]

CLI Options

• -e, --entry <file> - Required: Entry TypeScript file to bundle
• -o, --output <file> - Required: Output file path for bundled types
• -i, --inlinedLibraries <list> - Optional: Comma-separated list of npm packages to inline
• -h, --help - Show help message

CLI Examples

Basic usage (inline only local imports):

bundle-types -e ./src/types.ts -o ./dist/bundle.d.ts

With npm package inlining:

bundle-types \
  -e ./src/types.ts \
  -o ./dist/bundle.d.ts \
  -i @my-org/types-pkg,@another/types-pkg

Using npm scripts (add to package.json):

{
  "scripts": {
    "bundle-types": "bundle-types -e ./src/types.ts -o ./dist/bundle.d.ts"
  }
}

Then run:

npm run bundle-types

Real-World Use Cases

Use Case 1: Publishing a Library

When publishing a library, bundle internal types but keep framework types external:

import { bundleTypes } from "@qlik/dts-bundler";
import fs from "fs";

const bundled = bundleTypes({
  entry: "./src/index.ts",
  inlinedLibraries: ["@my-company/internal-types"],
});

fs.writeFileSync("./dist/index.d.ts", bundled);

Use Case 2: Monorepo Type Sharing

In a monorepo, inline types from your own packages:

bundle-types \
  -e ./src/types.ts \
  -o ./dist/types.d.ts \
  -i @myorg/pkg-a,@myorg/pkg-b,@myorg/pkg-c

Use Case 3: Single File Distribution

Create a single file with all types for easy distribution:

import { bundleTypes } from "@qlik/dts-bundler";
import fs from "fs";

const bundled = bundleTypes({
  entry: "./src/api.types.ts",
});

fs.writeFileSync("./api-complete.d.ts", bundled);

Use Case 4: Build Pipeline Integration

Integrate into your build process:

// build.js
import { bundleTypes } from "@qlik/dts-bundler";
import fs from "fs";

async function build() {
  // ... other build steps

  const bundled = bundleTypes({
    entry: "./src/public-api.ts",
  });

  fs.writeFileSync("./dist/index.d.ts", bundled);

  console.log("✓ Types bundled!");
}

build();

How It Works

The bundler performs the following steps:

1. Parse Entry File: Reads and parses the entry TypeScript file using the TypeScript compiler API
2. Resolve Imports:
   • Local imports (starting with ./ or ../) are always resolved and inlined
   • Imports from packages in the inlinedLibraries list are also inlined
   • All other imports are tracked as external dependencies
3. Recursive Processing: Recursively processes all files that should be inlined
4. Generate Output:
   • External imports are consolidated and placed at the top
   • All inlined type declarations follow
   • An export {} statement ensures the file is treated as a module

Example Transformation

Input Files

src/types.ts:

import type { ExternalType } from "@external/package";
import type { LocalType } from "./local-types";

export interface MyType extends LocalType {
  external: ExternalType;
}

src/local-types.ts:

export interface LocalType {
  id: string;
  name: string;
}

Output File

dist/bundle.d.ts:

// Generated by @qlik/dts-bundler

import type { ExternalType } from "@external/package";

export interface LocalType {
  id: string;
  name: string;
}

export interface MyType extends LocalType {
  external: ExternalType;
}

export {};

API Reference

For complete API documentation, see the API Reference.

Quick Reference

bundleTypes(options)

Bundle TypeScript declaration files.

import { bundleTypes } from "@qlik/dts-bundler";
import fs from "fs";

const bundled = bundleTypes({
  entry: "./src/types.ts",
  inlinedLibraries: ["@my-org/types"],
  inlineDeclareExternals: true,
});

fs.writeFileSync("./dist/bundle.d.ts", bundled);

Options Summary

Option	Type	Default	Description
entry	string	—	(Required) Entry TypeScript file path
inlinedLibraries	string[]	[]	Libraries to inline into the bundle
allowedTypesLibraries	string[]	undefined	@types/* packages for triple-slash references
importedLibraries	string[]	undefined	Libraries to keep as imports
inlineDeclareGlobals	boolean	false	Inline declare global blocks
inlineDeclareExternals	boolean	false	Inline declare module blocks
exportReferencedTypes	boolean	false	Auto-export referenced types
noBanner	boolean	false	Exclude banner comment
sortNodes	boolean	false	Sort declarations alphabetically
umdModuleName	string	undefined	UMD module name (export as namespace)
respectPreserveConstEnum	boolean	false	Respect tsconfig preserveConstEnums

See the full API documentation for detailed descriptions and examples of each option.

Tips & Best Practices

1. Multiple libraries: Separate with commas (CLI) or use an array (library)

   # CLI
   -i @org/pkg1,@org/pkg2,@org/pkg3

   // Library
   inlinedLibraries: ["@org/pkg1", "@org/pkg2", "@org/pkg3"];

2. Scoped packages: Include the full scope

   inlinedLibraries: ["@mycompany/types", "@anothercompany/utils"];

3. Package subpaths: Specify the exact import path

   inlinedLibraries: ["@mycompany/types/dist/api"];

4. Check the output: Always verify the generated file matches your expectations

   bundle-types -e ./src/types.ts -o ./dist/bundle.d.ts
   head -50 ./dist/bundle.d.ts

Limitations

• Only handles TypeScript files (.ts, .tsx, .mts, .cts, .d.ts, .d.mts, .d.cts)
• Does not handle runtime JavaScript code (this is a type bundler)
• Assumes all imported files exist and are accessible
• Does not perform type checking (use tsc for that)
• Circular dependencies may cause issues in complex scenarios

Requirements

• Node.js >= 20
• TypeScript ^5.9.3 (included as a dependency)

Troubleshooting

"Could not resolve import" warning

This warning appears when the bundler cannot find an imported file. Check:

• The file path is correct
• The file has a .ts, .tsx, or .d.ts extension
• The file exists at the resolved location

Duplicate type definitions

If you see duplicate types in the output, ensure:

• You're not importing the same file through multiple paths
• Your import paths are consistent (absolute vs relative)

Process exits unexpectedly

If the entry file doesn't exist, the process will exit with code 1. Ensure:

• The entry file path is correct
• The file exists before running the bundler

Development

Running Tests

The project uses vitest for testing with snapshot testing for output verification.

# Run tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Update snapshots when output changes are intentional
pnpm test:update

Snapshot Testing

Tests use snapshots to verify bundler output. If you make changes that affect the generated output:

1. Run pnpm test to see the diff
2. Review the changes carefully
3. If correct, run pnpm test:update to update snapshots
4. Commit the updated snapshot files

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Related

• API Reference — Complete API documentation
• TypeScript Handbook: Declaration Files

License

ISC