hono-openapi: The export types are still wrong
Unfortunately, the recent release has not fixed the issues affecting Node.js projects using ESM with tsconfig "module": "node16" or "module": "nodenext". Note that these are the officially recommended settings for all Node.js projects. Please check the awesome website from Andrew Branch of the TS-team which highlights the current issue: https://arethetypeswrong.github.io/?p=hono-openapi%400.2.0.
From my understanding we need to make sure that the output files for ESM have a .mjs file extension (and its type files the matching .mts file extension). Currently, this package declares itself as a CommonJS library in it’s package.json so that all the exported files with .js extensions will always be interpreted as CJS modules by Node.js.
I tried to fix the output settings in the rollup config but nx is magically trying to take over with it’s withNx function and I was not able to change the settings to something like this:
output: [
{
dir: './dist',
format: 'esm',
entryFileNames: '[name].mjs',
},
{
dir: './dist',
format: 'cjs',
entryFileNames: '[name].js',
}
],
As a side note: I’m not sure why anyone would still build new projects in 2024 with CJS. That ship has long sailed. The amount of complexity one has to handle to make a dual-emit properly work is unfortunately considerable. I would simply consider whether it is not time to jump on the standard bandwagon and embrace the ESM happy path. 😃
About this issue
- Original URL
- State: closed
- Created 2 years ago
- Comments: 28 (21 by maintainers)
Setting the type to module is definitely the way to go. If you then want to support exactly what Hono supports you can model its exports for sure (as long as that matches your actual dist output). That would make it work for most but not all users. Afaik it would work for esm and bundler projects but not for classic cjs projects.
That’s not what I would do but happy with whatever works for you! I would set the type to module, release a esm build, remove the cjs exports and communicate clearly that this is a esm only library: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
@marcomuser I think you’re correct here, thanks for calling that out!
@MathurAditya724 whatever you do here, I strongly recommend validating your work with Are The Types Wrong — it’s built by a core maintainer of TypeScript that did a ton of work on module resolution (@andrewbranch). You can use the ATTW CLI to validate your
dist/output locally.Hi @MathurAditya724, sorry I was out having lunch, I can confirm that
0.4.1is working normally in my local repo without error.I won’t have bandwidth to test this out myself for a bit but the Are The Types Wrong results look promising: https://arethetypeswrong.github.io/?p=hono-openapi@0.4.0
Thanks @MathurAditya724 @marcomuser for your work on this! 🎊
@marcomuser I have created a PR #44, which has a custom rollup config. Can you take a look?
I will add the contribution guidelines soon, but for the timing the command to bundle the package is
pnpm nx build core, thedistfolder will be created inside the core package.Yes, thank you, everyone, for your help on this!
And it’s fixed in
v0.4.3Hey @marcomuser, sorry for the late response. I am also not a fan of doing this manually but I had too because the
withNxwrapper was adding quite a lot of plugins to therollupconfig, and I am compiling it usingswcso a plugin for that is also added which is coming fromnxonly. So basically the build outputs where quite different in size and structure too, cause by defaultrollupusesesbuild. I wanted to first check if this solves the issue (and also limit the changes in that PR) before putting the effort to migrate all the plugins.So now as we know this works, we can start working on a new PR to migrate the
rollupconfig.What I don’t understand is why you removed the node16 module config from the tsconfig and instead opted into handling that manually in rollup. Seems way more error prone than letting typescript handle that for you?
Another problem I found is that in the published package, there seems to be a
moduleprop added inpackage.jsonthat points to a non-existing./index.esm.jsI’ll take a look later today after work! 😃
The code emitted is perfectly fine. The file extensions are the root of all evil. The issue comes from how Node.js decides to interpret packages as ESM or as CJS. And TypeScript models these rules too. If a package.json has no “type” property (like this one) it will be interpreted as CommonJS - UNLESS the file extension (.cjs or .mjs) declares the module as another type.
Looking at the relevant section of the package.json:
Since there is no “type” property, Node.js will interpret
.jsfile extensions as CommonJS and TypeScript will interpret.tsfile extensions as CommonJS too. A dual-emit, thus, absolutely needs to use diverging file extensions for one of the two emits., e.g.:Note that I also swapped the order of declaring types and default export. This is needed by TypeScript for some reason I don’t remember right now.
If we get the build pipeline to emit two sets of files with different file extensions and use those in all the exports, we will be fine no matter what you set as “type” property in the package.json. 😃 Even though I strongly recommend to follow Hono’s lead and set the “type” property to “module”. In which case the package.json exports should swap the file extensions:
Hi there — I don’t believe changing the package.json
typetomodulewill fix this. My hunch is that it’s a bigger problem where the build pipeline is emitting incorrect code/types. See the results from Are The Types Wrong and publint: https://arethetypeswrong.github.io/?p=hono-openapi@0.3.1 https://publint.dev/hono-openapi@0.3.1As a short-term fix, I’d recommend removing these
importstatements from thepackage.jsonso ESM consumers can defer to the CJS build, which is correct according to above links.As a longer term fix, I’d recommend moving your build process to
tsuportshy, which are both well-regarded tools for building hybrid packages (I’ve had success with both).As a final piece of advice, I’d recommend adding contributing guidelines to this repo or at least some sort of documentation for how the build process works. I was hoping to open a PR to address this but there’s seemingly no info on how to build this repo locally.