Change Request: Export types from main entry point

[lumirlumir]

Environment

ESLint version: HEAD
@eslint/json version: HEAD
Node version: 20.19.3
npm version: 10.9.2
Operating System: Windows 11

What problem do you want to solve?

Hi,

I'm raising this issue based on eslint/markdown#453, eslint/markdown#367 (comment), and eslint/markdown#367 (comment).

cc. @JoshuaKGoldberg

---

Currently, the JSON, CSS, and Markdown plugins export their types defined in types.ts from the /types entry point.

For example:

• JSON: @eslint/json/types

  • package.json reference
  • types.ts reference

  https://github.com/eslint/json/blob/bc2b31768b0e7dcde61d456ab34bafa3afce65a8/package.json#L20-L27

• CSS: @eslint/css/types

  • package.json reference
  • types.ts reference

• Markdown: @eslint/markdown/types

  • package.json reference
  • types.ts reference

---

As mentioned in eslint/markdown#453, eslint/markdown#367 (comment), and also from my own experience, exporting types from a /types entry point is a fairly uncommon pattern in TypeScript.

With this proposal, I'd like to suggest exporting types from the main entry point instead (i.e., @eslint/json, @eslint/css, and @eslint/markdown), rather than from @eslint/json/types, @eslint/css/types, and @eslint/markdown/types.

What do you think is the correct solution?

There are two possible approaches, depending on whether the build script uses bundling:

• If bundling is used:

  Adding export * from "types.ts" to the banner section in rollup.config.js worked well and was the simplest way to achieve this proposal in my tests.

  https://github.com/eslint/json/blob/bc2b31768b0e7dcde61d456ab34bafa3afce65a8/rollup.config.js#L14

• If bundling is not used:

  The following approach was the cleanest solution I found.

  I've taken another shot at this and wanted to share a different approach.

  Here's what I did:

  • First, I created an empty types.js file at src/types.js:

  export default {};

  • Then, I added export * from "./types.js"; to the end of index.js:

  // ...
  
  export default plugin;
  export { MarkdownSourceCode };
  + export * from "./types.js";

  ---

  This approach seems to work well, since it allows all types from src/types.ts to be imported directly from the @eslint/markdown package, rather than from @eslint/markdown/types.

  

  

Participation

• I am willing to submit a pull request for this change.

Additional comments

This proposal applies to all packages that export their types from types.ts using the @eslint/package-name/types entry point.

So far, I've only reviewed the JSON, CSS, and Markdown plugins, but I plan to look into the other packages as I continue.

[nzakas]

Thanks for the suggestion. The reason we don't do this is because of the complexity of bundling CommonJS and ESM in one package. We already jump through a lot of hoops just to get the correct types output, and I don't want to keep adding more complexity on top of it.

• Adding export * from "types.ts" to the banner section in rollup.config.js worked well and was the simplest way to achieve this proposal in my tests.

How does this work? You're adding an export from a TypeScript file inside of a JavaScript file?

Personally, I don't think it's worth making this change unless we want to switch the whole package to be ESM-only, at which point this becomes a lot easier.

[lumirlumir]

Thanks for sharing the context, it was really helpful.

How does this work? You're adding an export from a TypeScript file inside of a JavaScript file?

Sorry, I misunderstood how it works. It actually requires some additional setup.

---

I completely understand your concerns. I agree that it adds more complexity to the build process.

Would you prefer to close this issue for now, or mark it as blocked and revisit it after we drop support for Node.js 18.x?

Based on eslint/eslint#19969, it seems that require(ESM) is a consideration. In my opinion, ESLint v10 might be a good time to make this change, since we'll be able to drop support for CJS modules then.

Just my thoughts! I'm happy to go with whatever you think is best.

[nzakas]

Let's leave this open for now and we can revisit after v10 is released. I would like to move all of our plugin packages to be ESM-only after that point.

[lumirlumir]

@nzakas

I’d like to ask what you think about applying this change to the Markdown plugin first. Since the Markdown plugin is now ESM-only, I believe this change could be applied smoothly.

Would it be needed to provide a more concrete proposal for how to move forward with this?

[nzakas]

@lumirlumir I think that's fine, but we can't remove /types without a breaking change, so I'd hold off on that part for some future date to give people time to update their code.

[lumirlumir]

@nzakas Absolutely. I'll make sure not to remove /types.