NX-generated tsconfig uses deprecated baseUrl causing incompatibility with modern bundlers

[ThePlenkov]

NX-generated tsconfig uses deprecated baseUrl causing incompatibility with modern bundlers

Current Behavior

NX generates tsconfig.base.json with baseUrl: "." and non-relative paths in the paths mapping:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@myorg/lib1": ["packages/lib1/src"],
      "@myorg/lib2": ["packages/lib2/src"]
    }
  }
}

This configuration causes failures with modern TypeScript tooling that follows newer TypeScript standards, specifically:

• tsdown with tsgo option (TypeScript isolated declarations)
• Potentially other bundlers using TypeScript's isolated declarations feature

Error Messages

When using modern bundlers with this configuration:

TS5090: Non-relative paths are not allowed. Did you forget a leading './'?

TS5102: Option 'baseUrl' has been removed. Please remove it from your configuration.
  Use '"paths": {"*": ["../../*"]}' instead.

Expected Behavior

NX should generate tsconfig with relative paths that are compatible with modern TypeScript tooling:

{
  "compilerOptions": {
    "paths": {
      "@myorg/lib1": ["./packages/lib1/src"],
      "@myorg/lib2": ["./packages/lib2/src"]
    }
  }
}

Steps to Reproduce

1. Create a new NX workspace with TypeScript libraries
2. Install and configure tsdown for building a library
3. Enable DTS generation (auto-detected or explicit)
4. Run build

Example tsdown.config.ts:

import { defineConfig } from 'tsdown';

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

Build fails with:

ERROR: Build failed with errors:
[UNRESOLVED_IMPORT] Error: Could not resolve './types.js' in ../types/src/index.d.ts

Workaround

Manually update tsconfig.base.json:

{
  "compilerOptions": {
-   "baseUrl": ".",
    "paths": {
-     "@myorg/lib1": ["packages/lib1/src"],
-     "@myorg/lib2": ["packages/lib2/src"]
+     "@myorg/lib1": ["./packages/lib1/src"],
+     "@myorg/lib2": ["./packages/lib2/src"]
    }
  }
}

After this change, builds work correctly with modern bundlers.

Context

Why This Matters

1. TypeScript Evolution: The TypeScript team has deprecated baseUrl in favor of relative paths
2. Modern Tooling: Tools using TypeScript's isolated declarations (like tsdown's tsgo) require the newer format
3. Future Compatibility: As more tools adopt isolated declarations, this will become a broader issue

Related Issues

• tsdown issue #523 - Initially thought to be a tsdown bug, but root cause is NX's tsconfig format
• NX issue #11374 - Earlier discussion about baseUrl/paths usage

Proposed Solution

1. Update NX generators to create tsconfig files with relative paths (using ./ prefix) and without baseUrl
2. Provide migration for existing workspaces (perhaps an nx migrate command)
3. Update documentation to reflect this change and explain the reasoning
4. Add warning when detecting the old format to guide users to update

Environment

• NX Version: (affects all versions using current tsconfig template)
• Node Version: v20+
• Package Manager: npm/pnpm/yarn
• Operating System: All platforms
• Affected Bundlers: tsdown (confirmed), potentially others using isolated declarations

Additional Information

This is not just a tsdown-specific issue. As TypeScript evolves and more tools adopt isolated declarations and modern TypeScript features, the current NX-generated tsconfig format will cause increasing compatibility problems.

The fix is straightforward (add ./ prefix to paths, remove baseUrl) and maintains backward compatibility with existing TypeScript compilation while enabling compatibility with modern tooling.

[atsjo]

The workaround doesn't work in my monorepo when building libs with @nx/js:tsc, and referencing other local libs...

[gabrielbryk]

Same issue here, I got it when I switched to tsgo with nx 22.3

[C5G6M7]

Same issue here. I cannot use baseUrl but @nx/js:tsc breaks without it, however I was able to get it to work by using nx-run-commands instead like this:

   "build": {
      "executor": "nx:run-commands",
      "outputs": ["{projectRoot}/dist"],
      "options": {
        "commands": ["tsc -p {projectRoot}/tsconfig.lib.json"],
        "cwd": "{workspaceRoot}"
      },
      "dependsOn": ["^build"]
    }

[xiongemi]

might be fixed in #33332 or #34453?

[atsjo]

Using nx 22.5.4 with latest angular in a monorepo I tested out ts 6.0.1-rc.

If adding ./ to paths in tsconfig.base.json and removing baseUrl, vscode is able to resolve local lib references and also the native angular builder works fine... But @nx/js:tsc builder fails with TS2307: Cannot find module..., however @C5G6M7 workaround above can fix that, but then ending up with similar problems for @nx/angular:ng-packagr-lite. I could probably replace that with the native angular builder, and make it work, but then everything would need to be built from source, and not incrementally as I do via nx today...

Hoping fixing this will be prioritized sooner rather than later, as angular already supports ts 6, and I'm guessing many more than me would like to test out tsgo.... (ts 6 is scheduled for release in 10 days...)

[JonathanWilbur]

This is affecting me as of Nx version 22.6.1 and I did prepend the baseUrl to the paths. Even when I remove paths completely, I am still getting this error. Is Nx injecting a path into there?

[JonathanWilbur]

This looks like it could be a problem:

nx/packages/js/src/utils/buildable-libs-utils.spec.ts

Lines 33 to 47 in d047b81

	it('should replace paths', () => {
	const paths: Record<string, string[]> = {
	'@proj/lib': ['libs/lib/src/index.ts'],
	'@proj/lib/sub': ['libs/lib/sub/src/index.ts'],
	};
	updatePaths(deps, paths);
	expect(paths).toEqual({
	'@proj/lib': ['dist/libs/lib'],
	'@proj/lib/sub': [
	'dist/libs/lib/sub',
	'dist/libs/lib/sub/src/index',
	'dist/libs/lib/sub/src/index.ts',
	],
	});
	});