typegen

Bundle TypeScript declaration files (.d.ts) into standalone packages — no transitive type dependencies required.

📦 "Ship types. We’ll carry the baggage."

Give a Star on GitHub

If typegen helps you, please give it a star: https://github.com/epikodelabs/typegen

✨ Why typegen

typegen creates standalone TypeScript declaration bundles by inlining types from your internal packages. Your published library ships with complete, self-contained typings, so consumers can install your package normally — without needing your entire monorepo or its internal dependencies.

Highlights

• 📦 Standalone .d.ts bundles with zero transitive dependencies
• 🔗 Smart cross-package type resolution across your monorepo
• 🌍 External dependency preservation (keeps React, Node, etc. intact)
• 🎯 Intelligent type inlining (only what's actually used)
• ✅ Output validation to catch errors before publishing
• ⚡ Full TypeScript Compiler API integration

🤔 The Problem

You've built a TypeScript library in a monorepo. Your types work perfectly locally. Then you publish, and consumers face this:

error TS2307: Cannot find module '@yourorg/internal-utils'
error TS2307: Cannot find module '@yourorg/shared-types'
error TS2307: Cannot find module '@yourorg/core-helpers'

Why? When publishing libraries from a monorepo, TypeScript normally emits declaration files that reference internal workspace packages. If those packages aren’t published, consumers installing your library get unresolved type imports and broken typings.

The usual "fix":

• Add internal packages as peerDependencies so TypeScript can resolve them ❌
• Require consumers to install packages they never use directly ❌
• Expand your dependency graph just to satisfy type resolution ❌

The typegen fix:

• Bundle all internal types into one self-contained .d.ts file ✅
• Preserve external dependencies (React, Node, etc.) ✅
• Ship types that actually work out of the box ✅

⚡ How it works

When TypeScript builds a monorepo package, it emits declaration files that preserve imports to other workspace packages.

Before Bundling

Package A:

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

Package B:

import { User } from '@myorg/core';  // ← Internal dependency

export declare class UserAPI {
  getUser(id: string): Promise<User>;
}

❌ Publishing this requires consumers to install @myorg/core

After Bundling with typegen

typegen compiles your project and produces a bundled declaration file where internal types are inlined.

index.d.ts:

// Inlined from @myorg/core
interface User {
  id: string;
  name: string;
}

// Original declarations
declare class UserAPI {
  getUser(id: string): Promise<User>;
}

export { UserAPI };

✅ Consumers install one package. TypeScript works immediately.

💿 Installation

npm install --save-dev @epikodelabs/typegen

🚀 Quick start

1. Initialize configuration

npx typegen init

2. Bundle your declarations

npx typegen

3. Find your bundles in dist/ 🎉

✨ Features

• 🎯 Smart Type Inlining — Only includes types actually used in your public API
• 🔗 Cross-Package Resolution — Follows imports across your entire monorepo
• 📊 Dependency Graph Analysis — Detects and reports circular dependencies
• 🌍 External Import Preservation — Keeps third-party imports (react, node, etc.) untouched
• 🔄 Topological Sorting — Processes packages in correct dependency order
• ✅ Output Validation — Verifies bundled declarations compile correctly
• ⚡ Full TypeScript Integration — Uses official TypeScript Compiler API

📌 When to use typegen

Use it if:

• ✅ You publish TypeScript libraries from a monorepo
• ✅ Your packages reference types from other workspace packages
• ✅ You want consumers to install one package, not your entire repo (and who wouldn't?)
• ✅ You're tired of "Cannot find module" errors from legitimate code

Skip it if:

• ❌ You publish single-package libraries (no cross-package type imports)
• ❌ You're okay with massive peerDependencies lists (brave soul)
• ❌ Your users enjoy archaeological expeditions through node_modules

🔧 Configuration

typegen init creates typegen.json:

{
  "tsconfig": "tsconfig.json",
  "includeComments": false,
  "banner": "",
  "exclude": ["**/*.spec.ts", "**/*.test.ts", "**/node_modules/**"],
  "include": ["**/*.d.ts"],
  "verbose": false,
  "validateOutput": true,
  "sortStatements": false
}

Configuration options

| Option | Type | Default | Description | |--------|------|---------|-------------| | tsconfig | string | "tsconfig.json" | Path to your TypeScript config | | includeComments | boolean | false | Preserve JSDoc and comments in bundled output | | banner | string | "" | Custom banner text for bundled files | | exclude | string[] | See above | Files to ignore during bundling | | include | string[] | ["**/*.d.ts"] | Files to include in bundling | | verbose | boolean | false | Enable detailed logging | | validateOutput | boolean | true | Compile bundled .d.ts to catch errors | | sortStatements | boolean | false | Topologically sort declarations (experimental) |

🐛 Troubleshooting

No entry points found

typegen relies on the TypeScript compiler. If TypeScript can’t build your project, typegen can’t bundle it.

Circular dependencies detected

Your types are playing ring-around-the-rosie. Options:

• Refactor shared types into a separate base package (the adult solution)
• Use type extraction to break the cycle (the clever solution)
• Accept chaos and live with the warnings (the brave solution—not recommended)

TypeScript errors in bundle

TypeScript reported errors while typegen was generating the bundle:

• Check that your project compiles cleanly with tsc
• All exported types are valid and resolvable
• Path aliases resolve correctly
• Project references (if used) are valid

Bundle size too large

Your bundle is getting a bit hefty:

• Review what's being exported — you might be exposing internal types unintentionally
• Check for overly broad export * statements (the "take everything" approach)
• Consider splitting into multiple entry points (divide and conquer)

📜 License

MIT © 2026

🤝 Support

• Issues: GitHub Issues
• Documentation: GitHub Wiki