new FAQ page: How to use ESM-only packages in Nestjs CJS

[micalevisk]

From time to time people ask on our Discord community about it even tho this isn't exactly a nestjs issue. So I think that it would be good to have this mentioned somewhere in the docs site until we address the PR nestjs/nest#8736
If we conclude that we won't add this to the docs, I'll publish an article at https://dev.to

typescript users may face several issues when trying to use the import() expression to load ESM-only packages in a CommonJS project.

example

In a default standard nestjs app (typescript) we just can't do import superjson from 'superjson';:

const superjson_1 = __importDefault(require("superjson"));
                                    ^

Error [ERR_REQUIRE_ESM]: require() of ES Module /tmp/nestjs-app/node_modules/superjson/dist/index.js from /tmp/nestjs-app/dist/src/app.module.js not supported.
Instead change the require of index.js in /tmp/nestjs-app/dist/src/app.module.js to a dynamic import() which is available in all CommonJS modules.
    at Object.<anonymous> (/tmp/nestjs-app/dist/src/app.module.js:17:37) {
  code: 'ERR_REQUIRE_ESM'
}

the reason is well explained in this StackOverflow answer: https://stackoverflow.com/a/75287028

solution

As mentioned in SO, we can address this is three ways:

1. changing the moduleResolution and module in our tsconfig file so that import() won't be translated to require
2. use a helper eval-like function to prevents typescript from translating import into require
3. use the --experimental-require-module NodeJS's flag

And the docs we must show both of them because sometimes we can't change the module entry.

Another issue is that the docs should clarify is that depending on the package being loaded we must access the default property (more on this bellow).

We should also double-check if those solutions works for Jest/Vitest -- specially regarding mocking features

code snippets

I'm not sure about the best way to show-off the solutions to this yet but I think that we should avoid abstractions so the dev can understand the bare bones and write their own.

Working examples of the approach (1):

1. without NestJS stuff:

import { Module } from '@nestjs/common';

@Module({})
export class AppModule {
  async onModuleInit() {
    const superjson = await import('superjson');
    const jsonString = superjson.stringify({ date: new Date(0) });
    console.log(jsonString)
    
    const delay = await import('delay').then(loadedModule => loadedModule.default);
    await delay(1000)
  }
}

2. Using providers

import { Inject, Module } from '@nestjs/common';

@Module({
  providers: [
    {
      provide: 'package:delay',
      useFactory: () => import('delay').then(loadedModule => loadedModule.default),
    },
    {
      provide: 'package:superjson',
      useFactory: () => import('superjson'),
    },
  ]
})
export class AppModule {
  @Inject('package:delay')
  private readonly delay: typeof import('delay', { with: { 'resolution-mode': 'import' } }).default

  @Inject('package:superjson')
  private readonly superjson: typeof import('superjson', { with: {'resolution-mode': 'import'} })

  async onModuleInit() {
    const jsonString = this.superjson.stringify({ date: new Date(0) });
    console.log(jsonString)

    console.time('>')
    await this.delay(1000)
    console.timeEnd('>')
  }
}

Working example of the approach (2):

import { Inject, Module } from '@nestjs/common';

export const importPackage = async (packageName: string) =>
  new Function(`return import('${packageName}')`)()
    .then(loadedModule => loadedModule['default'] ?? loadedModule);

@Module({
  providers: [
    {
      provide: 'package:delay',
      useFactory: () => importPackage('delay'),
    },
    {
      provide: 'package:superjson',
      useFactory: () => importPackage('superjson'),
    },
  ]
})
export class AppModule {
  @Inject('package:delay')
  private readonly delay: typeof import('delay').default;

  @Inject('package:superjson')
  private readonly superjson: typeof import('superjson');

    async onModuleInit() {
    const jsonString = this.superjson.stringify({ date: new Date(0) });
    console.log(jsonString)

    console.time('>')
    await this.delay(1000)
    console.timeEnd('>')
  }
}

[kamilmysliwiec]

Would you like to create a PR for this?

[Kimblis]

Hey, I tried to implement this, but still get an error:

SUPERJSON_PROVIDER is just a constant (a name)

[micalevisk]

@Kimblis looks like your tsconfig doesn't have the expected moduleResolution value. Check out the StackOverflow answer

[codiophile]

I recently spent a lot of effort trying to use an ES module in a NestJS application. This would have saved me a bunch of time. One thing I would add is that Jest doesn't seem to work with dynamic imports. In my case, I didn't want to test that dependency anyway, so I'm using a mock in its place, but I'm sure others will face situations where their code is working, but they can't test it, because the dynamic import crashes Jest. I don't know what the solution is, but if possible, I think it would be good to add advice on how to deal with this in Jest.

[kamilmysliwiec]

Should we mention that https://x.com/JoyeeCheung/status/1839312043490578562 as well?

[Duske]

We faced the same issue and decided to upgrade the entire toolchain using swc, esm and vitest like in https://github.com/AlbertHernandez/nestjs-service-template. Surely not a silver bullet, but that options also exists and is still using nestjs tooling (swc, vitest).

[CatsMiaow]

ESM modules can now be imported from CommonJS projects using Node.js v20.19.0 or v22.12.0 or later and TypeScript v5.8 or later.

• require(esm) is now enabled by default
  • https://nodejs.org/ko/blog/release/v20.19.0
  • https://nodejs.org/en/blog/release/v22.12.0
• Support for require() of ECMAScript Modules in --module nodenext

And modify tsconfig.json.

{
  "compilerOptions": {
    // ...
    "module": "nodenext",
    "moduleResolution": "node16", // or nodenext
    // ...
  }
}

I also think that NestJS can be generally used in ESM projects, except for special cases.

CatsMiaow/nestjs-project-performance#3