Fixing Zod-OpenAPI With TypeScript's Bundler Module Resolution

Are you wrestling with TypeScript errors when using zod-openapi in your Next.js 13+ project? Specifically, are you encountering the dreaded "Could not find a declaration file for module" error? If so, you're not alone. This article dives into the root cause of this issue, providing a clear explanation and, more importantly, a straightforward solution to get your project back on track. We'll explore why the default configuration of zod-openapi clashes with TypeScript's moduleResolution: "bundler" setting and how a simple adjustment can resolve the problem. Let's get started!

The Problem: TypeScript's Missing Declaration Files

When developing with TypeScript, especially in modern frameworks like Next.js, the type system is your best friend. It helps catch errors early, provides excellent code completion, and makes your code more maintainable. However, when TypeScript can't find the necessary type declarations for a module, it throws an error. This is precisely the issue that arises when using zod-openapi with moduleResolution: "bundler". The error message looks something like this:

error TS7016: Could not find a declaration file for module 'zod-openapi'. 'node_modules/zod-openapi/dist/index.js' implicitly has an 'any' type.

This error indicates that TypeScript is unable to locate the .d.ts files that describe the types for zod-openapi. Without these declaration files, TypeScript treats the module as having an any type, which defeats the purpose of using a type-safe language. The moduleResolution: "bundler" setting is the recommended setting for modern TypeScript projects, especially those using bundlers like Webpack or esbuild, which are common in Next.js applications. This setting instructs TypeScript on how to resolve module imports, and it does so by strictly adhering to the exports field in the package.json file of the imported module. Therefore, the way zod-openapi specifies its export conditions directly impacts its compatibility with projects employing moduleResolution: "bundler".

The Cause: Examining the package.json Exports

The root of the problem lies within the package.json file of the zod-openapi package. Specifically, the exports field dictates how the module's files are exposed to other modules. In the case of zod-openapi (version 5.4.4, as of the writing of this article), the exports field looks something like this:

"exports": {
  ".": {
    "import": "./dist/index.js",
    "require": "./dist/index.cjs"
  }
}

This configuration tells TypeScript and other module loaders that when a module imports zod-openapi (using the top-level entry point .), it should use ./dist/index.js for import statements and ./dist/index.cjs for require statements. While this works well for resolving the JavaScript files, it doesn't specify how to locate the type definition files (.d.ts). Although the package does have a types field at the root level of package.json that points to the declaration file (e.g., `