Union Type Complexity Error (ts2590)

Problem:
When using Chakra UI's Button component (or similar), TypeScript reports the error:

Expression produces a union type that is too complex to represent. ts(2590)

Example triggering code:

import { Button } from "@chakra-ui/react";

function Page() {
  return <Button onClick={(event) => {}}>Text</Button>;
}

This occurs when TypeScript encounters union types exceeding its internal complexity limits, often due to configuration conflicts or version mismatches in tooling.

---

Solutions

1. Resolve TypeScript Version Conflicts in VS Code

VS Code may use its built-in TypeScript version instead of your project's version. Select the workspace TypeScript version:

GUI Method:

1. Click the TypeScript version in VS Code's status bar:
   
2. Select "Use Workspace Version"
   

Configure via settings.json:

{
  "typescript.enablePromptUseWorkspaceTsdk": true,
  "typescript.tsdk": "node_modules/typescript/lib"
}

TIP

After configuring, restart VS Code. If the prompt doesn't appear:

1. Verify typescript is in your package.json
2. Run npm install or npm clean-install

---

2. Modify tsconfig.json for Emotion.js

If using Emotion.js in an NX or similar setup, remove jsxImportSource and add Emotion types:

{
  "compilerOptions": {
-   "jsxImportSource": "@emotion/react",
+   "types": ["@emotion/react/types/css-prop"]
  }
}

WARNING

Clear caches after changes:

rm -rf node_modules dist build .cache
npm install

---

3. Downgrade TypeScript (Temporary Fix)

Use TypeScript v4.9.5 if you recently upgraded to v5.x:

npm install typescript@4.9.5
# or
yarn add typescript@4.9.5

Recommendation

Only use this as a last resort. Test newer TypeScript and library versions afterward, as Chakra UI updates may resolve the issue.

---

4. Upgrade Chakra UI

Update to the latest @chakra-ui/react patch version (fixes type refinements):

npm install @chakra-ui/react@latest
# Specific working version:
npm install @chakra-ui/react@2.5.5

---

5. Avoid Suboptimal Workarounds

❌ Don't suppress errors indiscriminately:
Adding // @ts-ignore ignores underlying issues and risks runtime failures.

❌ Don't disable strict mode:
Removing "strict": true from tsconfig.json degrades type safety.

⛔ Unreliable fixes:
Adding the css prop (<Button css=""...) occasionally works accidentally but isn't a solution.

---

Summary of Recommended Steps

1. Verify VS Code uses your project's TypeScript version (Solution 1)
2. Update tsconfig.json if using Emotion.js (Solution 2)
3. Upgrade Chakra UI to the latest version (Solution 4)
4. Reinstall dependencies and restart your editor after changes

Cause	Fix Priority	Effectiveness
VS Code TS Version	⭐⭐⭐	High
Emotion.js Config	⭐⭐⭐	High
Chakra UI Version	⭐⭐	Moderate
TypeScript Compatibility	⭐	Short-term

For ongoing issues, consult the Chakra UI GitHub discussion.