Poor CommonJS experience

[claytongulick]

Describe the bug

Many projects don't have the option of switching wholesale over to ESM, and must use CommonJS. This will probably be true for the foreseeable future, as CommonJS will be here to stay for at least five years.

It's pretty difficult to tease out how to use this package with CommonJS, there are no docs or mention of it anywhere.

The best I can come up with to make it work is something like:

const module = await import('@keycloak/keycloak-admin-client');
const KcAdminClient = module.default.default;

I was only able to figure this out after putting breakpoints on and inspecting the module - it's strange to have to do .default.default

Is there a way to improve the developer experience with CommonJS?

Version

18.0.0

Expected behavior

No response

Actual behavior

No response

How to Reproduce?

No response

Anything else?

No response

[jonkoops]

We are currently compiling this package in the CommonJS format, the quirkiness we are seeing here is a side-effect of the TypeScript compiler. Now that Node.js 12 is no longer supported we intend to compile to ESM instead.

There are no intentions to have this package contain both ESM and CommonJS entry points and we'd rather opt for a pure ESM package instead. Node.js provides interoperability between these two so that it should 'just work' so I expect this will improve the developer experience.

[jonkoops]

Closing this as we landed pure ES module support in #381.

[alexagc]

@jonkoops, i would reconsider the distribution of commonjs module(following this rules https://nodejs.org/api/esm.html#esm_commonjs_namespaces), if only ships ESM modules this project force to move all code database of project to use ESM (or transpile code), this, even now, its not clear in nodejs core maintainers because commonjs its not going to be deprecate in a future and a large number of packages are still only in commonjs. Here its the personal recommendation of a nodejs maintainer (Matteo collina) about this topic:

nodejs/node#33954 (comment)

[claytongulick]

@jonkoops, i would reconsider the distribution of commonjs module(following this rules https://nodejs.org/api/esm.html#esm_commonjs_namespaces), if only ships ESM modules this project force to move all code database of project to use ESM (or transpile code), this, even now, its not clear in nodejs core maintainers because commonjs its not going to be deprecate in a future and a large number of packages are still only in commonjs. Here its the personal recommendation of a nodejs maintainer (Matteo collina) about this topic:

nodejs/node#33954 (comment)

I agree, our solution for now is to move away from keycloak due to the response to this ticket and some other technical limitations.

I was disappointed with the response, it seemed needlessly strict, especially since packaging for both esm and cjs is pretty simple and a common practice.

[jonkoops]

especially since packaging for both esm and cjs is pretty simple and a common practice.

No, it's not.

if only ships ESM modules this project force to move all code database of project to use ESM

It doesn't force you to do this, you can still import ES modules from CommonJS. However there are caveats. You'll have to use the dynamic import(), and since top-level await is not supported in CommonJS you'll have to wrap your code in an IIFE.

You can find more information about this in this excellent blog post by @adam-coster.

That said, I am a fervent supporter of moving things to ESM, so my recommendation will always be to try to use it wherever possible.

[claytongulick]

No, it's not.

Are you sure? https://antfu.me/posts/publish-esm-and-cjs

I've bundled for both without any major issues.

[belinde]

I agree with claytongulick. I investigated for a few hours how to get the latest wersions of the package working with the existing codebase and I've decided that it's not worth the effort. Keycloak seerver is a great software, but this library can be easily replaced with some homemade call. It's a shame because I always prefere to use official clients, but I cannot afford to lose days and days of work just to have some REST call done.

Surely ES modules are the future, but at the moment commonjs is too much ubiquitous to be ignored.