From c20fdb4e52f5feff23ffee26fa35daf06902ea14 Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Tue, 5 Sep 2023 02:23:02 +0200 Subject: [PATCH] doc: edit `import.meta.resolve` documentation PR-URL: https://github.com/nodejs/node/pull/49247 Backport-PR-URL: https://github.com/nodejs/node/pull/50669 Refs: https://github.com/nodejs/node/pull/49028 Reviewed-By: Geoffrey Booth Reviewed-By: Guy Bedford --- doc/api/esm.md | 30 ++++++++++++++++-------------- 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/doc/api/esm.md b/doc/api/esm.md index 065671aeebae03..f74dd1542ea807 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -328,6 +328,9 @@ added: - v13.9.0 - v12.16.2 changes: + - version: REPLACEME + pr-url: https://github.com/nodejs/node/pull/49028 + description: No longer behind the `--experimental-import-meta-resolve` flag. - version: REPLACEME pr-url: https://github.com/nodejs/node/pull/44710 description: This API now returns a string synchronously instead of a Promise. @@ -347,7 +350,7 @@ changes: * `specifier` {string} The module specifier to resolve relative to the current module. -* Returns: {string} The absolute (`file:`) URL string for the resolved module. +* Returns: {string} The absolute URL string that the specifier would resolve to. [`import.meta.resolve`][] is a module-relative resolution function scoped to each module, returning the URL string. @@ -355,28 +358,27 @@ each module, returning the URL string. ```js const dependencyAsset = import.meta.resolve('component-lib/asset.css'); // file:///app/node_modules/component-lib/asset.css +import.meta.resolve('./dep.js'); +// file:///app/dep.js ``` All features of the Node.js module resolution are supported. Dependency resolutions are subject to the permitted exports resolutions within the package. -```js -import.meta.resolve('./dep', import.meta.url); -// file:///app/dep -``` +**Caveats**: -> **Caveat** This can result in synchronous file-system operations, which -> can impact performance similarly to `require.resolve`. +* This can result in synchronous file-system operations, which + can impact performance similarly to `require.resolve`. +* This feature is not available within custom loaders (it would + create a deadlock). -Previously, Node.js implemented an asynchronous resolver which also permitted -a second contextual argument. The implementation has since been updated to be -synchronous, with the second contextual `parent` argument still accessible -behind the `--experimental-import-meta-resolve` flag: +**Non-standard API**: -* `parent` {string|URL} An optional absolute parent module URL to resolve from. +When using the `--experimental-import-meta-resolve` flag, that function accepts +a second argument: -> **Caveat** This feature is not available within module customization hooks (it -> would create a deadlock). +* `parent` {string|URL} An optional absolute parent module URL to resolve from. + **Default:** `import.meta.url` ## Interoperability with CommonJS