DTS generation fails with TypeScript path mappings in monorepo

[ThePlenkov]

DTS generation fails with TypeScript path mappings in monorepo

Describe the bug

When building a package in a monorepo that uses TypeScript path mappings to reference other workspace packages, tsdown's DTS generation fails with UNRESOLVED_IMPORT errors. The error messages show that tsdown is trying to resolve imports from a phantom .d.ts file that contains the wrong exports.

Reproduction

Monorepo Structure

packages/
├── types/           # Pure type definitions package
│   └── src/
│       └── index.ts  # Only exports types
├── config/          # Package that depends on @anygpt/types
│   └── src/
│       └── index.ts  # Imports from '@anygpt/types'

TypeScript Configuration

tsconfig.base.json:

{
  "compilerOptions": {
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "baseUrl": ".",
    "paths": {
      "@anygpt/types": ["packages/types/src"],
      "@anygpt/config": ["packages/config/src"]
    }
  }
}

packages/types/src/index.ts:

// Only exports types
export type {
  ConnectorConfig,
  ProviderConfig,
  AnyGPTConfig,
  ConfigLoadOptions
} from './config.js';

packages/config/src/index.ts:

// Re-exports types from @anygpt/types
export type {
  ConnectorConfig,
  ProviderConfig,
  AnyGPTConfig,
  ConfigLoadOptions
} from '@anygpt/types';

// Also exports functions
export { setupRouter, loadConnectors } from './setup.js';

packages/config/tsdown.config.ts:

import { defineConfig } from 'tsdown';

export default defineConfig({
  sourcemap: true,
  tsconfig: 'tsconfig.lib.json',
  skipNodeModulesBundle: true,
  platform: 'node'
  // dts: true (auto-detected from package.json)
});

packages/config/package.json:

{
  "name": "@anygpt/config",
  "types": "./dist/index.d.ts",
  "dependencies": {
    "@anygpt/types": "0.1.0"
  }
}

Build Command

npx nx build config
# or
npx tsdown

Error Output

ERROR  Error: Build failed with 6 errors:

[UNRESOLVED_IMPORT] Error: Could not resolve './types.js' in ../types/src/index.d.ts
   ╭─[ ../types/src/index.d.ts:1:15 ]
   │
 1 │ export * from './types.js';
   │               ──────┬─────  
   │                     ╰─────── Module not found.
───╯

[UNRESOLVED_IMPORT] Error: Could not resolve './defaults.js' in ../types/src/index.d.ts
   ╭─[ ../types/src/index.d.ts:2:62 ]
   │
 2 │ export { getDefaultConfig, convertCodexToAnyGPTConfig } from './defaults.js';
   │                                                              ───────┬───────  
   │                                                                     ╰───────── Module not found.
───╯

[UNRESOLVED_IMPORT] Error: Could not resolve './connector-loader.js' in ../types/src/index.d.ts
   ╭─[ ../types/src/index.d.ts:3:73 ]
   │
 3 │ export { loadConnectors, getConnectorConfig, clearConnectorCache } from './connector-loader.js';
   │                                                                         ───────────┬───────────  
   │                                                                                    ╰───────────── Module not found.
───╯

What is Expected?

The build should succeed and generate proper DTS files with external references to @anygpt/types.

What is Actually Happening?

1. Tsdown resolves @anygpt/types via the TypeScript path mapping to packages/types/src
2. It tries to read/generate a .d.ts file at ../types/src/index.d.ts
3. The phantom file contains WRONG exports - it shows exports from the @anygpt/config package (setupRouter, loadConnectors, etc.) instead of the actual @anygpt/types exports
4. Tsdown then tries to resolve relative imports from this phantom file and fails

Key Observations

• The error path ../types/src/index.d.ts doesn't exist in the source tree
• The exports shown in the error (setupRouter, loadConnectors) are from @anygpt/config, NOT from @anygpt/types
• This suggests tsdown is confusing package contents during DTS bundling
• JavaScript bundling works perfectly - only DTS generation fails

Workaround

Setting dts: false and using tsc directly for DTS generation works:

export default defineConfig({
  sourcemap: true,
  tsconfig: 'tsconfig.lib.json',
  skipNodeModulesBundle: true,
  dts: false  // Disable tsdown DTS generation
});

Then generate DTS separately:

tsc --emitDeclarationOnly --declaration --declarationMap --outDir dist

System Info

• tsdown version: 0.15.6
• rolldown version: 1.0.0-beta.41
• Node version: v24.8.0
• npm version: 11.6.0
• OS: Linux (WSL Ubuntu)
• Package manager: npm

Additional Context

This issue appears to be specific to monorepos using TypeScript path mappings. The DTS bundler seems to have a bug where it:

1. Incorrectly resolves path-mapped imports to source directories
2. Generates or reads phantom .d.ts files with wrong content
3. Confuses exports between different packages

The JavaScript bundling works correctly, so this is isolated to the DTS generation phase.

Suggested Fix

The DTS bundler should either:

1. Properly resolve TypeScript path mappings to built .d.ts files instead of source files
2. Respect skipNodeModulesBundle: true for DTS generation (currently it only affects JS)
3. Add an option to keep path-mapped dependencies as external references in DTS output

Related

This might be related to how rolldown-plugin-dts handles TypeScript project references and path mappings in monorepo setups.

[ThePlenkov]

Update: Root Cause Identified

After further investigation, I discovered the actual root cause of this issue. The problem was not a fundamental bug in tsdown's DTS bundler, but rather an incompatible TypeScript configuration.

The Real Problem

The error occurred because of how TypeScript path mappings were configured:

Broken Configuration:

// tsconfig.base.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@anygpt/types": ["packages/types/src"],  // ❌ Non-relative path
      "@anygpt/config": ["packages/config/src"]
    }
  }
}

When tsdown's DTS generation (especially with tsgo option) tried to process this configuration, it failed with:

• TS5090: Non-relative paths are not allowed. Did you forget a leading './'?
• TS5102: Option 'baseUrl' has been removed. Use '"paths": {"*": ["../../*"]}' instead.

The Solution

Working Configuration:

// tsconfig.base.json
{
  "compilerOptions": {
    // "baseUrl": ".",  // ✅ Removed
    "paths": {
      "@anygpt/types": ["./packages/types/src"],  // ✅ Relative path with ./
      "@anygpt/config": ["./packages/config/src"]
    }
  }
}

After making paths relative and removing baseUrl, DTS generation works perfectly with default settings (auto-detected from package.json).

Result

// tsdown.config.ts - No special DTS configuration needed!
export default defineConfig({
  sourcemap: true,
  tsconfig: 'tsconfig.lib.json',
  skipNodeModulesBundle: true
  // dts is auto-detected and works correctly
});

Build output:

• ✅ dist/index.js (20.95 kB) - Bundled JavaScript
• ✅ dist/index.d.ts (3.27 kB) - Bundled TypeScript declarations
• ✅ Both with source maps
• ✅ No errors, no warnings

Recommendation

The issue title and description should perhaps be updated to reflect that this is actually a configuration compatibility issue rather than a fundamental bug. The error messages from tsdown could be improved to make this clearer to users.

For monorepo users: Ensure TypeScript paths use relative paths (starting with ./) and avoid using baseUrl when working with tsdown.

[ThePlenkov]

Keeping This Issue Open - Improved Error Messages Needed

While the root cause has been identified (see NX issue #32958), I believe this issue should remain open for tsdown to address error message clarity.

The Problem with Current Error Messages

The original error was extremely cryptic and misleading:

[UNRESOLVED_IMPORT] Error: Could not resolve './types.js' in ../types/src/index.d.ts
   ╭─[ ../types/src/index.d.ts:1:15 ]
   │
 1 │ export * from './types.js';
   │               ──────┬─────  
   │                     ╰─────── Module not found.

This error message:

1. Points to a phantom file (../types/src/index.d.ts) that doesn't exist
2. Shows wrong exports (config package exports instead of types package exports)
3. Gives no hint about the actual problem (tsconfig incompatibility)
4. Makes debugging nearly impossible without trial and error

How I Found the Solution

The only reason I discovered the root cause was by accidentally enabling the experimental tsgo option, which then showed the actual error:

TS5090: Non-relative paths are not allowed. Did you forget a leading './'?
TS5102: Option 'baseUrl' has been removed. Please remove it from your configuration.

Without tsgo, there was no way to know the real issue.

Proposed Improvement

When DTS generation fails, tsdown should:

1. Validate tsconfig compatibility before attempting DTS bundling
2. Show clear warnings about deprecated/incompatible TypeScript configuration:
   • Detect baseUrl usage and warn about deprecation
   • Detect non-relative paths and suggest adding ./ prefix
   • Validate path mappings point to valid locations
3. Provide actionable error messages instead of cryptic "Module not found" errors
4. Surface underlying TypeScript errors from the DTS generation process

Example of Better Error Message

Instead of:

[UNRESOLVED_IMPORT] Error: Could not resolve './types.js' in ../types/src/index.d.ts

Show:

[DTS_CONFIG_ERROR] Error: TypeScript configuration incompatibility detected

Your tsconfig.json uses 'baseUrl' with non-relative paths, which is deprecated
and incompatible with DTS generation:

  "baseUrl": ".",
  "paths": {
    "@anygpt/types": ["packages/types/src"]  // ❌ Non-relative path
  }

Recommended fix:
  1. Remove 'baseUrl' from tsconfig
  2. Make paths relative by adding './' prefix:
     "@anygpt/types": ["./packages/types/src"]  // ✅ Relative path

See: https://github.com/rolldown/tsdown/issues/523

Why This Matters

Many NX users (and potentially other monorepo users) will hit this exact issue. Without clear error messages, they'll waste hours debugging what appears to be a complex bundling problem when it's actually a simple configuration issue.

Request: Please keep this issue open to track improvements to error messages and configuration validation, even though the root cause has been identified.