Superjson Upgrade Troubles: Fixing CJS Issues

Hey everyone! 👋 Have you ever run into a situation where a simple upgrade completely throws your project for a loop? Well, that’s exactly what happened to me when I upgraded Superjson. I'm going to walk you through the issue, what caused it, and most importantly, how to fix it. Let's dive in!

The Problem: TypeScript Errors After Upgrading Superjson

Upgrading Superjson from version 2.2.2 to 2.2.3 seemed straightforward enough, but after the update, my TypeScript compiler started throwing errors. The error message looked something like this:

Error: *******/utils.ts(2,23): error TS7016: Could not find a declaration file for module 'superjson'. '/home/runner/work/*******/node_modules/superjson/dist-cjs/index.cjs' implicitly has an 'any' type.
  Try `npm i --save-dev @types/superjson` if it exists or add a new declaration (.d.ts) file containing `declare module 'superjson';`

This error essentially meant that TypeScript couldn't find the necessary type definitions for the superjson module when it was trying to use the CommonJS (CJS) version. The compiler was falling back to the any type, which meant a loss of type safety and potentially runtime errors. Not ideal!

Understanding the Error

To really understand what's happening, let’s break down the error message. TypeScript uses declaration files (.d.ts files) to understand the shape and types of external modules. These files tell the compiler about the functions, classes, and variables that a module exports. When TypeScript couldn't find a .d.ts file for superjson in the correct location (specifically, the dist-cjs directory for the CJS version), it threw this error. The implicitly has an 'any' type part is TypeScript's way of saying, "I don't know what this module exports, so I'm just going to assume it's all any." This is a problem because it bypasses the type checking that TypeScript is designed to provide.

The Root Cause

After digging a bit, I suspected that the changes introduced in pull request #301 might be the culprit. This is because the changes likely involved adjustments to how Superjson handled its distribution, potentially affecting the availability or location of the type definition files for CJS modules. It's a classic case of a seemingly minor change having a cascading effect on the build process. Figuring out the exact cause often involves looking at the changes made in the specific pull request and how they impact the project's structure and the way the module is built and distributed. In this case, the changes may have inadvertently altered the paths or configurations used during the build process, leading to the type definition files not being correctly placed or referenced for CJS modules.

The Solution: A Quick Fix and Workarounds

Fortunately, there's a relatively simple workaround that can help you get back on track while a more permanent solution is found.

The Temporary Fix

The quickest fix that I found was to copy the declaration file. You can simply copy superjson/dist-cjs/index.d.ts to superjson/dist-cjs/index.d.cts. This provides TypeScript with the type definitions it needs to understand the CJS module. Here’s a more detailed breakdown:

1. Locate the original declaration file: Inside your node_modules directory, navigate to superjson/dist-cjs/index.d.ts. This file contains the type declarations for the superjson module. It tells TypeScript about the functions, classes, and variables that the module exports, allowing it to perform type checking. Because index.d.ts is the type definition file for the module, TypeScript uses it to understand the structure and types of the superjson module. If this file is missing or not properly linked, TypeScript will not be able to correctly check the types, leading to errors.
2. Copy the file: Copy the index.d.ts file. You can do this manually using your file manager or use a command-line utility. The exact method will depend on your operating system and preferred tools.
3. Create a new file with a different extension: Paste the copied content into a new file named index.d.cts in the same directory (superjson/dist-cjs/). The .cts extension signifies a TypeScript declaration file for a CommonJS module.
4. Save the file: Save the new index.d.cts file.

By creating a .cts file, you are essentially telling TypeScript that the definitions apply to CommonJS modules. This helps the compiler correctly resolve the types and avoid the