Better ESM/CJS support

[vladmoroz]

Current issues

• Defaults to CJS even for modern Node
  • node folder for CJS is misleading and not discoverable
  • View source action in VS Code goes to the (hard to read) CJS version
• package.json doesn’t specify the type field
• ESM code is missing extensions
  • ESM version can't be used without a bunlder
  • Makes it incompatible with moduleResolution: "Node" | "NodeNext"

Suggestions

My preferred implementation would be to do what we learned from doing the dual package in Radix Themes (see on unpkg):

• type: "commonjs" in the root package.json
• type: "module" in the esm folder package.json
• exports field with require and import declarations
• Explicit cjs and esm folders in the built package
  • Makes it easy for consumers to find the right version if they need to explicitly point their tooling to the ESM/CJS version
• Extensions in source code
  • No build tooling would be needed to transform extensions
  • ESLint can enforce this and auto add them, VSC support is good too

publint can be a good way to check if all looks good:
https://publint.dev/@base_ui/react@1.0.0-alpha.2
https://publint.dev/@radix-ui/themes@3.1.4

Some details on the possible implementations:
https://www.sensedeep.com/blog/posts/2021/how-to-create-single-source-npm-module.html

[michaldudak]

Done in #821

[github-actions]

This issue has been closed. If you have a similar problem but not exactly the same, please open a new issue.
Now, if you have additional information related to this issue or things that could help future readers, feel free to leave a comment.