Lines Matching +full:hook +full:- +full:run +full:- +full:in +full:- +full:context
3 <!--introduced_in=v8.5.0-->
4 <!-- type=misc -->
5 <!-- YAML
8 - version:
9 - v12.20.0
10 pr-url: https://github.com/nodejs/node/pull/35249
12 - version: v12.20.0
13 pr-url: https://github.com/nodejs/node/pull/31974
15 - version:
16 - v12.17.0
17 pr-url: https://github.com/nodejs/node/pull/29866
18 description: Loading ECMAScript modules no longer requires a command-line flag.
19 - version: v12.0.0
20 pr-url: https://github.com/nodejs/node/pull/26745
24 -->
26 > Stability: 1 - Experimental
30 <!--name=esm-->
62 [Node.js EP for ES Modules][] and the [ECMAScript-modules implementation][].
64 Expect major changes in the implementation including interoperability support,
67 <!-- Anchors to make sure old links find a target -->
74 <!-- type=misc -->
79 `--input-type` flag. See
83 <!-- Anchors to make sure old links find a target -->
108 e.g. `'path'` in `import { sep } from 'path'`. Specifiers are also used in
113 * _Bare specifiers_ like `'some-package'`. They refer to an entry point of a
116 * _Deep import specifiers_ like `'some-package/lib/shuffle.mjs'`. They refer to
126 strings; but everything else in a specifier is a URL.
130 supported in Node.js.
137 <!-- YAML
139 -->
151 <!-- YAML
153 -->
190 This behavior matches how `import` behaves in browser environments, assuming a
200 These CommonJS variables are not available in ES modules.
219 and supported via the `--experimental-import-meta-resolve` flag:
223 const dependencyAsset = await import.meta.resolve('component-lib/asset.css');
237 This function is asynchronous because the ES module resolver in Node.js is
238 asynchronous. With the introduction of [Top-Level Await][], these use cases
244 hooks can provide this workflow in the future.
250 ### URL-based paths
272 in an ES module environment using [`module.createRequire()`][].
279 `import` statements are permitted only in ES modules. For similar functionality
280 in CommonJS, see [`import()`][].
293 can either be an URL-style relative path like `'./file.mjs'` or a package name
296 Like in CommonJS, files within packages can be accessed by appending a path to
298 [`"exports"`][] field, in which case files within packages need to be accessed
299 via the path defined in [`"exports"`][].
302 import { sin, cos } from 'geometry/trigonometry-functions.mjs';
307 [Dynamic `import()`][] is supported in both CommonJS and ES modules. It can be
317 <!-- eslint-disable no-duplicate-imports -->
322 // for `{ default as cjsSugar }` in the above import statement:
339 <!-- eslint-skip -->
349 For better compatibility with existing usage in the JS ecosystem, Node.js
350 in addition attempts to determine the CommonJS named exports of every imported
361 The preceding module supports named imports in ES modules:
363 <!-- eslint-disable no-duplicate-imports -->
386 always correctly detect named exports. In these cases, using the default
390 and build tool and transpiler outputs. See [cjs-module-lexer][] for the exact
447 Currently importing JSON modules are only supported in the `commonjs` mode
450 additional flag `--experimental-json-modules` when running Node.js.
452 When the `--experimental-json-modules` flag is included, both the
455 support for named exports. A cache entry is created in the CommonJS
456 cache to avoid duplication. The same object is returned in
462 <!-- eslint-skip -->
467 The `--experimental-json-modules` flag is needed for the module
472 node --experimental-json-modules index.mjs # works
478 `--experimental-wasm-modules` flag, allowing any `.wasm` files to be
481 This integration is in line with the
494 node --experimental-wasm-modules index.mjs
503 <!-- type=misc -->
506 provided via a `--experimental-loader ./loader-name.mjs` argument to Node.js.
513 #### `resolve(specifier, context, defaultResolve)`
515 > Note: The loaders API is being redesigned. This hook may disappear or its
519 * `context` {Object}
526 The `resolve` hook returns the resolved file URL for a given module specifier
527 and parent URL. The module specifier is the string in an `import` statement or
531 The `conditions` property on the `context` is an array of conditions for
536 The current [package exports conditions][Conditional Exports] are always in
537 the `context.conditions` array passed into the hook. To guarantee _default
539 `context.conditions` array passed to it _must_ include _all_ elements of the
540 `context.conditions` array originally passed into the `resolve` hook.
548 * }} context
552 export async function resolve(specifier, context, defaultResolve) {
553 const { parentURL = null } = context;
564 // When calling `defaultResolve`, the arguments can be modified. In this
567 ...context,
568 conditions: [...context.conditions, 'another-condition'],
572 return defaultResolve(specifier, context, defaultResolve);
576 #### `getFormat(url, context, defaultGetFormat)`
578 > Note: The loaders API is being redesigned. This hook may disappear or its
582 * `context` {Object}
587 The `getFormat` hook provides a way to define a custom method of determining how
593 | ------------ | ------------------------------ | ---------------------------------------------…
595 | `'dynamic'` | Use a [dynamic instantiate hook][] | Not applicable …
601 Note: These types all correspond to classes defined in ECMAScript.
606 Note: If the source value of a text-based format (i.e., `'json'`, `'module'`) is
612 * @param {Object} context (currently empty)
616 export async function getFormat(url, context, defaultGetFormat) {
620 // format is one of the strings in the preceding table.
626 return defaultGetFormat(url, context, defaultGetFormat);
630 #### `getSource(url, context, defaultGetSource)`
632 > Note: The loaders API is being redesigned. This hook may disappear or its
636 * `context` {Object}
642 The `getSource` hook provides a way to define a custom method for retrieving
649 * @param {{ format: string }} context
653 export async function getSource(url, context, defaultGetSource) {
654 const { format } = context;
663 return defaultGetSource(url, context, defaultGetSource);
667 #### `transformSource(source, context, defaultTransformSource)`
670 NODE_OPTIONS='--experimental-loader ./custom-loader.mjs' node x.js
673 > Note: The loaders API is being redesigned. This hook may disappear or its
677 * `context` {Object}
683 The `transformSource` hook provides a way to modify the source code of a loaded
687 If this hook is used to convert unknown-to-Node.js file types into executable
688 JavaScript, a resolve hook is also necessary in order to register any
689 unknown-to-Node.js file extensions. See the [transpiler loader example][] below.
697 * }} context
701 export async function transformSource(source, context, defaultTransformSource) {
702 const { url, format } = context;
711 return defaultTransformSource(source, context, defaultTransformSource);
717 > Note: The loaders API is being redesigned. This hook may disappear or its
722 Sometimes it might be necessary to run some code inside of the same global scope
723 that the application runs in. This hook allows the return of a string that is
724 run as sloppy-mode script on startup.
726 Similar to how CommonJS wrappers work, the code runs in an implicit function
727 scope. The only argument is a `require`-like function that can be used to load
735 * @returns {string} Code to run before application startup
750 #### <code>dynamicInstantiate</code> hook
752 > Note: The loaders API is being redesigned. This hook may disappear or its
756 existing `format` interpretations, the `dynamicInstantiate` hook can be used.
757 This hook is called only for modules that return `format: 'dynamic'` from
758 the `getFormat` hook.
771 // Get and set functions provided for pre-allocated export names
780 in the import tree.
784 The various loader hooks can be used together to accomplish wide-ranging
789 In current Node.js, specifiers starting with `https://` are unsupported. The
797 // https-loader.mjs
800 export function resolve(specifier, context, defaultResolve) {
801 const { parentURL = null } = context;
804 // this hook intercepts them and converts them into absolute URLs to be
817 return defaultResolve(specifier, context, defaultResolve);
820 export function getFormat(url, context, defaultGetFormat) {
821 // This loader assumes all network-provided JavaScript is ES module code.
829 return defaultGetFormat(url, context, defaultGetFormat);
832 export function getSource(url, context, defaultGetSource) {
846 return defaultGetSource(url, context, defaultGetSource);
852 import { VERSION } from 'https://coffeescript.org/browser-compiler-modern/coffeescript.js';
858 `node --experimental-loader ./https-loader.mjs ./main.mjs`
859 prints the current version of CoffeeScript per the module at the URL in
864 Sources that are in formats Node.js doesn’t understand can be converted into
865 JavaScript using the [`transformSource` hook][]. Before that hook gets called,
874 // coffeescript-loader.mjs
880 // CoffeeScript files end in .coffee, .litcoffee or .coffee.md.
883 export function resolve(specifier, context, defaultResolve) {
884 const { parentURL = baseURL } = context;
887 // specifiers ending in the CoffeeScript file extensions.
895 return defaultResolve(specifier, context, defaultResolve);
898 export function getFormat(url, context, defaultGetFormat) {
909 return defaultGetFormat(url, context, defaultGetFormat);
912 export function transformSource(source, context, defaultTransformSource) {
913 const { url, format } = context;
922 return defaultTransformSource(source, context, defaultTransformSource);
937 export scream = (str) -> str.toUpperCase()
941 `node --experimental-loader ./coffeescript-loader.mjs main.coffee`
953 * FileURL-based resolution as is used by ES modules
970 legacy CommonJS loader. Additional formats such as _"addon"_ can be extended in
973 In the following algorithms, all subroutine errors are propagated as errors
974 of these top-level routines unless stated otherwise.
987 subpath in the package for the given module.
1064 > 1. Return the URL resolution of _packageSubpath_ in _packageURL_.
1116 > 1. If _pjson.imports_ is a non-null Object, then
1127 > 1. If _matchKey_ is a key of _matchObj_, and does not end in _"*"_, then
1132 > 1. Let _expansionKeys_ be the list of keys of _matchObj_ ending in _"/"_
1134 > 1. For each key _expansionKey_ in _expansionKeys_, do
1135 > 1. If _expansionKey_ ends in _"*"_ and _matchKey_ starts with but is
1159 > 1. If _pattern_ is **false**, _subpath_ has non-zero length and _target_
1175 > 1. Assert: _resolvedTarget_ is contained in _packageURL_.
1184 > 1. Otherwise, if _target_ is a non-null Object, then
1185 > 1. If _exports_ contains any index property keys, as defined in ECMA-262
1187 > 1. For each property _p_ of _target_, in object insertion order as,
1190 > 1. Let _targetValue_ be the value of the _p_ property in _target_.
1199 > 1. For each item _targetValue_ in _target_, do
1214 > 1. If _url_ ends in _".mjs"_, then
1216 > 1. If _url_ ends in _".cjs"_, then
1219 > 1. If _url_ ends in _".js"_, then
1230 > 1. If _scopeURL_ ends in a _"node_modules"_ path segment, return **null**.
1252 The `--experimental-specifier-resolution=[mode]` flag can be used to customize
1263 $ node --experimental-specifier-resolution=node index
1267 <!-- Note: The cjs-module-lexer link should be kept in-sync with the deps version -->
1270 [Dynamic `import()`]: https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statem…
1271 [ECMAScript-modules implementation]: https://github.com/nodejs/modules/blob/master/doc/plan-for-new…
1272 [ES Module Integration Proposal for Web Assembly]: https://github.com/webassembly/esm-integration
1273 [Node.js EP for ES Modules]: https://github.com/nodejs/node-eps/blob/master/002-es-modules.md
1275 [WHATWG JSON modules specification]: https://html.spec.whatwg.org/#creating-a-json-module-script
1276 [`data:` URLs]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs
1277 [`export`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export
1280 [`import`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import
1283 [`transformSource` hook]: #esm_transformsource_source_context_defaulttransformsource
1284 [`ArrayBuffer`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/A…
1285 [`SharedArrayBuffer`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Obj…
1286 [`string`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String
1287 [`TypedArray`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Ty…
1288 [`Uint8Array`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Ui…
1289 [dynamic instantiate hook]: #esm_code_dynamicinstantiate_code_hook
1291 [cjs-module-lexer]: https://github.com/guybedford/cjs-module-lexer/tree/1.0.0
1292 [special scheme]: https://url.spec.whatwg.org/#special-scheme
1293 [the official standard format]: https://tc39.github.io/ecma262/#sec-modules
1295 [6.1.7 Array Index]: https://tc39.es/ecma262/#integer-index
1296 [Top-Level Await]: https://github.com/tc39/proposal-top-level-await