{
  "source": "doc/api/esm.md",
  "modules": [
    {
      "textRaw": "ECMAScript Modules",
      "name": "esm",
      "introduced_in": "v9.x.x",
      "stability": 1,
      "stabilityText": "Experimental",
      "desc": "<p>Node.js contains support for ES Modules based upon the\n<a href=\"https://github.com/nodejs/node-eps/blob/master/002-es-modules.md\">Node.js EP for ES Modules</a>.</p>\n<p>Not all features of the EP are complete and will be landing as both VM support\nand implementation is ready. Error messages are still being polished.</p>\n",
      "miscs": [
        {
          "textRaw": "Enabling",
          "name": "Enabling",
          "type": "misc",
          "desc": "<p>The <code>--experimental-modules</code> flag can be used to enable features for loading\nESM modules.</p>\n<p>Once this has been set, files ending with <code>.mjs</code> will be able to be loaded\nas ES Modules.</p>\n<pre><code class=\"lang-sh\">node --experimental-modules my-app.mjs\n</code></pre>\n"
        },
        {
          "textRaw": "Features",
          "name": "Features",
          "type": "misc",
          "miscs": [
            {
              "textRaw": "Supported",
              "name": "supported",
              "desc": "<p>Only the CLI argument for the main entry point to the program can be an entry\npoint into an ESM graph. In the future <code>import()</code> can be used to create entry\npoints into ESM graphs at run time.</p>\n",
              "type": "misc",
              "displayName": "Supported"
            },
            {
              "textRaw": "Unsupported",
              "name": "unsupported",
              "desc": "<table>\n<thead>\n<tr>\n<th>Feature</th>\n<th>Reason</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td><code>require(&#39;./foo.mjs&#39;)</code></td>\n<td>ES Modules have differing resolution and timing, use language standard <code>import()</code></td>\n</tr>\n<tr>\n<td><code>import()</code></td>\n<td>pending newer V8 release used in Node.js</td>\n</tr>\n<tr>\n<td><code>import.meta</code></td>\n<td>pending V8 implementation</td>\n</tr>\n<tr>\n<td>Loader Hooks</td>\n<td>pending Node.js EP creation/consensus</td>\n</tr>\n</tbody>\n</table>\n",
              "type": "misc",
              "displayName": "Unsupported"
            }
          ]
        }
      ],
      "modules": [
        {
          "textRaw": "Notable differences between `import` and `require`",
          "name": "notable_differences_between_`import`_and_`require`",
          "modules": [
            {
              "textRaw": "No NODE_PATH",
              "name": "no_node_path",
              "desc": "<p><code>NODE_PATH</code> is not part of resolving <code>import</code> specifiers. Please use symlinks\nif this behavior is desired.</p>\n",
              "type": "module",
              "displayName": "No NODE_PATH"
            },
            {
              "textRaw": "URL based paths",
              "name": "url_based_paths",
              "desc": "<p>ESM are resolved and cached based upon <a href=\"https://url.spec.whatwg.org/\">URL</a>\nsemantics. This means that files containing special characters such as <code>#</code> and\n<code>?</code> need to be escaped.</p>\n<p>Modules will be loaded multiple times if the <code>import</code> specifier used to resolve\nthem have a different query or fragment.</p>\n<pre><code class=\"lang-js\">import &#39;./foo?query=1&#39;; // loads ./foo with query of &quot;?query=1&quot;\nimport &#39;./foo?query=2&#39;; // loads ./foo with query of &quot;?query=2&quot;\n</code></pre>\n<p>For now, only modules using the <code>file:</code> protocol can be loaded.</p>\n",
              "type": "module",
              "displayName": "URL based paths"
            }
          ],
          "properties": [
            {
              "textRaw": "No `require.extensions`",
              "name": "extensions`",
              "desc": "<p><code>require.extensions</code> is not used by <code>import</code>. The expectation is that loader\nhooks can provide this workflow in the future.</p>\n"
            },
            {
              "textRaw": "No `require.cache`",
              "name": "cache`",
              "desc": "<p><code>require.cache</code> is not used by <code>import</code>. It has a separate cache.</p>\n"
            }
          ],
          "type": "module",
          "displayName": "Notable differences between `import` and `require`"
        },
        {
          "textRaw": "Interop with existing modules",
          "name": "interop_with_existing_modules",
          "desc": "<p>All CommonJS, JSON, and C++ modules can be used with <code>import</code>.</p>\n<p>Modules loaded this way will only be loaded once, even if their query\nor fragment string differs between <code>import</code> statements.</p>\n<p>When loaded via <code>import</code> these modules will provide a single <code>default</code> export\nrepresenting the value of <code>module.exports</code> at the time they finished evaluating.</p>\n<pre><code class=\"lang-js\">import fs from &#39;fs&#39;;\nfs.readFile(&#39;./foo.txt&#39;, (err, body) =&gt; {\n  if (err) {\n    console.error(err);\n  } else {\n    console.log(body);\n  }\n});\n</code></pre>\n",
          "type": "module",
          "displayName": "Interop with existing modules"
        }
      ],
      "type": "module",
      "displayName": "esm"
    }
  ]
}