Enable ESM interoperability by default.

[codiophile]

Is there an existing issue that is already proposing this?

• I have searched the existing issues

Is your feature request related to a problem? Please describe it

I was trying to use Octokit in a NestJS project, but the import didn't work properly. Octokit ended up just being an alias for any, which made the linter really unhappy and the auto-completion non-existent. I raised an issue with Octokit, because I thought they should make sure it works with CommonJS and I got an incredibly helpful response: octokit/octokit.js#2865

Describe the solution you'd like

Sine TypeScript 5.8, there is full interoperability between CommonJS and ESM. All you have to do is configure it. I changed my tsconfig.json to the following:

{
  "compilerOptions": {
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "resolvePackageJsonExports": true,
    "esModuleInterop": true,
    "declaration": true,
    "removeComments": true,
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
    "allowSyntheticDefaultImports": true,
    "target": "ES2023",
    "sourceMap": true,
    "outDir": "./dist",
    "baseUrl": "./",
    "incremental": true,
    "skipLibCheck": true,
    "strictNullChecks": true,
    "forceConsistentCasingInFileNames": true,
    "noImplicitAny": false,
    "strictBindCallApply": false,
    "noFallthroughCasesInSwitch": false
  }
}

It just works, and I don't see why it shouldn't be configured by default. Importing ESM has been such a pain for such a long time and there's now a solution that makes it completely seamless. I don't see why we shouldn't adopt it in NestJS.

Teachability, documentation, adoption, migration strategy

Assuming that this works with every part of NestJS (I've only tested the subset of modules I use in my project), this should be completely transparent to the end user. All the code they have today should keep working and if they ever try to import an ES module, it will just work and they don't have to worry about it.

I think this is a quick win and the main effort is to test it, to make sure that it works with every part of NestJS. In theory, it should, but I haven't tried it and I'm not an expert, so it seems like a reasonable thing to verify.

What is the motivation / use case for changing the behavior?

There's no noticeable change in behaviour. The only noticeable difference is that you can import ES modules and they just work as expected. It's purely an improvement, as far as I'm aware. At least in my project, it seems to work perfectly.

[codiophile]

It seems like I was right, in that testing would be the main challenge. jest is refusing to import ESM. It throws a warning that can be fixed by adding the following to tsconfig.json:

"isolatedModules": true

It seems to be working fine with the rest of the code, so I'm keeping it.

Unfortunately, the only solution I've found to be able to test files that import ESM, is to mock the module:

jest.mock('octokit', () => ({}));

Just add that line to the top of the file, before the imports, and jest is no longer failing to import ESM, as it doesn't even try.

Another minor thing I had to do was to change the supertest import:

import request from 'supertest';

To me, all of this is acceptable, since I do not want my tests to be talking to GitHub anyway. It's a bit of a shame that it's not possible to write full e2e tests with GitHub integration, but I don't have any such tests anyway, so I wouldn't consider it a blocker. Also, ESM interoperability is pretty new, so I have great hope that it will be fully supported in jest as well.

[kamilmysliwiec]

Out of curiosity: have you tried with Jest v30?

[codiophile]

@kamilmysliwiec I hadn't, but since you asked, I tried it. It makes no difference. I would assume that it is ts-jest that needs to fix this issue. It seems like it doesn't transpile ESM imports to use require, like typescript 5.8 does.

[codiophile]

Actually, just noticed that the problem is inside Octokit itself:

node_modules/octokit/dist-bundle/index.js:2
import { Octokit as OctokitCore } from "@octokit/core";
^^^^^^

SyntaxError: Cannot use import statement outside a module

So it seems like ts-jest is transpiling the import in my code, but not the import inside the ES module.