HIGH: TypeScript Module Resolution Issue with Radix UI Dependencies in pnpm Projects #46
Description
TypeScript Module Resolution Issue with Radix UI Dependencies in pnpm Projects
Severity: HIGH - Blocks TypeScript development for pnpm users
Package Version: 0.4.3
Environment: pnpm + TypeScript projects
Root Cause Identified
After extensive investigation, we've identified the exact root cause of the Select component import issues:
The Problem
pnpm's symlink structure + TypeScript module resolution = broken Radix UI dependency resolution
Technical Details
-
ui-kit declares Radix UI imports in TypeScript declarations:
import * as SelectPrimitive from '@radix-ui/react-select'; // Line 6 in dist/index.d.ts
-
pnpm installs dependencies in cache structure:
node_modules/.pnpm/@radix-ui+react-select@2.2.5_...../node_modules/@radix-ui/react-select -
TypeScript cannot resolve the import:
$ echo 'import * as SelectPrimitive from "@radix-ui/react-select";' > test.ts $ npx tsc --noEmit test.ts # ERROR: Cannot find module '@radix-ui/react-select' or its corresponding type declarations.
-
This breaks Select component's TypeScript declarations:
// This fails in TypeScript but works at runtime import { Select } from '@etherisc/ui-kit';
Evidence
All Radix UI Dependencies Affected
# Testing individual Radix UI imports
echo 'import * as SelectPrimitive from "@radix-ui/react-select";' > test.ts
npx tsc --noEmit test.ts
# ❌ ERROR: Cannot find module '@radix-ui/react-select'
echo 'import * as CheckboxPrimitive from "@radix-ui/react-checkbox";' > test.ts
npx tsc --noEmit test.ts
# ❌ ERROR: Cannot find module '@radix-ui/react-checkbox'Why Only Select Appears Broken
- Select has complex ForwardRef types depending on
SelectPrimitivethat must resolve at import time - Other components either don't use Radix UI or use simpler declaration patterns
- Runtime works because Node.js resolves pnpm symlinks correctly
- Build with
--skipLibCheckworks because it skips the broken type resolution
Impact Scope
- All pnpm projects using ui-kit cannot import Select with TypeScript
- npm/yarn projects may not be affected (different module resolution)
- Runtime functionality works perfectly
- Build systems with skipLibCheck work fine
Solutions
Option 1: Proper Peer Dependencies (Recommended)
Declare Radix UI dependencies as peer dependencies so users install them directly:
{
"peerDependencies": {
"@radix-ui/react-select": "^2.2.4",
"@radix-ui/react-checkbox": "^1.3.1",
"@radix-ui/react-dialog": "^1.1.14",
// ... other Radix UI deps used in declarations
}
}Option 2: Bundle Dependencies Properly
Bundle Radix UI dependencies so they don't need external resolution:
- Use proper bundling that doesn't leak internal import paths
- Ensure TypeScript declarations don't reference external modules
Option 3: Fix Module Resolution
Update TypeScript configuration in ui-kit build to handle pnpm symlinks correctly.
Current Project Impact
We're using this workaround in our pnpm project:
import { Select as UISelect } from '@etherisc/ui-kit';
// Works around the import resolution issueEnvironment Details
- Package Manager: pnpm v10.11.1
- TypeScript: Various versions affected
- Node.js: v20.19.2
- OS: Linux/Docker environment
This issue affects any TypeScript project using pnpm with @etherisc/ui-kit v0.4.3.
Priority: HIGH - This blocks TypeScript development for a significant portion of users (pnpm adoption is growing rapidly).