ESM-only oidc-provider and NestJS

[Gamote]

First of all, amazing package! 💯 Huge thanks to all the contributors for your time put into this project. 🙏🏼

What is up?

As you all know since v8.x this package is delivered as ESM only. NestJS being a CommonJS only (at least for the foreseeable future).
I assume that there is no option for the package to also deliver CommonJS (?) so I had to find a solution. Solution that I want to share with you, hopping that it will help developers and/or maybe it can be improved.

---

Summary of the issue

• Nest doesn't support ESM (issue)
• oidc-provider is a full ESM package since version 8 (release)
• We don't want to migrate Nest to ESM, until it's officially supported

Read more about it:

• Add flag to not transpile dynamic import() when module is CommonJS microsoft/TypeScript#43329
• Support importing from pure ESM packages nestjs/nest#7021

Solution

The solution was to have the module asynchronously be imported. Then we created an injectable provider that will await the import of the oidc-provider. This is so we don't have be forced to await it down the line. For example if we want to use it in a constructor. Code:

// oidc-provider-module.ts
import { FactoryProvider } from '@nestjs/common';
// @ts-ignore
import type ESMProvider, { interactionPolicy, errors } from 'oidc-provider';

/**
 * We re-export the type so the consumer doesn't have to import it from the oidc-provider package and be forced to ignore the type error.
 */
export type Provider = ESMProvider;

/**
 * A type representing the actual provider class provided by the `oidc-provider` package and not the instance.
 */
export type ProviderClass = { new (...args: ConstructorParameters<typeof ESMProvider>): Provider };

/**
 * A type representing the `oidc-provider` module.
 * Useful when we pass the around as a parameter.
 */
export type OidcProviderModule = { Provider: ProviderClass, interactionPolicy: typeof interactionPolicy, errors: typeof errors };

/**
 * Dynamically imports a package. Useful when we want to import an ES module into CommonJS.
 *
 * **Note:** We couldn't use only `await import(packageName)` because it still throws the ESM error.
 * @see https://github.com/microsoft/TypeScript/issues/43329#issuecomment-811606238
 *
 * @param packageName
 */
const dynamicImport = async <ReturnType>(packageName: string): Promise<ReturnType> =>
  new Function(`return import('${packageName}')`)();

/**
 * The OIDC provider module token. It's used to inject the OIDC provider as a dependency like so:
 * ```ts
 * @Inject(OIDC_PROVIDER_MODULE) private readonly oidcProviderModule: OidcProviderModule
 * ```
 */
export const OIDC_PROVIDER_MODULE = 'OIDC_PROVIDER_MODULE';

/**
 * A factory provider that provides the OIDC provider module.
 */
export const oidcProviderModuleFactory = (): FactoryProvider => ({
  provide: OIDC_PROVIDER_MODULE,
  useFactory: async (): Promise<OidcProviderModule> => {
    const { default: ProviderClass, ...rest } = await dynamicImport<{ default: ProviderClass } & Omit<OidcProviderModule, 'Provider'>>(
      'oidc-provider',
    );

    return {
      Provider: ProviderClass,
      ...rest,
    };
  },
});

Ideally this whole wrapper is removed and we use the package directly.

Usage

1. Add the provider in the module

   // oidc.module.ts
   import { oidcProviderModuleFactory } from './oidc-provider-module';
   
   @Module({
     providers: [oidcProviderModuleFactory(), OidcService],
   })
   export class OidcModule {}

2. Use it in the service

   // oidc.service.ts
   import { OIDC_PROVIDER_MODULE, OidcProviderModule, Provider } from './oidc-provider-module';
   
   @Injectable()
   export class OidcService {
     private readonly oidc: Provider;
   
     constructor(@Inject(OIDC_PROVIDER_MODULE) private readonly opm: OidcProviderModule) {
       this.oidc = new opm.Provider('http://localhost:3000', {
         // the rest of your configuration...
       });
     }
   }

[natnt2000]

@Gamote how can I set it up with ExpressJS?
My project is using commonjs

[Gamote]

Convert the Express project if possible,or use a bundler. If that is not possible, then create a similar functionality that "initialise" the library (a singleton class can be used for example) and delay the "listen" and any other dependent logic until the module is initialised.

[panva]

I assume that there is no option for the package to also deliver CommonJS (?) so I had to find a solution.

There's no going back to CJS for this module.

That being said, be on a lookout for nodejs/node#51977 to land in the supported Node.js release lines. With --experimental-require-module, and later on when it goes out of experimental, you'll be able to require(esm) so long as the module itself doesn't use any top level await, which I don't ever plan on doing with my modules.

Refs: https://joyeecheung.github.io/blog/2024/03/18/require-esm-in-node-js/

[JonasDoe]

Hm, I shrunk my tsconfig.json until that remained:

{
  "compilerOptions": {
    "module": "commonjs",
    "rootDir": "src",
    "outDir": "dist",
    "target": "ES2020",
    "skipLibCheck": true,
    "esModuleInterop": true
  },
  "exclude": ["node_modules"],
  "include": ["src/**/*"]
}

and I'm running tsc && node --experimental-require-module dist/serve.js, so there's not much place for fancy magic inbetween. My tsc version is 5.4.5 - I could downgrade that one and try again if you feel it is the issue.

But anyway, shouldn't my manual edit to oidc_provider_2.default.default.Provider(...) work with that double defaulting? Just wondering whether this wrapping is really the root of all problems, and not just an additional one.

[panva]

If you disable esModuleInterop it works as expected. This might as well just be typescript not ready for require(esm) in that it's trying to do something it shouldn't anymore. I suggest you open an issue in typescript.

[JonasDoe]

Alright, will do that. Thanks for your patience!

[JonasDoe]

Update - seems like the ball is in Node's field: microsoft/TypeScript#58341. So lets hope this experimental feature will make it rather soon!

[panva]

Node.js v23 will ship with unflagged require(esm) so oidc-provider will be requireable without any wrappers. This capability will eventually trickle down to LTS Node.js 22.x

[ArturChe]

Hi @Gamote I tried to repeat your solution, but I got an error:

Debugger listening on ws://0.0.0.0:9229/e48d22b0-28ce-4aaa-be5c-c69a4e96571e
2024-07-23T05:37:12.161370664Z For help, see: https://nodejs.org/en/docs/inspector
2024-07-23T05:37:13.095780795Z /usr/src/app/js/node_modules/nest-oidc-provider/dist/oidc.service.js:42
2024-07-23T05:37:13.095804925Z const oidc = __importStar(require("oidc-provider"));
2024-07-23T05:37:13.095807145Z                           ^
2024-07-23T05:37:13.095808812Z 
2024-07-23T05:37:13.095810395Z Error [ERR_REQUIRE_ESM]: require() of ES Module /usr/src/app/js/node_modules/oidc-provider/lib/index.js from /usr/src/app/js/node_modules/nest-oidc-provider/dist/oidc.service.js not supported.
2024-07-23T05:37:13.095812300Z Instead change the require of index.js in /usr/src/app/js/node_modules/nest-oidc-provider/dist/oidc.service.js to a dynamic import() which is available in all CommonJS modules.
2024-07-23T05:37:13.095814238Z     at Object.<anonymous> (/usr/src/app/js/node_modules/nest-oidc-provider/dist/oidc.service.js:42:27) {
2024-07-23T05:37:13.095816234Z   code: 'ERR_REQUIRE_ESM'
2024-07-23T05:37:13.095817763Z }
2024-07-23T05:37:13.095819226Z 
2024-07-23T05:37:13.095820657Z 

Node.js v20.11.1

[adrianbrs]

Hello everyone!

I’d like to share that you can use the nest-oidc-provider package to integrate oidc-provider with Nest. Version 2.0.0 now supports the ESM-only version of oidc-provider using a similar approach to what was described above.

Hope this helps!

[panva]

Node.js v23 will ship with unflagged require(esm) so oidc-provider will be requireable without any wrappers. This capability will eventually trickle down to LTS Node.js 22.x

[adrianbrs]

Hi @panva! Yeah, that's great news!

In the Nest ecosystem, it's quite common to use 'wrappers' for integrating with other libraries (Nest itself has many official ones). If you take a closer look at the library, you'll notice it offers more than just ESM support. Both libraries still need to be installed, and nest-oidc-provider mainly simplifies configuration and handles dependency injection through decorators, so I believe nest-oidc-provider is still a valid and useful option.

Let me know if there's anything I can do to improve this integration, and thanks for creating such an awesome lib!