eslint: Breaking: define an `exports` field for our public API
The version of ESLint you are using.
Latest
The problem you want to solve.
Downstream packages rely on ESLint’s internal modules, and removing/altering these modules can cause breakages in the ecosystem (example here). A lot of thought has gone into what is and isn’t our public API (defined here), but it would be great to be able to enforce that downstream packages don’t rely on these modules, since treating every module in our codebase as public isn’t practical and would make it extremely difficult to refactor or do feature work.
To be clear, I don’t think that our current strategy of defining our public API and then treating all other modules as “private” is an uncommon practice, but I do think this small change could prevent some instances of this from happening in the future.
Your take on the correct solution to problem.
As suggested here, I would like to propose that we define an exports field to a) clearly document what we consider our public API from an importable module standpoint, and b) prevent those using more recent versions of Node.js from importing internal modules not intended for public consumption. For older versions of Node.js, main (which we have defined) would be used as a fallback. You can find more details in the Node.js Package Entry Points docs.
Are you willing to submit a pull request to implement this change?
Absolutely!
About this issue
- Original URL
- State: closed
- Created 4 years ago
- Reactions: 5
- Comments: 23 (21 by maintainers)
Links to this issue
Commits related to this issue
- Breaking: Strict package exports (refs #13654) — committed to eslint/eslint by nzakas 3 years ago
- New: Add ESLint#getRulesMetaForResults() (refs #13654) — committed to eslint/eslint by nzakas 3 years ago
- New: Add ESLint#getRulesMetaForResults() (refs #13654) (#14716) * New: Add ESLint#getRulesMetaForResults() (refs #13654) * Update docs * Update docs/developer-guide/nodejs-api.md Co-authored... — committed to eslint/eslint by nzakas 3 years ago
- Breaking: Strict package exports (refs #13654) (#14706) * Breaking: Strict package exports (refs #13654) * Update docs * Fix linting errors * Update docs/developer-guide/nodejs-api.md Co-... — committed to eslint/eslint by nzakas 3 years ago
TSC Summary: This proposal seeks to add an
exportsfield topackage.jsonthat specifically identifies which files are part of the public API. Despite our consistently saying people should not be accessing files directly in theeslintpackage, people still are, and then complain when we make a change. For new Node.js versions, includingexportswould ensure our internal file structure isn’t exposed publicly.TSC Question: Shall we accept this proposal and add it to the public roadmap (for v8.0.0).
When adding this, you can use
npx ls-exports path .to verify what exports you’re exposing. This can be used to add the field in a nonbreaking way right now as well.Either way, I’d be happy to review any change around this field for correctness (node 13.0 and 13.1, if supported, require extra consideration in the format, as do a few non-latest minors in 12 and 14); please feel free to ping me.
“each rule” could still be on the list of entrypoints; that seems like a reasonably safe thing to expose to me.
Once the list of entrypoints exists, i will still happily make the PR to define them.
We’d like to include this in our upcoming v8.0.0 release if possible. The next step is to write an RFC specifying which portions of our API we want to expose via
exports. Is anybody interested in contributing that? The team would be happy to answer questions along the way.@btmills once the choices are made, I’d be happy to volunteer to write the PR to implement it.
@kaicataldo Did you mean to link to here? https://nodejs.org/api/packages.html. The link in the description is to the ESM Docs.
This seems like a simple enough change to prevent any further misunderstandings about what is and isn’t a public API.