Why Wagmi and Viem Break Your TypeScript Config (and How to Fix It)

--

Stop fighting errors in node_modules and align your Vite project with the latest Wagmi standards for v2 and v3.

Press enter or click to view image in full size

You run npm install wagmi viem. Before you’ve written a single line of application code, TypeScript is already shouting at you.

The errors point to files you didn’t write and can’t edit: wagmi/dist/index.d.ts or viem/_types/utils/.... You see cryptic messages like Type 'undefined' is not assignable or conflicts regarding exactOptionalPropertyTypes.

This is a tsconfig problem, not a wagmi bug. Wagmi and Viem are built to pass under strict settings and modern module resolution. If your configuration hasn’t caught up to TypeScript 5.0+ standards, you’ll face constant friction. Here are the three non-negotiable fixes for both wagmi v2 and v3.

1. Set moduleResolution to "bundler"

Vite uses esbuild for bundling. It follows modern package.json export maps and doesn't require explicit file extensions. TypeScript’s older node resolution mode doesn't understand this, leading to disagreements on how types are found.

The Fix: Set your moduleResolution to "bundler". This tells TypeScript to mimic the way Vite (and other modern bundlers) resolves files.

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "bundler"
  }
}

Note: This requires TypeScript 5.0+. If you get an error saying it’s not supported, ensure your module is set to ESNext or Preserve.

2. Enable strict: true

This is the most common point of failure. Wagmi uses advanced type inference that relies on strict null checks and strict function types. If strict is false, the inference engine breaks, causing those "undefined is not assignable" errors inside the library's internal declaration files.

{
  "compilerOptions": {
    "strict": true
  }
}

If enabling this surfaces errors in your existing code, fix your code. The errors in node_modules are just collateral damage from a loose configuration.

Pro-Tip: If your project is too large to flip the strict switch overnight, you can surgically enable strictNullChecks: true and strictFunctionTypes: true to satisfy Wagmi's inference engine while you incrementally migrate the rest of the codebase.

3. The skipLibCheck Trade-off

Even with the settings above, third-party packages (outside of Wagmi) might ship broken or incompatible types. To prevent these from halting your build, use:

{
  "compilerOptions": {
    "skipLibCheck": true
  }
}

Why do this? It tells TypeScript to skip checking .d.ts files globally. It makes builds faster and suppresses noise. While it technically reduces type safety for libraries, it is the industry standard for Vite projects. Fix moduleResolution and strict first to solve the logic; use skipLibCheck only to suppress remaining third-party noise.

The Complete “Golden” tsconfig.json

If you are starting a new project or fixing an old one, here is the verified configuration for Vite + React + Wagmi:

{
  "compilerOptions": {
    "target": "ES2020",
    "useDefineForClassFields": true,
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "skipLibCheck": true,
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "moduleDetection": "force",
    "noEmit": true,
    "jsx": "react-jsx",
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true
  },
  "include": ["src"]
}

Version Specifics: Wagmi v2 vs. v3

The tsconfig remains the same, but your TypeScript version matters immensely. Wagmi introduces breaking changes in minor releases because TypeScript itself doesn't follow strict SemVer.

Wagmi v2

• Install: npm install wagmi@2 viem @tanstack/react-query
• Requirement: TypeScript ≥ 5.0.4

Wagmi v3 (Current)

• Install: npm install wagmi viem @tanstack/react-query
• Requirement: TypeScript ≥ 5.7.3

Pro Tip: Always pin your TypeScript version in devDependencies to avoid silent breaks during CI/CD.
Example: "typescript": "5.7.3"

A Note on Create React App (CRA)

If you are seeing these errors in a CRA project, the bad news is there is no simple fix. CRA is locked to TypeScript 4.x, which cannot satisfy Wagmi’s requirements.

Passing --force or --legacy-peer-deps will install the library, but your types will be broken. The only real solution is to migrate to Vite.

Final Checklist

1. Check your TS version: npx tsc --version
2. Set moduleResolution: "bundler"
3. Set strict: true
4. If using CRA, start the migration to Vite today.