doc: update conditions, add "deno" and "types" #40708
Conversation
guybedford
changed the title
|
I've amended this PR to also include a |
Co-authored-by: Rich Trott <[email protected]>
guybedford
changed the title
|
I've removed the "source" condition for now, and also included a clarification that the "development" condition is primarily for debugging context use cases. |
guybedford
changed the title
Co-authored-by: Jordan Harband <[email protected]>
|
It seems really strange to me to explicitly endorse a private company’s product in node’s documentation. |
We originally discussed having a conditions registry being maintained outside of Node.js, but then made the decision to maintain the list in the Node.js documentation for now. No one has so far expressed any issue about listing |
|
The other conditions are all broad community standards, like browsers or types, or node things themselves. I don’t think it’s really appropriate for node to claim a “registry” when node isn’t enforcing anything like that - it seems better for each tool to describe the conditions that tool supports. |
|
@ljharb I personally feel quite strongly that especially given the risks of confusion we should be putting together more guidance not less with regards to usage of the "exports" field, and that maintaining a well-defined list of conditions most JS developers should know about is part of that effort. Your argument here seems to be on the grounds of "appropriate", which seems quite ill defined. Can you try to explain more clearly what exactly you disagree with about Node.js mentioning the "deno" condition? IMO this isn't a case of companies competing, but platforms coordinating in the shared interest of the user. |
|
I agree with you that those resources should exist, but it feels like the sort of thing the community should be deciding - node’s docs are authoritative and supposed to be primarily about how to use node. There’s no way imo that “most” JS developers “should” know about a lot of the options for this list - they’re things that a subset of developers, and often a small subset, will want to know about. Package authors targeting a non-node platform generally will be familiar with that platform’s docs, as will tooling authors - who else needs to know about possible exports conditions? |
|
I've added a commit to clarify that the "conditions definitions" Node.js docs section is an entire documentation section dedicated to maintaining a list of conditions defintions of conditions not directly implemented in Node.js as a community coordination help. In the process I removed some redundant text and also realised the To help further clarify this docs section, we could also consider renaming the title from "condition definitions" to "community definitions" to be clear that this is a coordination effort and not to do with documenting Node.js. |
|
@weswigham in the TSC meeting today we discussed that it would be good to verify that there is implementer agreement with these conditions definitions. Can you perhaps explicitly confirm / approve you are happy with the |
|
Yes with one caveat - it's fine for different conditions of an entrypoint to have different APIs (a la {
"exports": {
".": {
"types": {
"module": "./types/wrapper.d.mts",
"default": "./types/entrypoint.d.ts"
},
"module": "./wrapper.mjs",
"default": "./entrypoint.js"
}
}
}And, in fact, you typically must provide a separate definition for each version of an entrypoint in such a scenario (to at least capture the differing format data). |
|
Thanks for the confirmation @weswigham. Point taken re the dual typing - to avoid getting too much into the details I've removed the note about singular typing interface requirement for now. If you have a resource on this that can be linked to in future for further guidance please do share it here. |
This would perhaps be a great thing for TypeScript to document, and we could link to that. |
|
This PR no longer has a block and as per the TSC discussion we have now had implementer feedback from both Deno and TypeScript on these conditions as well. Does anyone feel any further requirements should be met to land this PR? If not I will aim to land in the coming days. |
|
@guybedford can you link to that implementer feedback? |
|
@ljharb see #40708 (comment) and #40708 (comment). |
PR-URL: #40708 Reviewed-By: Rich Trott <[email protected]> Reviewed-By: Geoffrey Booth <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Michael Dawson <[email protected]>
|
Landed in e31d1cb. |
PR-URL: #40708 Reviewed-By: Rich Trott <[email protected]> Reviewed-By: Geoffrey Booth <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Michael Dawson <[email protected]>
PR-URL: #40708 Reviewed-By: Rich Trott <[email protected]> Reviewed-By: Geoffrey Booth <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Michael Dawson <[email protected]>
PR-URL: #40708 Reviewed-By: Rich Trott <[email protected]> Reviewed-By: Geoffrey Booth <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Michael Dawson <[email protected]>
This adds two new conditions to the endorsed "exports" conditions list in the Node.js documentation.
"deno"condition when resolving using its Node.js compatibility resolver, allowing packages to define variants specifically for Deno. This makes the text in the Node.js documentation incorrect as since now the implementation exists we can correspondingly endorse its usage.It also reorders conditions by specificity and clarifies some of the definitions including:
These could possibly be split out into separate PRs for further discussion if there are any objections to any of the specific conditions listed in this PR.
@nodejs/modules