Use the node: protocol in docs examples
#38343
Comments
|
We may want to wait for this support for
That's really nice, thanks for doing this! |
|
Will |
Currently, it doesn't. In ESM world, a specifier using the |
|
Not 100% sure, but as the docs state
If I also have to inspect what the identifier is and change that string, isn't it strictly less useful for that use case? "Use this function to check if modules i first party, oh and btw you also need to strip Or do you mean "in addition to this list, all modules prefixed with (this is getting off topic, might be better to open a new issue) EDIT: I guess this is an issue for |
I think that's correct, if a user tries to
So far that has never been the case, but could change in the future. Currently, the introduction of a new core module (E.G.:
(I agree 😅)
Note sure what you mean by that, |
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
I think it makes sense to go ahead and do in docs in the main branch. It could take some time before things get backported to v14.x. |
aduh95
added
the
good first issue
|
My one major concern about this pattern becoming engrained is it means truly locking down that import maps should map all URLs and not just bare specifiers. Eg a package on unpkg that wants to shim a Node.js builtin with an import map. From a sort of security perspective I still like the concept of import maps only working on bare specifiers as it makes the security holes in the module graph absolutely clear from a resolution perspective, while this ship has most likely sailed to bring in this higher order concern here, it still seems a slight risk to me. The concern being that if import maps were to change to disabling absolute URL mappings at some point it might present an issue to mapping builtins for existing modules containing |
This comment has been minimized.
This comment has been minimized.
See for instance nodejs/node#38343.
|
@sindresorhus @jasnell et al. I've opened PR #38620 addressing this change in all the api docs. Please let me know what you think when you have time. |
|
I don't think it's a good idea to use |
@ljharb I might be stating the obvious here, but the docs are for specific versions, so we could update it for the versions that support it, and leave it as is for the versions that don't. |
|
@Trott while that is totally true, in my experience, most people have no idea that the default docs they land on are for latest node, even if they're not using latest node. |
That's their problem I guess, they should read the documentation appropriate to their Node version, if they don't they will take responsibility to try something from the latest documentation that don't work for their version. Each Node.js version has its documentation so IMO there is really no problem for that change! |
|
While that’s also true, the failure for downstream package consumers might be a bit more complex to debug with a node:-prefixed specifier than with a nonexistent feature. Things that affect published package consumers are always a lot more complex than things that affect local codebases. |
Trott
removed
the
good first issue
Some core modules can be loaded with or without the `node:` prefix. Using the prefix disambiguates which specifiers refer to core modules. This commit updates the docs to use the prefix everywhere a core module is referenced. PR-URL: #42752 Fixes: #38343 Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Mestery <[email protected]> Reviewed-By: Darshan Sen <[email protected]> Reviewed-By: Akhil Marsonya <[email protected]> Reviewed-By: Rafael Gonzaga <[email protected]> Reviewed-By: Mohammed Keyvanzadeh <[email protected]> Reviewed-By: Geoffrey Booth <[email protected]> Reviewed-By: Stephen Belanger <[email protected]>
Some core modules can be loaded with or without the `node:` prefix. Using the prefix disambiguates which specifiers refer to core modules. This commit updates the docs to use the prefix everywhere a core module is referenced. PR-URL: nodejs#42752 Fixes: nodejs#38343 Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Mestery <[email protected]> Reviewed-By: Darshan Sen <[email protected]> Reviewed-By: Akhil Marsonya <[email protected]> Reviewed-By: Rafael Gonzaga <[email protected]> Reviewed-By: Mohammed Keyvanzadeh <[email protected]> Reviewed-By: Geoffrey Booth <[email protected]> Reviewed-By: Stephen Belanger <[email protected]>
Some core modules can be loaded with or without the `node:` prefix. Using the prefix disambiguates which specifiers refer to core modules. This commit updates the docs to use the prefix everywhere a core module is referenced. PR-URL: #42752 Fixes: #38343 Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Mestery <[email protected]> Reviewed-By: Darshan Sen <[email protected]> Reviewed-By: Akhil Marsonya <[email protected]> Reviewed-By: Rafael Gonzaga <[email protected]> Reviewed-By: Mohammed Keyvanzadeh <[email protected]> Reviewed-By: Geoffrey Booth <[email protected]> Reviewed-By: Stephen Belanger <[email protected]>
Some core modules can be loaded with or without the `node:` prefix. Using the prefix disambiguates which specifiers refer to core modules. This commit updates the docs to use the prefix everywhere a core module is referenced. PR-URL: #42752 Fixes: #38343 Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Mestery <[email protected]> Reviewed-By: Darshan Sen <[email protected]> Reviewed-By: Akhil Marsonya <[email protected]> Reviewed-By: Rafael Gonzaga <[email protected]> Reviewed-By: Mohammed Keyvanzadeh <[email protected]> Reviewed-By: Geoffrey Booth <[email protected]> Reviewed-By: Stephen Belanger <[email protected]>
Some core modules can be loaded with or without the `node:` prefix. Using the prefix disambiguates which specifiers refer to core modules. This commit updates the docs to use the prefix everywhere a core module is referenced. PR-URL: #42752 Fixes: #38343 Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Mestery <[email protected]> Reviewed-By: Darshan Sen <[email protected]> Reviewed-By: Akhil Marsonya <[email protected]> Reviewed-By: Rafael Gonzaga <[email protected]> Reviewed-By: Mohammed Keyvanzadeh <[email protected]> Reviewed-By: Geoffrey Booth <[email protected]> Reviewed-By: Stephen Belanger <[email protected]>
Some core modules can be loaded with or without the `node:` prefix. Using the prefix disambiguates which specifiers refer to core modules. This commit updates the docs to use the prefix everywhere a core module is referenced. PR-URL: #42752 Fixes: #38343 Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Mestery <[email protected]> Reviewed-By: Darshan Sen <[email protected]> Reviewed-By: Akhil Marsonya <[email protected]> Reviewed-By: Rafael Gonzaga <[email protected]> Reviewed-By: Mohammed Keyvanzadeh <[email protected]> Reviewed-By: Geoffrey Booth <[email protected]> Reviewed-By: Stephen Belanger <[email protected]>
Some core modules can be loaded with or without the `node:` prefix. Using the prefix disambiguates which specifiers refer to core modules. This commit updates the docs to use the prefix everywhere a core module is referenced. PR-URL: #42752 Fixes: #38343 Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Mestery <[email protected]> Reviewed-By: Darshan Sen <[email protected]> Reviewed-By: Akhil Marsonya <[email protected]> Reviewed-By: Rafael Gonzaga <[email protected]> Reviewed-By: Mohammed Keyvanzadeh <[email protected]> Reviewed-By: Geoffrey Booth <[email protected]> Reviewed-By: Stephen Belanger <[email protected]>
If there is any reason to "lock down" module resolutions, would not the Node.js built-ins be of the absolute highest priority to lock down? I agree that it can make sense -- even then -- to tamper with the resolution.....but that's a statement about the high utility in tweaking resolution in general. tl;dr Import maps should work for all specifiers. |
|
@pauldraper |
Some core modules can be loaded with or without the `node:` prefix. Using the prefix disambiguates which specifiers refer to core modules. This commit updates the docs to use the prefix everywhere a core module is referenced. PR-URL: nodejs/node#42752 Fixes: nodejs/node#38343 Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Mestery <[email protected]> Reviewed-By: Darshan Sen <[email protected]> Reviewed-By: Akhil Marsonya <[email protected]> Reviewed-By: Rafael Gonzaga <[email protected]> Reviewed-By: Mohammed Keyvanzadeh <[email protected]> Reviewed-By: Geoffrey Booth <[email protected]> Reviewed-By: Stephen Belanger <[email protected]>
- Bump Node.js to version 18. This change is necessary as Node.js v16 will reach end-of-life on 2023-09-11. It also ensure compatibility with dependencies requiring minimum of Node.js v18, such as `vite`, `@vitejs`plugin-legacy` and `icon-gen`. - Bump `setup-node` action to v4. - Recommend using the `nvm` tool for managing Node.js versions in the documentation. - Update documentation to point to code reference for required Node.js version. This removes duplication of information, and keeps the code as single source of truth for required Node.js version. - Refactor code to adopt the `node:` protocol for Node API imports as per Node.js 18 standards. This change addresses ambiguities and aligns with Node.js best practices (nodejs/node#38343). Currently, there is no ESLint rule to enforce this protocol, as noted in import-js/eslint-plugin-import#2717. - Replace `cross-fetch` dependency with the native Node.js fetch API introduced in Node.js 18. Adjust type casting for async iterable read streams to align with the latest Node.js APIs, based on discussions in DefinitelyTyped/DefinitelyTyped#65542.
The
node:protocol has many benefits:However, most people don't know about the
node:protocol. I suggest Node.js makes it the recommended way of importing builtin modules by using it in all the examples in the documentation. A lot of people are starting to move to ESM, so now would be a good time for people to switch to thenode:protocol too.Personally, I plan to switch all my packages to use the
node:protocol. We have also made an ESLint rule for it.The text was updated successfully, but these errors were encountered: