From 36a1f5b8afeb94921a1220d776c5669a340f80bc Mon Sep 17 00:00:00 2001 From: Guy Bedford Date: Sat, 5 Aug 2023 18:15:19 +0000 Subject: [PATCH] docs changes --- doc/api/esm.md | 47 +++++++++++++++++++++++++++-------------------- 1 file changed, 27 insertions(+), 20 deletions(-) diff --git a/doc/api/esm.md b/doc/api/esm.md index 6d510d0d0b00b5..c44b5e538406c3 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -322,7 +322,7 @@ import { readFileSync } from 'node:fs'; const buffer = readFileSync(new URL('./data.proto', import.meta.url)); ``` -### `import.meta.resolve(specifier[, parent])` +### `import.meta.resolve(specifier)` -> Stability: 1 - Experimental - -This feature is only available with the `--experimental-import-meta-resolve` -command flag enabled. - * `specifier` {string} The module specifier to resolve relative to `parent`. -* `parent` {string|URL} The absolute parent module URL to resolve from. If none - is specified, the value of `import.meta.url` is used as the default. -* Returns: {string} - -Provides a module-relative resolution function scoped to each module, returning -the URL string. In alignment with browser behavior, this now returns -synchronously. +* Returns: {string} The absolute (`file:`) URL string for the resolved module. -> **Caveat** This can result in synchronous file-system operations, which -> can impact performance similarly to `require.resolve`. +[`import.meta.resolve`][] is a module-relative resolution function scoped to +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` also accepts a second argument which is the parent module -from which to resolve: +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 ``` +> **Caveat** This can result in synchronous file-system operations, which +> can impact performance similarly to `require.resolve`. + +Previously, Node.js implemented an asynchonous resolver which also permitted +a second contextual argument. The implementation has since been updated to be +synchronous, with the second contextual `parent` URL still accessible behind the +`--experimental-import-meta-resolve` flag: + +* `parent` {string|URL} An optional absolute parent module URL to resolve from. + ## Interoperability with CommonJS ### `import` statements @@ -501,8 +507,8 @@ They can instead be loaded with [`module.createRequire()`][] or Relative resolution can be handled via `new URL('./local', import.meta.url)`. -For a complete `require.resolve` replacement, there is a flagged experimental -[`import.meta.resolve`][] API. +For a complete `require.resolve` replacement, there is the +[import.meta.resolve][] API. Alternatively `module.createRequire()` can be used. @@ -1672,7 +1678,7 @@ for ESM specifiers is [commonjs-extension-resolution-loader][]. [`data:` URLs]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs [`export`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export [`import()`]: #import-expressions -[`import.meta.resolve`]: #importmetaresolvespecifier-parent +[`import.meta.resolve`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import.meta/resolve [`import.meta.url`]: #importmetaurl [`import`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import [`initialize`]: #initialize @@ -1690,6 +1696,7 @@ for ESM specifiers is [commonjs-extension-resolution-loader][]. [cjs-module-lexer]: https://github.com/nodejs/cjs-module-lexer/tree/1.2.2 [commonjs-extension-resolution-loader]: https://github.com/nodejs/loaders-test/tree/main/commonjs-extension-resolution-loader [custom https loader]: #https-loader +[import.meta.resolve]: #importmetaresolvespecifier [load hook]: #loadurl-context-nextload [percent-encoded]: url.md#percent-encoding-in-urls [special scheme]: https://url.spec.whatwg.org/#special-scheme