11cb0ef41Sopenharmony_ci<!DOCTYPE html> 21cb0ef41Sopenharmony_ci<html lang="en"> 31cb0ef41Sopenharmony_ci<head> 41cb0ef41Sopenharmony_ci <meta charset="utf-8"> 51cb0ef41Sopenharmony_ci <meta name="viewport" content="width=device-width"> 61cb0ef41Sopenharmony_ci <meta name="nodejs.org:node-version" content="v18.20.1"> 71cb0ef41Sopenharmony_ci <title>Modules: Packages | Node.js v18.20.1 Documentation</title> 81cb0ef41Sopenharmony_ci <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:400,700,400italic&display=fallback"> 91cb0ef41Sopenharmony_ci <link rel="stylesheet" href="assets/style.css"> 101cb0ef41Sopenharmony_ci <link rel="stylesheet" href="assets/hljs.css"> 111cb0ef41Sopenharmony_ci <link rel="canonical" href="https://nodejs.org/api/packages.html"> 121cb0ef41Sopenharmony_ci <script async defer src="assets/api.js" type="text/javascript"></script> 131cb0ef41Sopenharmony_ci 141cb0ef41Sopenharmony_ci</head> 151cb0ef41Sopenharmony_ci<body class="alt apidoc" id="api-section-packages"> 161cb0ef41Sopenharmony_ci <div id="content" class="clearfix"> 171cb0ef41Sopenharmony_ci <div id="column2" class="interior"> 181cb0ef41Sopenharmony_ci <div id="intro" class="interior"> 191cb0ef41Sopenharmony_ci <a href="/" title="Go back to the home page"> 201cb0ef41Sopenharmony_ci Node.js 211cb0ef41Sopenharmony_ci </a> 221cb0ef41Sopenharmony_ci </div> 231cb0ef41Sopenharmony_ci <ul> 241cb0ef41Sopenharmony_ci<li><a href="documentation.html" class="nav-documentation">About this documentation</a></li> 251cb0ef41Sopenharmony_ci<li><a href="synopsis.html" class="nav-synopsis">Usage and example</a></li> 261cb0ef41Sopenharmony_ci</ul> 271cb0ef41Sopenharmony_ci<hr class="line"> 281cb0ef41Sopenharmony_ci<ul> 291cb0ef41Sopenharmony_ci<li><a href="assert.html" class="nav-assert">Assertion testing</a></li> 301cb0ef41Sopenharmony_ci<li><a href="async_context.html" class="nav-async_context">Asynchronous context tracking</a></li> 311cb0ef41Sopenharmony_ci<li><a href="async_hooks.html" class="nav-async_hooks">Async hooks</a></li> 321cb0ef41Sopenharmony_ci<li><a href="buffer.html" class="nav-buffer">Buffer</a></li> 331cb0ef41Sopenharmony_ci<li><a href="addons.html" class="nav-addons">C++ addons</a></li> 341cb0ef41Sopenharmony_ci<li><a href="n-api.html" class="nav-n-api">C/C++ addons with Node-API</a></li> 351cb0ef41Sopenharmony_ci<li><a href="embedding.html" class="nav-embedding">C++ embedder API</a></li> 361cb0ef41Sopenharmony_ci<li><a href="child_process.html" class="nav-child_process">Child processes</a></li> 371cb0ef41Sopenharmony_ci<li><a href="cluster.html" class="nav-cluster">Cluster</a></li> 381cb0ef41Sopenharmony_ci<li><a href="cli.html" class="nav-cli">Command-line options</a></li> 391cb0ef41Sopenharmony_ci<li><a href="console.html" class="nav-console">Console</a></li> 401cb0ef41Sopenharmony_ci<li><a href="corepack.html" class="nav-corepack">Corepack</a></li> 411cb0ef41Sopenharmony_ci<li><a href="crypto.html" class="nav-crypto">Crypto</a></li> 421cb0ef41Sopenharmony_ci<li><a href="debugger.html" class="nav-debugger">Debugger</a></li> 431cb0ef41Sopenharmony_ci<li><a href="deprecations.html" class="nav-deprecations">Deprecated APIs</a></li> 441cb0ef41Sopenharmony_ci<li><a href="diagnostics_channel.html" class="nav-diagnostics_channel">Diagnostics Channel</a></li> 451cb0ef41Sopenharmony_ci<li><a href="dns.html" class="nav-dns">DNS</a></li> 461cb0ef41Sopenharmony_ci<li><a href="domain.html" class="nav-domain">Domain</a></li> 471cb0ef41Sopenharmony_ci<li><a href="errors.html" class="nav-errors">Errors</a></li> 481cb0ef41Sopenharmony_ci<li><a href="events.html" class="nav-events">Events</a></li> 491cb0ef41Sopenharmony_ci<li><a href="fs.html" class="nav-fs">File system</a></li> 501cb0ef41Sopenharmony_ci<li><a href="globals.html" class="nav-globals">Globals</a></li> 511cb0ef41Sopenharmony_ci<li><a href="http.html" class="nav-http">HTTP</a></li> 521cb0ef41Sopenharmony_ci<li><a href="http2.html" class="nav-http2">HTTP/2</a></li> 531cb0ef41Sopenharmony_ci<li><a href="https.html" class="nav-https">HTTPS</a></li> 541cb0ef41Sopenharmony_ci<li><a href="inspector.html" class="nav-inspector">Inspector</a></li> 551cb0ef41Sopenharmony_ci<li><a href="intl.html" class="nav-intl">Internationalization</a></li> 561cb0ef41Sopenharmony_ci<li><a href="modules.html" class="nav-modules">Modules: CommonJS modules</a></li> 571cb0ef41Sopenharmony_ci<li><a href="esm.html" class="nav-esm">Modules: ECMAScript modules</a></li> 581cb0ef41Sopenharmony_ci<li><a href="module.html" class="nav-module">Modules: <code>node:module</code> API</a></li> 591cb0ef41Sopenharmony_ci<li><a href="packages.html" class="nav-packages active">Modules: Packages</a></li> 601cb0ef41Sopenharmony_ci<li><a href="net.html" class="nav-net">Net</a></li> 611cb0ef41Sopenharmony_ci<li><a href="os.html" class="nav-os">OS</a></li> 621cb0ef41Sopenharmony_ci<li><a href="path.html" class="nav-path">Path</a></li> 631cb0ef41Sopenharmony_ci<li><a href="perf_hooks.html" class="nav-perf_hooks">Performance hooks</a></li> 641cb0ef41Sopenharmony_ci<li><a href="permissions.html" class="nav-permissions">Permissions</a></li> 651cb0ef41Sopenharmony_ci<li><a href="process.html" class="nav-process">Process</a></li> 661cb0ef41Sopenharmony_ci<li><a href="punycode.html" class="nav-punycode">Punycode</a></li> 671cb0ef41Sopenharmony_ci<li><a href="querystring.html" class="nav-querystring">Query strings</a></li> 681cb0ef41Sopenharmony_ci<li><a href="readline.html" class="nav-readline">Readline</a></li> 691cb0ef41Sopenharmony_ci<li><a href="repl.html" class="nav-repl">REPL</a></li> 701cb0ef41Sopenharmony_ci<li><a href="report.html" class="nav-report">Report</a></li> 711cb0ef41Sopenharmony_ci<li><a href="single-executable-applications.html" class="nav-single-executable-applications">Single executable applications</a></li> 721cb0ef41Sopenharmony_ci<li><a href="stream.html" class="nav-stream">Stream</a></li> 731cb0ef41Sopenharmony_ci<li><a href="string_decoder.html" class="nav-string_decoder">String decoder</a></li> 741cb0ef41Sopenharmony_ci<li><a href="test.html" class="nav-test">Test runner</a></li> 751cb0ef41Sopenharmony_ci<li><a href="timers.html" class="nav-timers">Timers</a></li> 761cb0ef41Sopenharmony_ci<li><a href="tls.html" class="nav-tls">TLS/SSL</a></li> 771cb0ef41Sopenharmony_ci<li><a href="tracing.html" class="nav-tracing">Trace events</a></li> 781cb0ef41Sopenharmony_ci<li><a href="tty.html" class="nav-tty">TTY</a></li> 791cb0ef41Sopenharmony_ci<li><a href="dgram.html" class="nav-dgram">UDP/datagram</a></li> 801cb0ef41Sopenharmony_ci<li><a href="url.html" class="nav-url">URL</a></li> 811cb0ef41Sopenharmony_ci<li><a href="util.html" class="nav-util">Utilities</a></li> 821cb0ef41Sopenharmony_ci<li><a href="v8.html" class="nav-v8">V8</a></li> 831cb0ef41Sopenharmony_ci<li><a href="vm.html" class="nav-vm">VM</a></li> 841cb0ef41Sopenharmony_ci<li><a href="wasi.html" class="nav-wasi">WASI</a></li> 851cb0ef41Sopenharmony_ci<li><a href="webcrypto.html" class="nav-webcrypto">Web Crypto API</a></li> 861cb0ef41Sopenharmony_ci<li><a href="webstreams.html" class="nav-webstreams">Web Streams API</a></li> 871cb0ef41Sopenharmony_ci<li><a href="worker_threads.html" class="nav-worker_threads">Worker threads</a></li> 881cb0ef41Sopenharmony_ci<li><a href="zlib.html" class="nav-zlib">Zlib</a></li> 891cb0ef41Sopenharmony_ci</ul> 901cb0ef41Sopenharmony_ci<hr class="line"> 911cb0ef41Sopenharmony_ci<ul> 921cb0ef41Sopenharmony_ci<li><a href="https://github.com/nodejs/node" class="nav-https-github-com-nodejs-node">Code repository and issue tracker</a></li> 931cb0ef41Sopenharmony_ci</ul> 941cb0ef41Sopenharmony_ci </div> 951cb0ef41Sopenharmony_ci 961cb0ef41Sopenharmony_ci <div id="column1" data-id="packages" class="interior"> 971cb0ef41Sopenharmony_ci <header class="header"> 981cb0ef41Sopenharmony_ci <div class="header-container"> 991cb0ef41Sopenharmony_ci <h1>Node.js v18.20.1 documentation</h1> 1001cb0ef41Sopenharmony_ci <button class="theme-toggle-btn" id="theme-toggle-btn" title="Toggle dark mode/light mode" aria-label="Toggle dark mode/light mode" hidden> 1011cb0ef41Sopenharmony_ci <svg xmlns="http://www.w3.org/2000/svg" class="icon dark-icon" height="24" width="24"> 1021cb0ef41Sopenharmony_ci <path fill="none" d="M0 0h24v24H0z" /> 1031cb0ef41Sopenharmony_ci <path d="M11.1 12.08c-2.33-4.51-.5-8.48.53-10.07C6.27 2.2 1.98 6.59 1.98 12c0 .14.02.28.02.42.62-.27 1.29-.42 2-.42 1.66 0 3.18.83 4.1 2.15A4.01 4.01 0 0111 18c0 1.52-.87 2.83-2.12 3.51.98.32 2.03.5 3.11.5 3.5 0 6.58-1.8 8.37-4.52-2.36.23-6.98-.97-9.26-5.41z"/> 1041cb0ef41Sopenharmony_ci <path d="M7 16h-.18C6.4 14.84 5.3 14 4 14c-1.66 0-3 1.34-3 3s1.34 3 3 3h3c1.1 0 2-.9 2-2s-.9-2-2-2z"/> 1051cb0ef41Sopenharmony_ci </svg> 1061cb0ef41Sopenharmony_ci <svg xmlns="http://www.w3.org/2000/svg" class="icon light-icon" height="24" width="24"> 1071cb0ef41Sopenharmony_ci <path d="M0 0h24v24H0z" fill="none" /> 1081cb0ef41Sopenharmony_ci <path d="M6.76 4.84l-1.8-1.79-1.41 1.41 1.79 1.79 1.42-1.41zM4 10.5H1v2h3v-2zm9-9.95h-2V3.5h2V.55zm7.45 3.91l-1.41-1.41-1.79 1.79 1.41 1.41 1.79-1.79zm-3.21 13.7l1.79 1.8 1.41-1.41-1.8-1.79-1.4 1.4zM20 10.5v2h3v-2h-3zm-8-5c-3.31 0-6 2.69-6 6s2.69 6 6 6 6-2.69 6-6-2.69-6-6-6zm-1 16.95h2V19.5h-2v2.95zm-7.45-3.91l1.41 1.41 1.79-1.8-1.41-1.41-1.79 1.8z"/> 1091cb0ef41Sopenharmony_ci </svg> 1101cb0ef41Sopenharmony_ci </button> 1111cb0ef41Sopenharmony_ci </div> 1121cb0ef41Sopenharmony_ci <div id="gtoc"> 1131cb0ef41Sopenharmony_ci <ul> 1141cb0ef41Sopenharmony_ci <li class="pinned-header">Node.js v18.20.1</li> 1151cb0ef41Sopenharmony_ci 1161cb0ef41Sopenharmony_ci <li class="picker-header"> 1171cb0ef41Sopenharmony_ci <a href="#"> 1181cb0ef41Sopenharmony_ci <span class="collapsed-arrow">►</span><span class="expanded-arrow">▼</span> 1191cb0ef41Sopenharmony_ci Table of contents 1201cb0ef41Sopenharmony_ci </a> 1211cb0ef41Sopenharmony_ci 1221cb0ef41Sopenharmony_ci <div class="picker"><div class="toc"><ul> 1231cb0ef41Sopenharmony_ci<li><a href="#modules-packages">Modules: Packages</a> 1241cb0ef41Sopenharmony_ci<ul> 1251cb0ef41Sopenharmony_ci<li><a href="#introduction">Introduction</a></li> 1261cb0ef41Sopenharmony_ci<li><a href="#determining-module-system">Determining module system</a> 1271cb0ef41Sopenharmony_ci<ul> 1281cb0ef41Sopenharmony_ci<li><a href="#introduction_1">Introduction</a></li> 1291cb0ef41Sopenharmony_ci<li><a href="#modules-loaders">Modules loaders</a></li> 1301cb0ef41Sopenharmony_ci<li><a href="#packagejson-and-file-extensions"><code>package.json</code> and file extensions</a></li> 1311cb0ef41Sopenharmony_ci<li><a href="#--input-type-flag"><code>--input-type</code> flag</a></li> 1321cb0ef41Sopenharmony_ci</ul> 1331cb0ef41Sopenharmony_ci</li> 1341cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#determining-package-manager">Determining package manager</a></span></li> 1351cb0ef41Sopenharmony_ci<li><a href="#package-entry-points">Package entry points</a> 1361cb0ef41Sopenharmony_ci<ul> 1371cb0ef41Sopenharmony_ci<li><a href="#main-entry-point-export">Main entry point export</a></li> 1381cb0ef41Sopenharmony_ci<li><a href="#subpath-exports">Subpath exports</a> 1391cb0ef41Sopenharmony_ci<ul> 1401cb0ef41Sopenharmony_ci<li><a href="#extensions-in-subpaths">Extensions in subpaths</a></li> 1411cb0ef41Sopenharmony_ci</ul> 1421cb0ef41Sopenharmony_ci</li> 1431cb0ef41Sopenharmony_ci<li><a href="#exports-sugar">Exports sugar</a></li> 1441cb0ef41Sopenharmony_ci<li><a href="#subpath-imports">Subpath imports</a></li> 1451cb0ef41Sopenharmony_ci<li><a href="#subpath-patterns">Subpath patterns</a></li> 1461cb0ef41Sopenharmony_ci<li><a href="#conditional-exports">Conditional exports</a></li> 1471cb0ef41Sopenharmony_ci<li><a href="#nested-conditions">Nested conditions</a></li> 1481cb0ef41Sopenharmony_ci<li><a href="#resolving-user-conditions">Resolving user conditions</a></li> 1491cb0ef41Sopenharmony_ci<li><a href="#community-conditions-definitions">Community Conditions Definitions</a></li> 1501cb0ef41Sopenharmony_ci<li><a href="#self-referencing-a-package-using-its-name">Self-referencing a package using its name</a></li> 1511cb0ef41Sopenharmony_ci</ul> 1521cb0ef41Sopenharmony_ci</li> 1531cb0ef41Sopenharmony_ci<li><a href="#dual-commonjses-module-packages">Dual CommonJS/ES module packages</a> 1541cb0ef41Sopenharmony_ci<ul> 1551cb0ef41Sopenharmony_ci<li><a href="#dual-package-hazard">Dual package hazard</a></li> 1561cb0ef41Sopenharmony_ci<li><a href="#writing-dual-packages-while-avoiding-or-minimizing-hazards">Writing dual packages while avoiding or minimizing hazards</a> 1571cb0ef41Sopenharmony_ci<ul> 1581cb0ef41Sopenharmony_ci<li><a href="#approach-1-use-an-es-module-wrapper">Approach #1: Use an ES module wrapper</a></li> 1591cb0ef41Sopenharmony_ci<li><a href="#approach-2-isolate-state">Approach #2: Isolate state</a></li> 1601cb0ef41Sopenharmony_ci</ul> 1611cb0ef41Sopenharmony_ci</li> 1621cb0ef41Sopenharmony_ci</ul> 1631cb0ef41Sopenharmony_ci</li> 1641cb0ef41Sopenharmony_ci<li><a href="#nodejs-packagejson-field-definitions">Node.js <code>package.json</code> field definitions</a> 1651cb0ef41Sopenharmony_ci<ul> 1661cb0ef41Sopenharmony_ci<li><a href="#name"><code>"name"</code></a></li> 1671cb0ef41Sopenharmony_ci<li><a href="#main"><code>"main"</code></a></li> 1681cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#packagemanager"><code>"packageManager"</code></a></span></li> 1691cb0ef41Sopenharmony_ci<li><a href="#type"><code>"type"</code></a></li> 1701cb0ef41Sopenharmony_ci<li><a href="#exports"><code>"exports"</code></a></li> 1711cb0ef41Sopenharmony_ci<li><a href="#imports"><code>"imports"</code></a></li> 1721cb0ef41Sopenharmony_ci</ul> 1731cb0ef41Sopenharmony_ci</li> 1741cb0ef41Sopenharmony_ci</ul> 1751cb0ef41Sopenharmony_ci</li> 1761cb0ef41Sopenharmony_ci</ul></div></div> 1771cb0ef41Sopenharmony_ci </li> 1781cb0ef41Sopenharmony_ci 1791cb0ef41Sopenharmony_ci 1801cb0ef41Sopenharmony_ci <li class="picker-header"> 1811cb0ef41Sopenharmony_ci <a href="#"> 1821cb0ef41Sopenharmony_ci <span class="collapsed-arrow">►</span><span class="expanded-arrow">▼</span> 1831cb0ef41Sopenharmony_ci Index 1841cb0ef41Sopenharmony_ci </a> 1851cb0ef41Sopenharmony_ci 1861cb0ef41Sopenharmony_ci <div class="picker"><ul> 1871cb0ef41Sopenharmony_ci<li><a href="documentation.html" class="nav-documentation">About this documentation</a></li> 1881cb0ef41Sopenharmony_ci<li><a href="synopsis.html" class="nav-synopsis">Usage and example</a></li> 1891cb0ef41Sopenharmony_ci 1901cb0ef41Sopenharmony_ci <li> 1911cb0ef41Sopenharmony_ci <a href="index.html">Index</a> 1921cb0ef41Sopenharmony_ci </li> 1931cb0ef41Sopenharmony_ci </ul> 1941cb0ef41Sopenharmony_ci 1951cb0ef41Sopenharmony_ci<hr class="line"> 1961cb0ef41Sopenharmony_ci<ul> 1971cb0ef41Sopenharmony_ci<li><a href="assert.html" class="nav-assert">Assertion testing</a></li> 1981cb0ef41Sopenharmony_ci<li><a href="async_context.html" class="nav-async_context">Asynchronous context tracking</a></li> 1991cb0ef41Sopenharmony_ci<li><a href="async_hooks.html" class="nav-async_hooks">Async hooks</a></li> 2001cb0ef41Sopenharmony_ci<li><a href="buffer.html" class="nav-buffer">Buffer</a></li> 2011cb0ef41Sopenharmony_ci<li><a href="addons.html" class="nav-addons">C++ addons</a></li> 2021cb0ef41Sopenharmony_ci<li><a href="n-api.html" class="nav-n-api">C/C++ addons with Node-API</a></li> 2031cb0ef41Sopenharmony_ci<li><a href="embedding.html" class="nav-embedding">C++ embedder API</a></li> 2041cb0ef41Sopenharmony_ci<li><a href="child_process.html" class="nav-child_process">Child processes</a></li> 2051cb0ef41Sopenharmony_ci<li><a href="cluster.html" class="nav-cluster">Cluster</a></li> 2061cb0ef41Sopenharmony_ci<li><a href="cli.html" class="nav-cli">Command-line options</a></li> 2071cb0ef41Sopenharmony_ci<li><a href="console.html" class="nav-console">Console</a></li> 2081cb0ef41Sopenharmony_ci<li><a href="corepack.html" class="nav-corepack">Corepack</a></li> 2091cb0ef41Sopenharmony_ci<li><a href="crypto.html" class="nav-crypto">Crypto</a></li> 2101cb0ef41Sopenharmony_ci<li><a href="debugger.html" class="nav-debugger">Debugger</a></li> 2111cb0ef41Sopenharmony_ci<li><a href="deprecations.html" class="nav-deprecations">Deprecated APIs</a></li> 2121cb0ef41Sopenharmony_ci<li><a href="diagnostics_channel.html" class="nav-diagnostics_channel">Diagnostics Channel</a></li> 2131cb0ef41Sopenharmony_ci<li><a href="dns.html" class="nav-dns">DNS</a></li> 2141cb0ef41Sopenharmony_ci<li><a href="domain.html" class="nav-domain">Domain</a></li> 2151cb0ef41Sopenharmony_ci<li><a href="errors.html" class="nav-errors">Errors</a></li> 2161cb0ef41Sopenharmony_ci<li><a href="events.html" class="nav-events">Events</a></li> 2171cb0ef41Sopenharmony_ci<li><a href="fs.html" class="nav-fs">File system</a></li> 2181cb0ef41Sopenharmony_ci<li><a href="globals.html" class="nav-globals">Globals</a></li> 2191cb0ef41Sopenharmony_ci<li><a href="http.html" class="nav-http">HTTP</a></li> 2201cb0ef41Sopenharmony_ci<li><a href="http2.html" class="nav-http2">HTTP/2</a></li> 2211cb0ef41Sopenharmony_ci<li><a href="https.html" class="nav-https">HTTPS</a></li> 2221cb0ef41Sopenharmony_ci<li><a href="inspector.html" class="nav-inspector">Inspector</a></li> 2231cb0ef41Sopenharmony_ci<li><a href="intl.html" class="nav-intl">Internationalization</a></li> 2241cb0ef41Sopenharmony_ci<li><a href="modules.html" class="nav-modules">Modules: CommonJS modules</a></li> 2251cb0ef41Sopenharmony_ci<li><a href="esm.html" class="nav-esm">Modules: ECMAScript modules</a></li> 2261cb0ef41Sopenharmony_ci<li><a href="module.html" class="nav-module">Modules: <code>node:module</code> API</a></li> 2271cb0ef41Sopenharmony_ci<li><a href="packages.html" class="nav-packages active">Modules: Packages</a></li> 2281cb0ef41Sopenharmony_ci<li><a href="net.html" class="nav-net">Net</a></li> 2291cb0ef41Sopenharmony_ci<li><a href="os.html" class="nav-os">OS</a></li> 2301cb0ef41Sopenharmony_ci<li><a href="path.html" class="nav-path">Path</a></li> 2311cb0ef41Sopenharmony_ci<li><a href="perf_hooks.html" class="nav-perf_hooks">Performance hooks</a></li> 2321cb0ef41Sopenharmony_ci<li><a href="permissions.html" class="nav-permissions">Permissions</a></li> 2331cb0ef41Sopenharmony_ci<li><a href="process.html" class="nav-process">Process</a></li> 2341cb0ef41Sopenharmony_ci<li><a href="punycode.html" class="nav-punycode">Punycode</a></li> 2351cb0ef41Sopenharmony_ci<li><a href="querystring.html" class="nav-querystring">Query strings</a></li> 2361cb0ef41Sopenharmony_ci<li><a href="readline.html" class="nav-readline">Readline</a></li> 2371cb0ef41Sopenharmony_ci<li><a href="repl.html" class="nav-repl">REPL</a></li> 2381cb0ef41Sopenharmony_ci<li><a href="report.html" class="nav-report">Report</a></li> 2391cb0ef41Sopenharmony_ci<li><a href="single-executable-applications.html" class="nav-single-executable-applications">Single executable applications</a></li> 2401cb0ef41Sopenharmony_ci<li><a href="stream.html" class="nav-stream">Stream</a></li> 2411cb0ef41Sopenharmony_ci<li><a href="string_decoder.html" class="nav-string_decoder">String decoder</a></li> 2421cb0ef41Sopenharmony_ci<li><a href="test.html" class="nav-test">Test runner</a></li> 2431cb0ef41Sopenharmony_ci<li><a href="timers.html" class="nav-timers">Timers</a></li> 2441cb0ef41Sopenharmony_ci<li><a href="tls.html" class="nav-tls">TLS/SSL</a></li> 2451cb0ef41Sopenharmony_ci<li><a href="tracing.html" class="nav-tracing">Trace events</a></li> 2461cb0ef41Sopenharmony_ci<li><a href="tty.html" class="nav-tty">TTY</a></li> 2471cb0ef41Sopenharmony_ci<li><a href="dgram.html" class="nav-dgram">UDP/datagram</a></li> 2481cb0ef41Sopenharmony_ci<li><a href="url.html" class="nav-url">URL</a></li> 2491cb0ef41Sopenharmony_ci<li><a href="util.html" class="nav-util">Utilities</a></li> 2501cb0ef41Sopenharmony_ci<li><a href="v8.html" class="nav-v8">V8</a></li> 2511cb0ef41Sopenharmony_ci<li><a href="vm.html" class="nav-vm">VM</a></li> 2521cb0ef41Sopenharmony_ci<li><a href="wasi.html" class="nav-wasi">WASI</a></li> 2531cb0ef41Sopenharmony_ci<li><a href="webcrypto.html" class="nav-webcrypto">Web Crypto API</a></li> 2541cb0ef41Sopenharmony_ci<li><a href="webstreams.html" class="nav-webstreams">Web Streams API</a></li> 2551cb0ef41Sopenharmony_ci<li><a href="worker_threads.html" class="nav-worker_threads">Worker threads</a></li> 2561cb0ef41Sopenharmony_ci<li><a href="zlib.html" class="nav-zlib">Zlib</a></li> 2571cb0ef41Sopenharmony_ci</ul> 2581cb0ef41Sopenharmony_ci<hr class="line"> 2591cb0ef41Sopenharmony_ci<ul> 2601cb0ef41Sopenharmony_ci<li><a href="https://github.com/nodejs/node" class="nav-https-github-com-nodejs-node">Code repository and issue tracker</a></li> 2611cb0ef41Sopenharmony_ci</ul></div> 2621cb0ef41Sopenharmony_ci </li> 2631cb0ef41Sopenharmony_ci 2641cb0ef41Sopenharmony_ci 2651cb0ef41Sopenharmony_ci <li class="picker-header"> 2661cb0ef41Sopenharmony_ci <a href="#"> 2671cb0ef41Sopenharmony_ci <span class="collapsed-arrow">►</span><span class="expanded-arrow">▼</span> 2681cb0ef41Sopenharmony_ci Other versions 2691cb0ef41Sopenharmony_ci </a> 2701cb0ef41Sopenharmony_ci <div class="picker"><ol id="alt-docs"><li><a href="https://nodejs.org/docs/latest-v21.x/api/packages.html">21.x</a></li> 2711cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v20.x/api/packages.html">20.x <b>LTS</b></a></li> 2721cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v19.x/api/packages.html">19.x</a></li> 2731cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v18.x/api/packages.html">18.x <b>LTS</b></a></li> 2741cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v17.x/api/packages.html">17.x</a></li> 2751cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v16.x/api/packages.html">16.x</a></li> 2761cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v15.x/api/packages.html">15.x</a></li> 2771cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v14.x/api/packages.html">14.x</a></li> 2781cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v13.x/api/packages.html">13.x</a></li> 2791cb0ef41Sopenharmony_ci<li><a href="https://nodejs.org/docs/latest-v12.x/api/packages.html">12.x</a></li></ol></div> 2801cb0ef41Sopenharmony_ci </li> 2811cb0ef41Sopenharmony_ci 2821cb0ef41Sopenharmony_ci <li class="picker-header"> 2831cb0ef41Sopenharmony_ci <a href="#"> 2841cb0ef41Sopenharmony_ci <span class="collapsed-arrow">►</span><span class="expanded-arrow">▼</span> 2851cb0ef41Sopenharmony_ci Options 2861cb0ef41Sopenharmony_ci </a> 2871cb0ef41Sopenharmony_ci 2881cb0ef41Sopenharmony_ci <div class="picker"> 2891cb0ef41Sopenharmony_ci <ul> 2901cb0ef41Sopenharmony_ci <li> 2911cb0ef41Sopenharmony_ci <a href="all.html">View on single page</a> 2921cb0ef41Sopenharmony_ci </li> 2931cb0ef41Sopenharmony_ci <li> 2941cb0ef41Sopenharmony_ci <a href="packages.json">View as JSON</a> 2951cb0ef41Sopenharmony_ci </li> 2961cb0ef41Sopenharmony_ci <li class="edit_on_github"><a href="https://github.com/nodejs/node/edit/main/doc/api/packages.md">Edit on GitHub</a></li> 2971cb0ef41Sopenharmony_ci </ul> 2981cb0ef41Sopenharmony_ci </div> 2991cb0ef41Sopenharmony_ci </li> 3001cb0ef41Sopenharmony_ci </ul> 3011cb0ef41Sopenharmony_ci </div> 3021cb0ef41Sopenharmony_ci <hr> 3031cb0ef41Sopenharmony_ci </header> 3041cb0ef41Sopenharmony_ci 3051cb0ef41Sopenharmony_ci <details id="toc" open><summary>Table of contents</summary><ul> 3061cb0ef41Sopenharmony_ci<li><a href="#modules-packages">Modules: Packages</a> 3071cb0ef41Sopenharmony_ci<ul> 3081cb0ef41Sopenharmony_ci<li><a href="#introduction">Introduction</a></li> 3091cb0ef41Sopenharmony_ci<li><a href="#determining-module-system">Determining module system</a> 3101cb0ef41Sopenharmony_ci<ul> 3111cb0ef41Sopenharmony_ci<li><a href="#introduction_1">Introduction</a></li> 3121cb0ef41Sopenharmony_ci<li><a href="#modules-loaders">Modules loaders</a></li> 3131cb0ef41Sopenharmony_ci<li><a href="#packagejson-and-file-extensions"><code>package.json</code> and file extensions</a></li> 3141cb0ef41Sopenharmony_ci<li><a href="#--input-type-flag"><code>--input-type</code> flag</a></li> 3151cb0ef41Sopenharmony_ci</ul> 3161cb0ef41Sopenharmony_ci</li> 3171cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#determining-package-manager">Determining package manager</a></span></li> 3181cb0ef41Sopenharmony_ci<li><a href="#package-entry-points">Package entry points</a> 3191cb0ef41Sopenharmony_ci<ul> 3201cb0ef41Sopenharmony_ci<li><a href="#main-entry-point-export">Main entry point export</a></li> 3211cb0ef41Sopenharmony_ci<li><a href="#subpath-exports">Subpath exports</a> 3221cb0ef41Sopenharmony_ci<ul> 3231cb0ef41Sopenharmony_ci<li><a href="#extensions-in-subpaths">Extensions in subpaths</a></li> 3241cb0ef41Sopenharmony_ci</ul> 3251cb0ef41Sopenharmony_ci</li> 3261cb0ef41Sopenharmony_ci<li><a href="#exports-sugar">Exports sugar</a></li> 3271cb0ef41Sopenharmony_ci<li><a href="#subpath-imports">Subpath imports</a></li> 3281cb0ef41Sopenharmony_ci<li><a href="#subpath-patterns">Subpath patterns</a></li> 3291cb0ef41Sopenharmony_ci<li><a href="#conditional-exports">Conditional exports</a></li> 3301cb0ef41Sopenharmony_ci<li><a href="#nested-conditions">Nested conditions</a></li> 3311cb0ef41Sopenharmony_ci<li><a href="#resolving-user-conditions">Resolving user conditions</a></li> 3321cb0ef41Sopenharmony_ci<li><a href="#community-conditions-definitions">Community Conditions Definitions</a></li> 3331cb0ef41Sopenharmony_ci<li><a href="#self-referencing-a-package-using-its-name">Self-referencing a package using its name</a></li> 3341cb0ef41Sopenharmony_ci</ul> 3351cb0ef41Sopenharmony_ci</li> 3361cb0ef41Sopenharmony_ci<li><a href="#dual-commonjses-module-packages">Dual CommonJS/ES module packages</a> 3371cb0ef41Sopenharmony_ci<ul> 3381cb0ef41Sopenharmony_ci<li><a href="#dual-package-hazard">Dual package hazard</a></li> 3391cb0ef41Sopenharmony_ci<li><a href="#writing-dual-packages-while-avoiding-or-minimizing-hazards">Writing dual packages while avoiding or minimizing hazards</a> 3401cb0ef41Sopenharmony_ci<ul> 3411cb0ef41Sopenharmony_ci<li><a href="#approach-1-use-an-es-module-wrapper">Approach #1: Use an ES module wrapper</a></li> 3421cb0ef41Sopenharmony_ci<li><a href="#approach-2-isolate-state">Approach #2: Isolate state</a></li> 3431cb0ef41Sopenharmony_ci</ul> 3441cb0ef41Sopenharmony_ci</li> 3451cb0ef41Sopenharmony_ci</ul> 3461cb0ef41Sopenharmony_ci</li> 3471cb0ef41Sopenharmony_ci<li><a href="#nodejs-packagejson-field-definitions">Node.js <code>package.json</code> field definitions</a> 3481cb0ef41Sopenharmony_ci<ul> 3491cb0ef41Sopenharmony_ci<li><a href="#name"><code>"name"</code></a></li> 3501cb0ef41Sopenharmony_ci<li><a href="#main"><code>"main"</code></a></li> 3511cb0ef41Sopenharmony_ci<li><span class="stability_1"><a href="#packagemanager"><code>"packageManager"</code></a></span></li> 3521cb0ef41Sopenharmony_ci<li><a href="#type"><code>"type"</code></a></li> 3531cb0ef41Sopenharmony_ci<li><a href="#exports"><code>"exports"</code></a></li> 3541cb0ef41Sopenharmony_ci<li><a href="#imports"><code>"imports"</code></a></li> 3551cb0ef41Sopenharmony_ci</ul> 3561cb0ef41Sopenharmony_ci</li> 3571cb0ef41Sopenharmony_ci</ul> 3581cb0ef41Sopenharmony_ci</li> 3591cb0ef41Sopenharmony_ci</ul></details> 3601cb0ef41Sopenharmony_ci 3611cb0ef41Sopenharmony_ci <div id="apicontent"> 3621cb0ef41Sopenharmony_ci <h2>Modules: Packages<span><a class="mark" href="#modules-packages" id="modules-packages">#</a></span><a aria-hidden="true" class="legacy" id="packages_modules_packages"></a></h2> 3631cb0ef41Sopenharmony_ci 3641cb0ef41Sopenharmony_ci 3651cb0ef41Sopenharmony_ci<div class="api_metadata"> 3661cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 3671cb0ef41Sopenharmony_ci<table> 3681cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 3691cb0ef41Sopenharmony_ci<tr><td>v14.13.0, v12.20.0</td> 3701cb0ef41Sopenharmony_ci<td><p>Add support for <code>"exports"</code> patterns.</p></td></tr> 3711cb0ef41Sopenharmony_ci<tr><td>v14.6.0, v12.19.0</td> 3721cb0ef41Sopenharmony_ci<td><p>Add package <code>"imports"</code> field.</p></td></tr> 3731cb0ef41Sopenharmony_ci<tr><td>v13.7.0, v12.17.0</td> 3741cb0ef41Sopenharmony_ci<td><p>Unflag conditional exports.</p></td></tr> 3751cb0ef41Sopenharmony_ci<tr><td>v13.7.0, v12.16.0</td> 3761cb0ef41Sopenharmony_ci<td><p>Remove the <code>--experimental-conditional-exports</code> option. In 12.16.0, conditional exports are still behind <code>--experimental-modules</code>.</p></td></tr> 3771cb0ef41Sopenharmony_ci<tr><td>v13.6.0, v12.16.0</td> 3781cb0ef41Sopenharmony_ci<td><p>Unflag self-referencing a package using its name.</p></td></tr> 3791cb0ef41Sopenharmony_ci<tr><td>v12.7.0</td> 3801cb0ef41Sopenharmony_ci<td><p>Introduce <code>"exports"</code> <code>package.json</code> field as a more powerful alternative to the classic <code>"main"</code> field.</p></td></tr> 3811cb0ef41Sopenharmony_ci<tr><td>v12.0.0</td> 3821cb0ef41Sopenharmony_ci<td><p>Add support for ES modules using <code>.js</code> file extension via <code>package.json</code> <code>"type"</code> field.</p></td></tr> 3831cb0ef41Sopenharmony_ci</tbody></table> 3841cb0ef41Sopenharmony_ci</details> 3851cb0ef41Sopenharmony_ci</div> 3861cb0ef41Sopenharmony_ci<section><h3>Introduction<span><a class="mark" href="#introduction" id="introduction">#</a></span><a aria-hidden="true" class="legacy" id="packages_introduction"></a></h3> 3871cb0ef41Sopenharmony_ci<p>A package is a folder tree described by a <code>package.json</code> file. The package 3881cb0ef41Sopenharmony_ciconsists of the folder containing the <code>package.json</code> file and all subfolders 3891cb0ef41Sopenharmony_ciuntil the next folder containing another <code>package.json</code> file, or a folder 3901cb0ef41Sopenharmony_cinamed <code>node_modules</code>.</p> 3911cb0ef41Sopenharmony_ci<p>This page provides guidance for package authors writing <code>package.json</code> files 3921cb0ef41Sopenharmony_cialong with a reference for the <a href="#nodejs-packagejson-field-definitions"><code>package.json</code></a> fields defined by Node.js.</p> 3931cb0ef41Sopenharmony_ci</section><section><h3>Determining module system<span><a class="mark" href="#determining-module-system" id="determining-module-system">#</a></span><a aria-hidden="true" class="legacy" id="packages_determining_module_system"></a></h3> 3941cb0ef41Sopenharmony_ci<h4>Introduction<span><a class="mark" href="#introduction_1" id="introduction_1">#</a></span><a aria-hidden="true" class="legacy" id="packages_introduction_1"></a></h4> 3951cb0ef41Sopenharmony_ci<p>Node.js will treat the following as <a href="esm.html">ES modules</a> when passed to <code>node</code> as the 3961cb0ef41Sopenharmony_ciinitial input, or when referenced by <code>import</code> statements or <code>import()</code> 3971cb0ef41Sopenharmony_ciexpressions:</p> 3981cb0ef41Sopenharmony_ci<ul> 3991cb0ef41Sopenharmony_ci<li> 4001cb0ef41Sopenharmony_ci<p>Files with an <code>.mjs</code> extension.</p> 4011cb0ef41Sopenharmony_ci</li> 4021cb0ef41Sopenharmony_ci<li> 4031cb0ef41Sopenharmony_ci<p>Files with a <code>.js</code> extension when the nearest parent <code>package.json</code> file 4041cb0ef41Sopenharmony_cicontains a top-level <a href="#type"><code>"type"</code></a> field with a value of <code>"module"</code>.</p> 4051cb0ef41Sopenharmony_ci</li> 4061cb0ef41Sopenharmony_ci<li> 4071cb0ef41Sopenharmony_ci<p>Strings passed in as an argument to <code>--eval</code>, or piped to <code>node</code> via <code>STDIN</code>, 4081cb0ef41Sopenharmony_ciwith the flag <code>--input-type=module</code>.</p> 4091cb0ef41Sopenharmony_ci</li> 4101cb0ef41Sopenharmony_ci</ul> 4111cb0ef41Sopenharmony_ci<p>Node.js will treat the following as <a href="modules.html">CommonJS</a> when passed to <code>node</code> as the 4121cb0ef41Sopenharmony_ciinitial input, or when referenced by <code>import</code> statements or <code>import()</code> 4131cb0ef41Sopenharmony_ciexpressions:</p> 4141cb0ef41Sopenharmony_ci<ul> 4151cb0ef41Sopenharmony_ci<li> 4161cb0ef41Sopenharmony_ci<p>Files with a <code>.cjs</code> extension.</p> 4171cb0ef41Sopenharmony_ci</li> 4181cb0ef41Sopenharmony_ci<li> 4191cb0ef41Sopenharmony_ci<p>Files with a <code>.js</code> extension when the nearest parent <code>package.json</code> file 4201cb0ef41Sopenharmony_cicontains a top-level field <a href="#type"><code>"type"</code></a> with a value of <code>"commonjs"</code>.</p> 4211cb0ef41Sopenharmony_ci</li> 4221cb0ef41Sopenharmony_ci<li> 4231cb0ef41Sopenharmony_ci<p>Strings passed in as an argument to <code>--eval</code> or <code>--print</code>, or piped to <code>node</code> 4241cb0ef41Sopenharmony_civia <code>STDIN</code>, with the flag <code>--input-type=commonjs</code>.</p> 4251cb0ef41Sopenharmony_ci</li> 4261cb0ef41Sopenharmony_ci</ul> 4271cb0ef41Sopenharmony_ci<p>Aside from these explicit cases, there are other cases where Node.js defaults to 4281cb0ef41Sopenharmony_cione module system or the other based on the value of the 4291cb0ef41Sopenharmony_ci<a href="cli.html#--experimental-default-typetype"><code>--experimental-default-type</code></a> flag:</p> 4301cb0ef41Sopenharmony_ci<ul> 4311cb0ef41Sopenharmony_ci<li> 4321cb0ef41Sopenharmony_ci<p>Files ending in <code>.js</code> or with no extension, if there is no <code>package.json</code> file 4331cb0ef41Sopenharmony_cipresent in the same folder or any parent folder.</p> 4341cb0ef41Sopenharmony_ci</li> 4351cb0ef41Sopenharmony_ci<li> 4361cb0ef41Sopenharmony_ci<p>Files ending in <code>.js</code> or with no extension, if the nearest parent 4371cb0ef41Sopenharmony_ci<code>package.json</code> field lacks a <code>"type"</code> field; unless the folder is inside a 4381cb0ef41Sopenharmony_ci<code>node_modules</code> folder. (Package scopes under <code>node_modules</code> are always treated 4391cb0ef41Sopenharmony_cias CommonJS when the <code>package.json</code> file lacks a <code>"type"</code> field, regardless 4401cb0ef41Sopenharmony_ciof <code>--experimental-default-type</code>, for backward compatibility.)</p> 4411cb0ef41Sopenharmony_ci</li> 4421cb0ef41Sopenharmony_ci<li> 4431cb0ef41Sopenharmony_ci<p>Strings passed in as an argument to <code>--eval</code> or piped to <code>node</code> via <code>STDIN</code>, 4441cb0ef41Sopenharmony_ciwhen <code>--input-type</code> is unspecified.</p> 4451cb0ef41Sopenharmony_ci</li> 4461cb0ef41Sopenharmony_ci</ul> 4471cb0ef41Sopenharmony_ci<p>This flag currently defaults to <code>"commonjs"</code>, but it may change in the future to 4481cb0ef41Sopenharmony_cidefault to <code>"module"</code>. For this reason it is best to be explicit wherever 4491cb0ef41Sopenharmony_cipossible; in particular, package authors should always include the <a href="#type"><code>"type"</code></a> 4501cb0ef41Sopenharmony_cifield in their <code>package.json</code> files, even in packages where all sources are 4511cb0ef41Sopenharmony_ciCommonJS. Being explicit about the <code>type</code> of the package will future-proof the 4521cb0ef41Sopenharmony_cipackage in case the default type of Node.js ever changes, and it will also make 4531cb0ef41Sopenharmony_cithings easier for build tools and loaders to determine how the files in the 4541cb0ef41Sopenharmony_cipackage should be interpreted.</p> 4551cb0ef41Sopenharmony_ci<h4>Modules loaders<span><a class="mark" href="#modules-loaders" id="modules-loaders">#</a></span><a aria-hidden="true" class="legacy" id="packages_modules_loaders"></a></h4> 4561cb0ef41Sopenharmony_ci<p>Node.js has two systems for resolving a specifier and loading modules.</p> 4571cb0ef41Sopenharmony_ci<p>There is the CommonJS module loader:</p> 4581cb0ef41Sopenharmony_ci<ul> 4591cb0ef41Sopenharmony_ci<li>It is fully synchronous.</li> 4601cb0ef41Sopenharmony_ci<li>It is responsible for handling <code>require()</code> calls.</li> 4611cb0ef41Sopenharmony_ci<li>It is monkey patchable.</li> 4621cb0ef41Sopenharmony_ci<li>It supports <a href="modules.html#folders-as-modules">folders as modules</a>.</li> 4631cb0ef41Sopenharmony_ci<li>When resolving a specifier, if no exact match is found, it will try to add 4641cb0ef41Sopenharmony_ciextensions (<code>.js</code>, <code>.json</code>, and finally <code>.node</code>) and then attempt to resolve 4651cb0ef41Sopenharmony_ci<a href="modules.html#folders-as-modules">folders as modules</a>.</li> 4661cb0ef41Sopenharmony_ci<li>It treats <code>.json</code> as JSON text files.</li> 4671cb0ef41Sopenharmony_ci<li><code>.node</code> files are interpreted as compiled addon modules loaded with 4681cb0ef41Sopenharmony_ci<code>process.dlopen()</code>.</li> 4691cb0ef41Sopenharmony_ci<li>It treats all files that lack <code>.json</code> or <code>.node</code> extensions as JavaScript 4701cb0ef41Sopenharmony_citext files.</li> 4711cb0ef41Sopenharmony_ci<li>It cannot be used to load ECMAScript modules (although it is possible to 4721cb0ef41Sopenharmony_ci<a href="modules.html#the-mjs-extension">load ECMASCript modules from CommonJS modules</a>). When used to load a 4731cb0ef41Sopenharmony_ciJavaScript text file that is not an ECMAScript module, it loads it as a 4741cb0ef41Sopenharmony_ciCommonJS module.</li> 4751cb0ef41Sopenharmony_ci</ul> 4761cb0ef41Sopenharmony_ci<p>There is the ECMAScript module loader:</p> 4771cb0ef41Sopenharmony_ci<ul> 4781cb0ef41Sopenharmony_ci<li>It is asynchronous.</li> 4791cb0ef41Sopenharmony_ci<li>It is responsible for handling <code>import</code> statements and <code>import()</code> expressions.</li> 4801cb0ef41Sopenharmony_ci<li>It is not monkey patchable, can be customized using <a href="esm.html#loaders">loader hooks</a>.</li> 4811cb0ef41Sopenharmony_ci<li>It does not support folders as modules, directory indexes (e.g. 4821cb0ef41Sopenharmony_ci<code>'./startup/index.js'</code>) must be fully specified.</li> 4831cb0ef41Sopenharmony_ci<li>It does no extension searching. A file extension must be provided 4841cb0ef41Sopenharmony_ciwhen the specifier is a relative or absolute file URL.</li> 4851cb0ef41Sopenharmony_ci<li>It can load JSON modules, but an import assertion is required.</li> 4861cb0ef41Sopenharmony_ci<li>It accepts only <code>.js</code>, <code>.mjs</code>, and <code>.cjs</code> extensions for JavaScript text 4871cb0ef41Sopenharmony_cifiles.</li> 4881cb0ef41Sopenharmony_ci<li>It can be used to load JavaScript CommonJS modules. Such modules 4891cb0ef41Sopenharmony_ciare passed through the <code>cjs-module-lexer</code> to try to identify named exports, 4901cb0ef41Sopenharmony_ciwhich are available if they can be determined through static analysis. 4911cb0ef41Sopenharmony_ciImported CommonJS modules have their URLs converted to absolute 4921cb0ef41Sopenharmony_cipaths and are then loaded via the CommonJS module loader.</li> 4931cb0ef41Sopenharmony_ci</ul> 4941cb0ef41Sopenharmony_ci<h4><code>package.json</code> and file extensions<span><a class="mark" href="#packagejson-and-file-extensions" id="packagejson-and-file-extensions">#</a></span><a aria-hidden="true" class="legacy" id="packages_package_json_and_file_extensions"></a></h4> 4951cb0ef41Sopenharmony_ci<p>Within a package, the <a href="#nodejs-packagejson-field-definitions"><code>package.json</code></a> <a href="#type"><code>"type"</code></a> field defines how 4961cb0ef41Sopenharmony_ciNode.js should interpret <code>.js</code> files. If a <code>package.json</code> file does not have a 4971cb0ef41Sopenharmony_ci<code>"type"</code> field, <code>.js</code> files are treated as <a href="modules.html">CommonJS</a>.</p> 4981cb0ef41Sopenharmony_ci<p>A <code>package.json</code> <code>"type"</code> value of <code>"module"</code> tells Node.js to interpret <code>.js</code> 4991cb0ef41Sopenharmony_cifiles within that package as using <a href="esm.html">ES module</a> syntax.</p> 5001cb0ef41Sopenharmony_ci<p>The <code>"type"</code> field applies not only to initial entry points (<code>node my-app.js</code>) 5011cb0ef41Sopenharmony_cibut also to files referenced by <code>import</code> statements and <code>import()</code> expressions.</p> 5021cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-comment">// my-app.js, treated as an ES module because there is a package.json</span> 5031cb0ef41Sopenharmony_ci<span class="hljs-comment">// file in the same folder with "type": "module".</span> 5041cb0ef41Sopenharmony_ci 5051cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> <span class="hljs-string">'./startup/init.js'</span>; 5061cb0ef41Sopenharmony_ci<span class="hljs-comment">// Loaded as ES module since ./startup contains no package.json file,</span> 5071cb0ef41Sopenharmony_ci<span class="hljs-comment">// and therefore inherits the "type" value from one level up.</span> 5081cb0ef41Sopenharmony_ci 5091cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> <span class="hljs-string">'commonjs-package'</span>; 5101cb0ef41Sopenharmony_ci<span class="hljs-comment">// Loaded as CommonJS since ./node_modules/commonjs-package/package.json</span> 5111cb0ef41Sopenharmony_ci<span class="hljs-comment">// lacks a "type" field or contains "type": "commonjs".</span> 5121cb0ef41Sopenharmony_ci 5131cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> <span class="hljs-string">'./node_modules/commonjs-package/index.js'</span>; 5141cb0ef41Sopenharmony_ci<span class="hljs-comment">// Loaded as CommonJS since ./node_modules/commonjs-package/package.json</span> 5151cb0ef41Sopenharmony_ci<span class="hljs-comment">// lacks a "type" field or contains "type": "commonjs".</span></code> <button class="copy-button">copy</button></pre> 5161cb0ef41Sopenharmony_ci<p>Files ending with <code>.mjs</code> are always loaded as <a href="esm.html">ES modules</a> regardless of 5171cb0ef41Sopenharmony_cithe nearest parent <code>package.json</code>.</p> 5181cb0ef41Sopenharmony_ci<p>Files ending with <code>.cjs</code> are always loaded as <a href="modules.html">CommonJS</a> regardless of the 5191cb0ef41Sopenharmony_cinearest parent <code>package.json</code>.</p> 5201cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">import</span> <span class="hljs-string">'./legacy-file.cjs'</span>; 5211cb0ef41Sopenharmony_ci<span class="hljs-comment">// Loaded as CommonJS since .cjs is always loaded as CommonJS.</span> 5221cb0ef41Sopenharmony_ci 5231cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> <span class="hljs-string">'commonjs-package/src/index.mjs'</span>; 5241cb0ef41Sopenharmony_ci<span class="hljs-comment">// Loaded as ES module since .mjs is always loaded as ES module.</span></code> <button class="copy-button">copy</button></pre> 5251cb0ef41Sopenharmony_ci<p>The <code>.mjs</code> and <code>.cjs</code> extensions can be used to mix types within the same 5261cb0ef41Sopenharmony_cipackage:</p> 5271cb0ef41Sopenharmony_ci<ul> 5281cb0ef41Sopenharmony_ci<li> 5291cb0ef41Sopenharmony_ci<p>Within a <code>"type": "module"</code> package, Node.js can be instructed to 5301cb0ef41Sopenharmony_ciinterpret a particular file as <a href="modules.html">CommonJS</a> by naming it with a <code>.cjs</code> 5311cb0ef41Sopenharmony_ciextension (since both <code>.js</code> and <code>.mjs</code> files are treated as ES modules within 5321cb0ef41Sopenharmony_cia <code>"module"</code> package).</p> 5331cb0ef41Sopenharmony_ci</li> 5341cb0ef41Sopenharmony_ci<li> 5351cb0ef41Sopenharmony_ci<p>Within a <code>"type": "commonjs"</code> package, Node.js can be instructed to 5361cb0ef41Sopenharmony_ciinterpret a particular file as an <a href="esm.html">ES module</a> by naming it with an <code>.mjs</code> 5371cb0ef41Sopenharmony_ciextension (since both <code>.js</code> and <code>.cjs</code> files are treated as CommonJS within a 5381cb0ef41Sopenharmony_ci<code>"commonjs"</code> package).</p> 5391cb0ef41Sopenharmony_ci</li> 5401cb0ef41Sopenharmony_ci</ul> 5411cb0ef41Sopenharmony_ci<h4><code>--input-type</code> flag<span><a class="mark" href="#--input-type-flag" id="--input-type-flag">#</a></span><a aria-hidden="true" class="legacy" id="packages_input_type_flag"></a></h4> 5421cb0ef41Sopenharmony_ci<div class="api_metadata"> 5431cb0ef41Sopenharmony_ci<span>Added in: v12.0.0</span> 5441cb0ef41Sopenharmony_ci</div> 5451cb0ef41Sopenharmony_ci<p>Strings passed in as an argument to <code>--eval</code> (or <code>-e</code>), or piped to <code>node</code> via 5461cb0ef41Sopenharmony_ci<code>STDIN</code>, are treated as <a href="esm.html">ES modules</a> when the <code>--input-type=module</code> flag 5471cb0ef41Sopenharmony_ciis set.</p> 5481cb0ef41Sopenharmony_ci<pre><code class="language-bash">node --input-type=module --<span class="hljs-built_in">eval</span> <span class="hljs-string">"import { sep } from 'node:path'; console.log(sep);"</span> 5491cb0ef41Sopenharmony_ci 5501cb0ef41Sopenharmony_ci<span class="hljs-built_in">echo</span> <span class="hljs-string">"import { sep } from 'node:path'; console.log(sep);"</span> | node --input-type=module</code> <button class="copy-button">copy</button></pre> 5511cb0ef41Sopenharmony_ci<p>For completeness there is also <code>--input-type=commonjs</code>, for explicitly running 5521cb0ef41Sopenharmony_cistring input as CommonJS. This is the default behavior if <code>--input-type</code> is 5531cb0ef41Sopenharmony_ciunspecified.</p> 5541cb0ef41Sopenharmony_ci</section><section><h3>Determining package manager<span><a class="mark" href="#determining-package-manager" id="determining-package-manager">#</a></span><a aria-hidden="true" class="legacy" id="packages_determining_package_manager"></a></h3> 5551cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - Experimental</div><p></p> 5561cb0ef41Sopenharmony_ci<p>While all Node.js projects are expected to be installable by all package 5571cb0ef41Sopenharmony_cimanagers once published, their development teams are often required to use one 5581cb0ef41Sopenharmony_cispecific package manager. To make this process easier, Node.js ships with a 5591cb0ef41Sopenharmony_citool called <a href="corepack.html">Corepack</a> that aims to make all package managers transparently 5601cb0ef41Sopenharmony_ciavailable in your environment - provided you have Node.js installed.</p> 5611cb0ef41Sopenharmony_ci<p>By default Corepack won't enforce any specific package manager and will use 5621cb0ef41Sopenharmony_cithe generic "Last Known Good" versions associated with each Node.js release, 5631cb0ef41Sopenharmony_cibut you can improve this experience by setting the <a href="#packagemanager"><code>"packageManager"</code></a> field 5641cb0ef41Sopenharmony_ciin your project's <code>package.json</code>.</p> 5651cb0ef41Sopenharmony_ci</section><section><h3>Package entry points<span><a class="mark" href="#package-entry-points" id="package-entry-points">#</a></span><a aria-hidden="true" class="legacy" id="packages_package_entry_points"></a></h3> 5661cb0ef41Sopenharmony_ci<p>In a package's <code>package.json</code> file, two fields can define entry points for a 5671cb0ef41Sopenharmony_cipackage: <a href="#main"><code>"main"</code></a> and <a href="#exports"><code>"exports"</code></a>. Both fields apply to both ES module 5681cb0ef41Sopenharmony_ciand CommonJS module entry points.</p> 5691cb0ef41Sopenharmony_ci<p>The <a href="#main"><code>"main"</code></a> field is supported in all versions of Node.js, but its 5701cb0ef41Sopenharmony_cicapabilities are limited: it only defines the main entry point of the package.</p> 5711cb0ef41Sopenharmony_ci<p>The <a href="#exports"><code>"exports"</code></a> provides a modern alternative to <a href="#main"><code>"main"</code></a> allowing 5721cb0ef41Sopenharmony_cimultiple entry points to be defined, conditional entry resolution support 5731cb0ef41Sopenharmony_cibetween environments, and <strong>preventing any other entry points besides those 5741cb0ef41Sopenharmony_cidefined in <a href="#exports"><code>"exports"</code></a></strong>. This encapsulation allows module authors to 5751cb0ef41Sopenharmony_ciclearly define the public interface for their package.</p> 5761cb0ef41Sopenharmony_ci<p>For new packages targeting the currently supported versions of Node.js, the 5771cb0ef41Sopenharmony_ci<a href="#exports"><code>"exports"</code></a> field is recommended. For packages supporting Node.js 10 and 5781cb0ef41Sopenharmony_cibelow, the <a href="#main"><code>"main"</code></a> field is required. If both <a href="#exports"><code>"exports"</code></a> and 5791cb0ef41Sopenharmony_ci<a href="#main"><code>"main"</code></a> are defined, the <a href="#exports"><code>"exports"</code></a> field takes precedence over 5801cb0ef41Sopenharmony_ci<a href="#main"><code>"main"</code></a> in supported versions of Node.js.</p> 5811cb0ef41Sopenharmony_ci<p><a href="#conditional-exports">Conditional exports</a> can be used within <a href="#exports"><code>"exports"</code></a> to define different 5821cb0ef41Sopenharmony_cipackage entry points per environment, including whether the package is 5831cb0ef41Sopenharmony_cireferenced via <code>require</code> or via <code>import</code>. For more information about supporting 5841cb0ef41Sopenharmony_ciboth CommonJS and ES modules in a single package please consult 5851cb0ef41Sopenharmony_ci<a href="#dual-commonjses-module-packages">the dual CommonJS/ES module packages section</a>.</p> 5861cb0ef41Sopenharmony_ci<p>Existing packages introducing the <a href="#exports"><code>"exports"</code></a> field will prevent consumers 5871cb0ef41Sopenharmony_ciof the package from using any entry points that are not defined, including the 5881cb0ef41Sopenharmony_ci<a href="#nodejs-packagejson-field-definitions"><code>package.json</code></a> (e.g. <code>require('your-package/package.json')</code>. <strong>This will 5891cb0ef41Sopenharmony_cilikely be a breaking change.</strong></p> 5901cb0ef41Sopenharmony_ci<p>To make the introduction of <a href="#exports"><code>"exports"</code></a> non-breaking, ensure that every 5911cb0ef41Sopenharmony_cipreviously supported entry point is exported. It is best to explicitly specify 5921cb0ef41Sopenharmony_cientry points so that the package's public API is well-defined. For example, 5931cb0ef41Sopenharmony_cia project that previously exported <code>main</code>, <code>lib</code>, 5941cb0ef41Sopenharmony_ci<code>feature</code>, and the <code>package.json</code> could use the following <code>package.exports</code>:</p> 5951cb0ef41Sopenharmony_ci<pre><code class="language-json"><span class="hljs-punctuation">{</span> 5961cb0ef41Sopenharmony_ci <span class="hljs-attr">"name"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"my-package"</span><span class="hljs-punctuation">,</span> 5971cb0ef41Sopenharmony_ci <span class="hljs-attr">"exports"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 5981cb0ef41Sopenharmony_ci <span class="hljs-attr">"."</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./lib/index.js"</span><span class="hljs-punctuation">,</span> 5991cb0ef41Sopenharmony_ci <span class="hljs-attr">"./lib"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./lib/index.js"</span><span class="hljs-punctuation">,</span> 6001cb0ef41Sopenharmony_ci <span class="hljs-attr">"./lib/index"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./lib/index.js"</span><span class="hljs-punctuation">,</span> 6011cb0ef41Sopenharmony_ci <span class="hljs-attr">"./lib/index.js"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./lib/index.js"</span><span class="hljs-punctuation">,</span> 6021cb0ef41Sopenharmony_ci <span class="hljs-attr">"./feature"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./feature/index.js"</span><span class="hljs-punctuation">,</span> 6031cb0ef41Sopenharmony_ci <span class="hljs-attr">"./feature/index"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./feature/index.js"</span><span class="hljs-punctuation">,</span> 6041cb0ef41Sopenharmony_ci <span class="hljs-attr">"./feature/index.js"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./feature/index.js"</span><span class="hljs-punctuation">,</span> 6051cb0ef41Sopenharmony_ci <span class="hljs-attr">"./package.json"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./package.json"</span> 6061cb0ef41Sopenharmony_ci <span class="hljs-punctuation">}</span> 6071cb0ef41Sopenharmony_ci<span class="hljs-punctuation">}</span></code> <button class="copy-button">copy</button></pre> 6081cb0ef41Sopenharmony_ci<p>Alternatively a project could choose to export entire folders both with and 6091cb0ef41Sopenharmony_ciwithout extensioned subpaths using export patterns:</p> 6101cb0ef41Sopenharmony_ci<pre><code class="language-json"><span class="hljs-punctuation">{</span> 6111cb0ef41Sopenharmony_ci <span class="hljs-attr">"name"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"my-package"</span><span class="hljs-punctuation">,</span> 6121cb0ef41Sopenharmony_ci <span class="hljs-attr">"exports"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 6131cb0ef41Sopenharmony_ci <span class="hljs-attr">"."</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./lib/index.js"</span><span class="hljs-punctuation">,</span> 6141cb0ef41Sopenharmony_ci <span class="hljs-attr">"./lib"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./lib/index.js"</span><span class="hljs-punctuation">,</span> 6151cb0ef41Sopenharmony_ci <span class="hljs-attr">"./lib/*"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./lib/*.js"</span><span class="hljs-punctuation">,</span> 6161cb0ef41Sopenharmony_ci <span class="hljs-attr">"./lib/*.js"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./lib/*.js"</span><span class="hljs-punctuation">,</span> 6171cb0ef41Sopenharmony_ci <span class="hljs-attr">"./feature"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./feature/index.js"</span><span class="hljs-punctuation">,</span> 6181cb0ef41Sopenharmony_ci <span class="hljs-attr">"./feature/*"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./feature/*.js"</span><span class="hljs-punctuation">,</span> 6191cb0ef41Sopenharmony_ci <span class="hljs-attr">"./feature/*.js"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./feature/*.js"</span><span class="hljs-punctuation">,</span> 6201cb0ef41Sopenharmony_ci <span class="hljs-attr">"./package.json"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./package.json"</span> 6211cb0ef41Sopenharmony_ci <span class="hljs-punctuation">}</span> 6221cb0ef41Sopenharmony_ci<span class="hljs-punctuation">}</span></code> <button class="copy-button">copy</button></pre> 6231cb0ef41Sopenharmony_ci<p>With the above providing backwards-compatibility for any minor package versions, 6241cb0ef41Sopenharmony_cia future major change for the package can then properly restrict the exports 6251cb0ef41Sopenharmony_cito only the specific feature exports exposed:</p> 6261cb0ef41Sopenharmony_ci<pre><code class="language-json"><span class="hljs-punctuation">{</span> 6271cb0ef41Sopenharmony_ci <span class="hljs-attr">"name"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"my-package"</span><span class="hljs-punctuation">,</span> 6281cb0ef41Sopenharmony_ci <span class="hljs-attr">"exports"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 6291cb0ef41Sopenharmony_ci <span class="hljs-attr">"."</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./lib/index.js"</span><span class="hljs-punctuation">,</span> 6301cb0ef41Sopenharmony_ci <span class="hljs-attr">"./feature/*.js"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./feature/*.js"</span><span class="hljs-punctuation">,</span> 6311cb0ef41Sopenharmony_ci <span class="hljs-attr">"./feature/internal/*"</span><span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">null</span></span> 6321cb0ef41Sopenharmony_ci <span class="hljs-punctuation">}</span> 6331cb0ef41Sopenharmony_ci<span class="hljs-punctuation">}</span></code> <button class="copy-button">copy</button></pre> 6341cb0ef41Sopenharmony_ci<h4>Main entry point export<span><a class="mark" href="#main-entry-point-export" id="main-entry-point-export">#</a></span><a aria-hidden="true" class="legacy" id="packages_main_entry_point_export"></a></h4> 6351cb0ef41Sopenharmony_ci<p>When writing a new package, it is recommended to use the <a href="#exports"><code>"exports"</code></a> field:</p> 6361cb0ef41Sopenharmony_ci<pre><code class="language-json"><span class="hljs-punctuation">{</span> 6371cb0ef41Sopenharmony_ci <span class="hljs-attr">"exports"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./index.js"</span> 6381cb0ef41Sopenharmony_ci<span class="hljs-punctuation">}</span></code> <button class="copy-button">copy</button></pre> 6391cb0ef41Sopenharmony_ci<p>When the <a href="#exports"><code>"exports"</code></a> field is defined, all subpaths of the package are 6401cb0ef41Sopenharmony_ciencapsulated and no longer available to importers. For example, 6411cb0ef41Sopenharmony_ci<code>require('pkg/subpath.js')</code> throws an <a href="errors.html#err_package_path_not_exported"><code>ERR_PACKAGE_PATH_NOT_EXPORTED</code></a> 6421cb0ef41Sopenharmony_cierror.</p> 6431cb0ef41Sopenharmony_ci<p>This encapsulation of exports provides more reliable guarantees 6441cb0ef41Sopenharmony_ciabout package interfaces for tools and when handling semver upgrades for a 6451cb0ef41Sopenharmony_cipackage. It is not a strong encapsulation since a direct require of any 6461cb0ef41Sopenharmony_ciabsolute subpath of the package such as 6471cb0ef41Sopenharmony_ci<code>require('/path/to/node_modules/pkg/subpath.js')</code> will still load <code>subpath.js</code>.</p> 6481cb0ef41Sopenharmony_ci<p>All currently supported versions of Node.js and modern build tools support the 6491cb0ef41Sopenharmony_ci<code>"exports"</code> field. For projects using an older version of Node.js or a related 6501cb0ef41Sopenharmony_cibuild tool, compatibility can be achieved by including the <code>"main"</code> field 6511cb0ef41Sopenharmony_cialongside <code>"exports"</code> pointing to the same module:</p> 6521cb0ef41Sopenharmony_ci<pre><code class="language-json"><span class="hljs-punctuation">{</span> 6531cb0ef41Sopenharmony_ci <span class="hljs-attr">"main"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./index.js"</span><span class="hljs-punctuation">,</span> 6541cb0ef41Sopenharmony_ci <span class="hljs-attr">"exports"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./index.js"</span> 6551cb0ef41Sopenharmony_ci<span class="hljs-punctuation">}</span></code> <button class="copy-button">copy</button></pre> 6561cb0ef41Sopenharmony_ci<h4>Subpath exports<span><a class="mark" href="#subpath-exports" id="subpath-exports">#</a></span><a aria-hidden="true" class="legacy" id="packages_subpath_exports"></a></h4> 6571cb0ef41Sopenharmony_ci<div class="api_metadata"> 6581cb0ef41Sopenharmony_ci<span>Added in: v12.7.0</span> 6591cb0ef41Sopenharmony_ci</div> 6601cb0ef41Sopenharmony_ci<p>When using the <a href="#exports"><code>"exports"</code></a> field, custom subpaths can be defined along 6611cb0ef41Sopenharmony_ciwith the main entry point by treating the main entry point as the 6621cb0ef41Sopenharmony_ci<code>"."</code> subpath:</p> 6631cb0ef41Sopenharmony_ci<pre><code class="language-json"><span class="hljs-punctuation">{</span> 6641cb0ef41Sopenharmony_ci <span class="hljs-attr">"exports"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 6651cb0ef41Sopenharmony_ci <span class="hljs-attr">"."</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./index.js"</span><span class="hljs-punctuation">,</span> 6661cb0ef41Sopenharmony_ci <span class="hljs-attr">"./submodule.js"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./src/submodule.js"</span> 6671cb0ef41Sopenharmony_ci <span class="hljs-punctuation">}</span> 6681cb0ef41Sopenharmony_ci<span class="hljs-punctuation">}</span></code> <button class="copy-button">copy</button></pre> 6691cb0ef41Sopenharmony_ci<p>Now only the defined subpath in <a href="#exports"><code>"exports"</code></a> can be imported by a consumer:</p> 6701cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">import</span> submodule <span class="hljs-keyword">from</span> <span class="hljs-string">'es-module-package/submodule.js'</span>; 6711cb0ef41Sopenharmony_ci<span class="hljs-comment">// Loads ./node_modules/es-module-package/src/submodule.js</span></code> <button class="copy-button">copy</button></pre> 6721cb0ef41Sopenharmony_ci<p>While other subpaths will error:</p> 6731cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">import</span> submodule <span class="hljs-keyword">from</span> <span class="hljs-string">'es-module-package/private-module.js'</span>; 6741cb0ef41Sopenharmony_ci<span class="hljs-comment">// Throws ERR_PACKAGE_PATH_NOT_EXPORTED</span></code> <button class="copy-button">copy</button></pre> 6751cb0ef41Sopenharmony_ci<h5>Extensions in subpaths<span><a class="mark" href="#extensions-in-subpaths" id="extensions-in-subpaths">#</a></span><a aria-hidden="true" class="legacy" id="packages_extensions_in_subpaths"></a></h5> 6761cb0ef41Sopenharmony_ci<p>Package authors should provide either extensioned (<code>import 'pkg/subpath.js'</code>) or 6771cb0ef41Sopenharmony_ciextensionless (<code>import 'pkg/subpath'</code>) subpaths in their exports. This ensures 6781cb0ef41Sopenharmony_cithat there is only one subpath for each exported module so that all dependents 6791cb0ef41Sopenharmony_ciimport the same consistent specifier, keeping the package contract clear for 6801cb0ef41Sopenharmony_ciconsumers and simplifying package subpath completions.</p> 6811cb0ef41Sopenharmony_ci<p>Traditionally, packages tended to use the extensionless style, which has the 6821cb0ef41Sopenharmony_cibenefits of readability and of masking the true path of the file within the 6831cb0ef41Sopenharmony_cipackage.</p> 6841cb0ef41Sopenharmony_ci<p>With <a href="https://github.com/WICG/import-maps">import maps</a> now providing a standard for package resolution in browsers 6851cb0ef41Sopenharmony_ciand other JavaScript runtimes, using the extensionless style can result in 6861cb0ef41Sopenharmony_cibloated import map definitions. Explicit file extensions can avoid this issue by 6871cb0ef41Sopenharmony_cienabling the import map to utilize a <a href="https://github.com/WICG/import-maps#packages-via-trailing-slashes">packages folder mapping</a> to map multiple 6881cb0ef41Sopenharmony_cisubpaths where possible instead of a separate map entry per package subpath 6891cb0ef41Sopenharmony_ciexport. This also mirrors the requirement of using <a href="esm.html#mandatory-file-extensions">the full specifier path</a> 6901cb0ef41Sopenharmony_ciin relative and absolute import specifiers.</p> 6911cb0ef41Sopenharmony_ci<h4>Exports sugar<span><a class="mark" href="#exports-sugar" id="exports-sugar">#</a></span><a aria-hidden="true" class="legacy" id="packages_exports_sugar"></a></h4> 6921cb0ef41Sopenharmony_ci<div class="api_metadata"> 6931cb0ef41Sopenharmony_ci<span>Added in: v12.11.0</span> 6941cb0ef41Sopenharmony_ci</div> 6951cb0ef41Sopenharmony_ci<p>If the <code>"."</code> export is the only export, the <a href="#exports"><code>"exports"</code></a> field provides sugar 6961cb0ef41Sopenharmony_cifor this case being the direct <a href="#exports"><code>"exports"</code></a> field value.</p> 6971cb0ef41Sopenharmony_ci<pre><code class="language-json"><span class="hljs-punctuation">{</span> 6981cb0ef41Sopenharmony_ci <span class="hljs-attr">"exports"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 6991cb0ef41Sopenharmony_ci <span class="hljs-attr">"."</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./index.js"</span> 7001cb0ef41Sopenharmony_ci <span class="hljs-punctuation">}</span> 7011cb0ef41Sopenharmony_ci<span class="hljs-punctuation">}</span></code> <button class="copy-button">copy</button></pre> 7021cb0ef41Sopenharmony_ci<p>can be written:</p> 7031cb0ef41Sopenharmony_ci<pre><code class="language-json"><span class="hljs-punctuation">{</span> 7041cb0ef41Sopenharmony_ci <span class="hljs-attr">"exports"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./index.js"</span> 7051cb0ef41Sopenharmony_ci<span class="hljs-punctuation">}</span></code> <button class="copy-button">copy</button></pre> 7061cb0ef41Sopenharmony_ci<h4>Subpath imports<span><a class="mark" href="#subpath-imports" id="subpath-imports">#</a></span><a aria-hidden="true" class="legacy" id="packages_subpath_imports"></a></h4> 7071cb0ef41Sopenharmony_ci<div class="api_metadata"> 7081cb0ef41Sopenharmony_ci<span>Added in: v14.6.0, v12.19.0</span> 7091cb0ef41Sopenharmony_ci</div> 7101cb0ef41Sopenharmony_ci<p>In addition to the <a href="#exports"><code>"exports"</code></a> field, there is a package <code>"imports"</code> field 7111cb0ef41Sopenharmony_cito create private mappings that only apply to import specifiers from within the 7121cb0ef41Sopenharmony_cipackage itself.</p> 7131cb0ef41Sopenharmony_ci<p>Entries in the <code>"imports"</code> field must always start with <code>#</code> to ensure they are 7141cb0ef41Sopenharmony_cidisambiguated from external package specifiers.</p> 7151cb0ef41Sopenharmony_ci<p>For example, the imports field can be used to gain the benefits of conditional 7161cb0ef41Sopenharmony_ciexports for internal modules:</p> 7171cb0ef41Sopenharmony_ci<pre><code class="language-json"><span class="hljs-comment">// package.json</span> 7181cb0ef41Sopenharmony_ci<span class="hljs-punctuation">{</span> 7191cb0ef41Sopenharmony_ci <span class="hljs-attr">"imports"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 7201cb0ef41Sopenharmony_ci <span class="hljs-attr">"#dep"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 7211cb0ef41Sopenharmony_ci <span class="hljs-attr">"node"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"dep-node-native"</span><span class="hljs-punctuation">,</span> 7221cb0ef41Sopenharmony_ci <span class="hljs-attr">"default"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./dep-polyfill.js"</span> 7231cb0ef41Sopenharmony_ci <span class="hljs-punctuation">}</span> 7241cb0ef41Sopenharmony_ci <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span> 7251cb0ef41Sopenharmony_ci <span class="hljs-attr">"dependencies"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 7261cb0ef41Sopenharmony_ci <span class="hljs-attr">"dep-node-native"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"^1.0.0"</span> 7271cb0ef41Sopenharmony_ci <span class="hljs-punctuation">}</span> 7281cb0ef41Sopenharmony_ci<span class="hljs-punctuation">}</span></code> <button class="copy-button">copy</button></pre> 7291cb0ef41Sopenharmony_ci<p>where <code>import '#dep'</code> does not get the resolution of the external package 7301cb0ef41Sopenharmony_ci<code>dep-node-native</code> (including its exports in turn), and instead gets the local 7311cb0ef41Sopenharmony_cifile <code>./dep-polyfill.js</code> relative to the package in other environments.</p> 7321cb0ef41Sopenharmony_ci<p>Unlike the <code>"exports"</code> field, the <code>"imports"</code> field permits mapping to external 7331cb0ef41Sopenharmony_cipackages.</p> 7341cb0ef41Sopenharmony_ci<p>The resolution rules for the imports field are otherwise analogous to the 7351cb0ef41Sopenharmony_ciexports field.</p> 7361cb0ef41Sopenharmony_ci<h4>Subpath patterns<span><a class="mark" href="#subpath-patterns" id="subpath-patterns">#</a></span><a aria-hidden="true" class="legacy" id="packages_subpath_patterns"></a></h4> 7371cb0ef41Sopenharmony_ci<div class="api_metadata"> 7381cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 7391cb0ef41Sopenharmony_ci<table> 7401cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 7411cb0ef41Sopenharmony_ci<tr><td>v16.10.0, v14.19.0</td> 7421cb0ef41Sopenharmony_ci<td><p>Support pattern trailers in "imports" field.</p></td></tr> 7431cb0ef41Sopenharmony_ci<tr><td>v16.9.0, v14.19.0</td> 7441cb0ef41Sopenharmony_ci<td><p>Support pattern trailers.</p></td></tr> 7451cb0ef41Sopenharmony_ci<tr><td>v14.13.0, v12.20.0</td> 7461cb0ef41Sopenharmony_ci<td><p><span>Added in: v14.13.0, v12.20.0</span></p></td></tr> 7471cb0ef41Sopenharmony_ci</tbody></table> 7481cb0ef41Sopenharmony_ci</details> 7491cb0ef41Sopenharmony_ci</div> 7501cb0ef41Sopenharmony_ci<p>For packages with a small number of exports or imports, we recommend 7511cb0ef41Sopenharmony_ciexplicitly listing each exports subpath entry. But for packages that have 7521cb0ef41Sopenharmony_cilarge numbers of subpaths, this might cause <code>package.json</code> bloat and 7531cb0ef41Sopenharmony_cimaintenance issues.</p> 7541cb0ef41Sopenharmony_ci<p>For these use cases, subpath export patterns can be used instead:</p> 7551cb0ef41Sopenharmony_ci<pre><code class="language-json"><span class="hljs-comment">// ./node_modules/es-module-package/package.json</span> 7561cb0ef41Sopenharmony_ci<span class="hljs-punctuation">{</span> 7571cb0ef41Sopenharmony_ci <span class="hljs-attr">"exports"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 7581cb0ef41Sopenharmony_ci <span class="hljs-attr">"./features/*.js"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./src/features/*.js"</span> 7591cb0ef41Sopenharmony_ci <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span> 7601cb0ef41Sopenharmony_ci <span class="hljs-attr">"imports"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 7611cb0ef41Sopenharmony_ci <span class="hljs-attr">"#internal/*.js"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./src/internal/*.js"</span> 7621cb0ef41Sopenharmony_ci <span class="hljs-punctuation">}</span> 7631cb0ef41Sopenharmony_ci<span class="hljs-punctuation">}</span></code> <button class="copy-button">copy</button></pre> 7641cb0ef41Sopenharmony_ci<p><strong><code>*</code> maps expose nested subpaths as it is a string replacement syntax 7651cb0ef41Sopenharmony_cionly.</strong></p> 7661cb0ef41Sopenharmony_ci<p>All instances of <code>*</code> on the right hand side will then be replaced with this 7671cb0ef41Sopenharmony_civalue, including if it contains any <code>/</code> separators.</p> 7681cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">import</span> featureX <span class="hljs-keyword">from</span> <span class="hljs-string">'es-module-package/features/x.js'</span>; 7691cb0ef41Sopenharmony_ci<span class="hljs-comment">// Loads ./node_modules/es-module-package/src/features/x.js</span> 7701cb0ef41Sopenharmony_ci 7711cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> featureY <span class="hljs-keyword">from</span> <span class="hljs-string">'es-module-package/features/y/y.js'</span>; 7721cb0ef41Sopenharmony_ci<span class="hljs-comment">// Loads ./node_modules/es-module-package/src/features/y/y.js</span> 7731cb0ef41Sopenharmony_ci 7741cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> internalZ <span class="hljs-keyword">from</span> <span class="hljs-string">'#internal/z.js'</span>; 7751cb0ef41Sopenharmony_ci<span class="hljs-comment">// Loads ./node_modules/es-module-package/src/internal/z.js</span></code> <button class="copy-button">copy</button></pre> 7761cb0ef41Sopenharmony_ci<p>This is a direct static matching and replacement without any special handling 7771cb0ef41Sopenharmony_cifor file extensions. Including the <code>"*.js"</code> on both sides of the mapping 7781cb0ef41Sopenharmony_cirestricts the exposed package exports to only JS files.</p> 7791cb0ef41Sopenharmony_ci<p>The property of exports being statically enumerable is maintained with exports 7801cb0ef41Sopenharmony_cipatterns since the individual exports for a package can be determined by 7811cb0ef41Sopenharmony_citreating the right hand side target pattern as a <code>**</code> glob against the list of 7821cb0ef41Sopenharmony_cifiles within the package. Because <code>node_modules</code> paths are forbidden in exports 7831cb0ef41Sopenharmony_citargets, this expansion is dependent on only the files of the package itself.</p> 7841cb0ef41Sopenharmony_ci<p>To exclude private subfolders from patterns, <code>null</code> targets can be used:</p> 7851cb0ef41Sopenharmony_ci<pre><code class="language-json"><span class="hljs-comment">// ./node_modules/es-module-package/package.json</span> 7861cb0ef41Sopenharmony_ci<span class="hljs-punctuation">{</span> 7871cb0ef41Sopenharmony_ci <span class="hljs-attr">"exports"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 7881cb0ef41Sopenharmony_ci <span class="hljs-attr">"./features/*.js"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./src/features/*.js"</span><span class="hljs-punctuation">,</span> 7891cb0ef41Sopenharmony_ci <span class="hljs-attr">"./features/private-internal/*"</span><span class="hljs-punctuation">:</span> <span class="hljs-literal"><span class="hljs-keyword">null</span></span> 7901cb0ef41Sopenharmony_ci <span class="hljs-punctuation">}</span> 7911cb0ef41Sopenharmony_ci<span class="hljs-punctuation">}</span></code> <button class="copy-button">copy</button></pre> 7921cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">import</span> featureInternal <span class="hljs-keyword">from</span> <span class="hljs-string">'es-module-package/features/private-internal/m.js'</span>; 7931cb0ef41Sopenharmony_ci<span class="hljs-comment">// Throws: ERR_PACKAGE_PATH_NOT_EXPORTED</span> 7941cb0ef41Sopenharmony_ci 7951cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> featureX <span class="hljs-keyword">from</span> <span class="hljs-string">'es-module-package/features/x.js'</span>; 7961cb0ef41Sopenharmony_ci<span class="hljs-comment">// Loads ./node_modules/es-module-package/src/features/x.js</span></code> <button class="copy-button">copy</button></pre> 7971cb0ef41Sopenharmony_ci<h4>Conditional exports<span><a class="mark" href="#conditional-exports" id="conditional-exports">#</a></span><a aria-hidden="true" class="legacy" id="packages_conditional_exports"></a></h4> 7981cb0ef41Sopenharmony_ci<div class="api_metadata"> 7991cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 8001cb0ef41Sopenharmony_ci<table> 8011cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 8021cb0ef41Sopenharmony_ci<tr><td>v13.7.0, v12.16.0</td> 8031cb0ef41Sopenharmony_ci<td><p>Unflag conditional exports.</p></td></tr> 8041cb0ef41Sopenharmony_ci<tr><td>v13.2.0, v12.16.0</td> 8051cb0ef41Sopenharmony_ci<td><p><span>Added in: v13.2.0, v12.16.0</span></p></td></tr> 8061cb0ef41Sopenharmony_ci</tbody></table> 8071cb0ef41Sopenharmony_ci</details> 8081cb0ef41Sopenharmony_ci</div> 8091cb0ef41Sopenharmony_ci<p>Conditional exports provide a way to map to different paths depending on 8101cb0ef41Sopenharmony_cicertain conditions. They are supported for both CommonJS and ES module imports.</p> 8111cb0ef41Sopenharmony_ci<p>For example, a package that wants to provide different ES module exports for 8121cb0ef41Sopenharmony_ci<code>require()</code> and <code>import</code> can be written:</p> 8131cb0ef41Sopenharmony_ci<pre><code class="language-json"><span class="hljs-comment">// package.json</span> 8141cb0ef41Sopenharmony_ci<span class="hljs-punctuation">{</span> 8151cb0ef41Sopenharmony_ci <span class="hljs-attr">"exports"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 8161cb0ef41Sopenharmony_ci <span class="hljs-attr">"import"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./index-module.js"</span><span class="hljs-punctuation">,</span> 8171cb0ef41Sopenharmony_ci <span class="hljs-attr">"require"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./index-require.cjs"</span> 8181cb0ef41Sopenharmony_ci <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span> 8191cb0ef41Sopenharmony_ci <span class="hljs-attr">"type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"module"</span> 8201cb0ef41Sopenharmony_ci<span class="hljs-punctuation">}</span></code> <button class="copy-button">copy</button></pre> 8211cb0ef41Sopenharmony_ci<p>Node.js implements the following conditions, listed in order from most 8221cb0ef41Sopenharmony_cispecific to least specific as conditions should be defined:</p> 8231cb0ef41Sopenharmony_ci<ul> 8241cb0ef41Sopenharmony_ci<li><code>"node-addons"</code> - similar to <code>"node"</code> and matches for any Node.js environment. 8251cb0ef41Sopenharmony_ciThis condition can be used to provide an entry point which uses native C++ 8261cb0ef41Sopenharmony_ciaddons as opposed to an entry point which is more universal and doesn't rely 8271cb0ef41Sopenharmony_cion native addons. This condition can be disabled via the 8281cb0ef41Sopenharmony_ci<a href="cli.html#--no-addons"><code>--no-addons</code> flag</a>.</li> 8291cb0ef41Sopenharmony_ci<li><code>"node"</code> - matches for any Node.js environment. Can be a CommonJS or ES 8301cb0ef41Sopenharmony_cimodule file. <em>In most cases explicitly calling out the Node.js platform is 8311cb0ef41Sopenharmony_cinot necessary.</em></li> 8321cb0ef41Sopenharmony_ci<li><code>"import"</code> - matches when the package is loaded via <code>import</code> or 8331cb0ef41Sopenharmony_ci<code>import()</code>, or via any top-level import or resolve operation by the 8341cb0ef41Sopenharmony_ciECMAScript module loader. Applies regardless of the module format of the 8351cb0ef41Sopenharmony_citarget file. <em>Always mutually exclusive with <code>"require"</code>.</em></li> 8361cb0ef41Sopenharmony_ci<li><code>"require"</code> - matches when the package is loaded via <code>require()</code>. The 8371cb0ef41Sopenharmony_cireferenced file should be loadable with <code>require()</code> although the condition 8381cb0ef41Sopenharmony_cimatches regardless of the module format of the target file. Expected 8391cb0ef41Sopenharmony_ciformats include CommonJS, JSON, and native addons but not ES modules as 8401cb0ef41Sopenharmony_ci<code>require()</code> doesn't support them. <em>Always mutually exclusive with 8411cb0ef41Sopenharmony_ci<code>"import"</code>.</em></li> 8421cb0ef41Sopenharmony_ci<li><code>"default"</code> - the generic fallback that always matches. Can be a CommonJS 8431cb0ef41Sopenharmony_cior ES module file. <em>This condition should always come last.</em></li> 8441cb0ef41Sopenharmony_ci</ul> 8451cb0ef41Sopenharmony_ci<p>Within the <a href="#exports"><code>"exports"</code></a> object, key order is significant. During condition 8461cb0ef41Sopenharmony_cimatching, earlier entries have higher priority and take precedence over later 8471cb0ef41Sopenharmony_cientries. <em>The general rule is that conditions should be from most specific to 8481cb0ef41Sopenharmony_cileast specific in object order</em>.</p> 8491cb0ef41Sopenharmony_ci<p>Using the <code>"import"</code> and <code>"require"</code> conditions can lead to some hazards, 8501cb0ef41Sopenharmony_ciwhich are further explained in <a href="#dual-commonjses-module-packages">the dual CommonJS/ES module packages section</a>.</p> 8511cb0ef41Sopenharmony_ci<p>The <code>"node-addons"</code> condition can be used to provide an entry point which 8521cb0ef41Sopenharmony_ciuses native C++ addons. However, this condition can be disabled via the 8531cb0ef41Sopenharmony_ci<a href="cli.html#--no-addons"><code>--no-addons</code> flag</a>. When using <code>"node-addons"</code>, it's recommended to treat 8541cb0ef41Sopenharmony_ci<code>"default"</code> as an enhancement that provides a more universal entry point, e.g. 8551cb0ef41Sopenharmony_ciusing WebAssembly instead of a native addon.</p> 8561cb0ef41Sopenharmony_ci<p>Conditional exports can also be extended to exports subpaths, for example:</p> 8571cb0ef41Sopenharmony_ci<pre><code class="language-json"><span class="hljs-punctuation">{</span> 8581cb0ef41Sopenharmony_ci <span class="hljs-attr">"exports"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 8591cb0ef41Sopenharmony_ci <span class="hljs-attr">"."</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./index.js"</span><span class="hljs-punctuation">,</span> 8601cb0ef41Sopenharmony_ci <span class="hljs-attr">"./feature.js"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 8611cb0ef41Sopenharmony_ci <span class="hljs-attr">"node"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./feature-node.js"</span><span class="hljs-punctuation">,</span> 8621cb0ef41Sopenharmony_ci <span class="hljs-attr">"default"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./feature.js"</span> 8631cb0ef41Sopenharmony_ci <span class="hljs-punctuation">}</span> 8641cb0ef41Sopenharmony_ci <span class="hljs-punctuation">}</span> 8651cb0ef41Sopenharmony_ci<span class="hljs-punctuation">}</span></code> <button class="copy-button">copy</button></pre> 8661cb0ef41Sopenharmony_ci<p>Defines a package where <code>require('pkg/feature.js')</code> and 8671cb0ef41Sopenharmony_ci<code>import 'pkg/feature.js'</code> could provide different implementations between 8681cb0ef41Sopenharmony_ciNode.js and other JS environments.</p> 8691cb0ef41Sopenharmony_ci<p>When using environment branches, always include a <code>"default"</code> condition where 8701cb0ef41Sopenharmony_cipossible. Providing a <code>"default"</code> condition ensures that any unknown JS 8711cb0ef41Sopenharmony_cienvironments are able to use this universal implementation, which helps avoid 8721cb0ef41Sopenharmony_cithese JS environments from having to pretend to be existing environments in 8731cb0ef41Sopenharmony_ciorder to support packages with conditional exports. For this reason, using 8741cb0ef41Sopenharmony_ci<code>"node"</code> and <code>"default"</code> condition branches is usually preferable to using 8751cb0ef41Sopenharmony_ci<code>"node"</code> and <code>"browser"</code> condition branches.</p> 8761cb0ef41Sopenharmony_ci<h4>Nested conditions<span><a class="mark" href="#nested-conditions" id="nested-conditions">#</a></span><a aria-hidden="true" class="legacy" id="packages_nested_conditions"></a></h4> 8771cb0ef41Sopenharmony_ci<p>In addition to direct mappings, Node.js also supports nested condition objects.</p> 8781cb0ef41Sopenharmony_ci<p>For example, to define a package that only has dual mode entry points for 8791cb0ef41Sopenharmony_ciuse in Node.js but not the browser:</p> 8801cb0ef41Sopenharmony_ci<pre><code class="language-json"><span class="hljs-punctuation">{</span> 8811cb0ef41Sopenharmony_ci <span class="hljs-attr">"exports"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 8821cb0ef41Sopenharmony_ci <span class="hljs-attr">"node"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 8831cb0ef41Sopenharmony_ci <span class="hljs-attr">"import"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./feature-node.mjs"</span><span class="hljs-punctuation">,</span> 8841cb0ef41Sopenharmony_ci <span class="hljs-attr">"require"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./feature-node.cjs"</span> 8851cb0ef41Sopenharmony_ci <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span> 8861cb0ef41Sopenharmony_ci <span class="hljs-attr">"default"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./feature.mjs"</span> 8871cb0ef41Sopenharmony_ci <span class="hljs-punctuation">}</span> 8881cb0ef41Sopenharmony_ci<span class="hljs-punctuation">}</span></code> <button class="copy-button">copy</button></pre> 8891cb0ef41Sopenharmony_ci<p>Conditions continue to be matched in order as with flat conditions. If 8901cb0ef41Sopenharmony_cia nested condition does not have any mapping it will continue checking 8911cb0ef41Sopenharmony_cithe remaining conditions of the parent condition. In this way nested 8921cb0ef41Sopenharmony_ciconditions behave analogously to nested JavaScript <code>if</code> statements.</p> 8931cb0ef41Sopenharmony_ci<h4>Resolving user conditions<span><a class="mark" href="#resolving-user-conditions" id="resolving-user-conditions">#</a></span><a aria-hidden="true" class="legacy" id="packages_resolving_user_conditions"></a></h4> 8941cb0ef41Sopenharmony_ci<div class="api_metadata"> 8951cb0ef41Sopenharmony_ci<span>Added in: v14.9.0, v12.19.0</span> 8961cb0ef41Sopenharmony_ci</div> 8971cb0ef41Sopenharmony_ci<p>When running Node.js, custom user conditions can be added with the 8981cb0ef41Sopenharmony_ci<code>--conditions</code> flag:</p> 8991cb0ef41Sopenharmony_ci<pre><code class="language-bash">node --conditions=development index.js</code> <button class="copy-button">copy</button></pre> 9001cb0ef41Sopenharmony_ci<p>which would then resolve the <code>"development"</code> condition in package imports and 9011cb0ef41Sopenharmony_ciexports, while resolving the existing <code>"node"</code>, <code>"node-addons"</code>, <code>"default"</code>, 9021cb0ef41Sopenharmony_ci<code>"import"</code>, and <code>"require"</code> conditions as appropriate.</p> 9031cb0ef41Sopenharmony_ci<p>Any number of custom conditions can be set with repeat flags.</p> 9041cb0ef41Sopenharmony_ci<h4>Community Conditions Definitions<span><a class="mark" href="#community-conditions-definitions" id="community-conditions-definitions">#</a></span><a aria-hidden="true" class="legacy" id="packages_community_conditions_definitions"></a></h4> 9051cb0ef41Sopenharmony_ci<p>Condition strings other than the <code>"import"</code>, <code>"require"</code>, <code>"node"</code>, 9061cb0ef41Sopenharmony_ci<code>"node-addons"</code> and <code>"default"</code> conditions 9071cb0ef41Sopenharmony_ci<a href="#conditional-exports">implemented in Node.js core</a> are ignored by default.</p> 9081cb0ef41Sopenharmony_ci<p>Other platforms may implement other conditions and user conditions can be 9091cb0ef41Sopenharmony_cienabled in Node.js via the <a href="#resolving-user-conditions"><code>--conditions</code> / <code>-C</code> flag</a>.</p> 9101cb0ef41Sopenharmony_ci<p>Since custom package conditions require clear definitions to ensure correct 9111cb0ef41Sopenharmony_ciusage, a list of common known package conditions and their strict definitions 9121cb0ef41Sopenharmony_ciis provided below to assist with ecosystem coordination.</p> 9131cb0ef41Sopenharmony_ci<ul> 9141cb0ef41Sopenharmony_ci<li><code>"types"</code> - can be used by typing systems to resolve the typing file for 9151cb0ef41Sopenharmony_cithe given export. <em>This condition should always be included first.</em></li> 9161cb0ef41Sopenharmony_ci<li><code>"browser"</code> - any web browser environment.</li> 9171cb0ef41Sopenharmony_ci<li><code>"development"</code> - can be used to define a development-only environment 9181cb0ef41Sopenharmony_cientry point, for example to provide additional debugging context such as 9191cb0ef41Sopenharmony_cibetter error messages when running in a development mode. <em>Must always be 9201cb0ef41Sopenharmony_cimutually exclusive with <code>"production"</code>.</em></li> 9211cb0ef41Sopenharmony_ci<li><code>"production"</code> - can be used to define a production environment entry 9221cb0ef41Sopenharmony_cipoint. <em>Must always be mutually exclusive with <code>"development"</code>.</em></li> 9231cb0ef41Sopenharmony_ci</ul> 9241cb0ef41Sopenharmony_ci<p>For other runtimes, platform-specific condition key definitions are maintained 9251cb0ef41Sopenharmony_ciby the <a href="https://wintercg.org/">WinterCG</a> in the <a href="https://runtime-keys.proposal.wintercg.org/">Runtime Keys</a> proposal specification.</p> 9261cb0ef41Sopenharmony_ci<p>New conditions definitions may be added to this list by creating a pull request 9271cb0ef41Sopenharmony_cito the <a href="https://github.com/nodejs/node/blob/HEAD/doc/api/packages.md#conditions-definitions">Node.js documentation for this section</a>. The requirements for listing 9281cb0ef41Sopenharmony_cia new condition definition here are that:</p> 9291cb0ef41Sopenharmony_ci<ul> 9301cb0ef41Sopenharmony_ci<li>The definition should be clear and unambiguous for all implementers.</li> 9311cb0ef41Sopenharmony_ci<li>The use case for why the condition is needed should be clearly justified.</li> 9321cb0ef41Sopenharmony_ci<li>There should exist sufficient existing implementation usage.</li> 9331cb0ef41Sopenharmony_ci<li>The condition name should not conflict with another condition definition or 9341cb0ef41Sopenharmony_cicondition in wide usage.</li> 9351cb0ef41Sopenharmony_ci<li>The listing of the condition definition should provide a coordination 9361cb0ef41Sopenharmony_cibenefit to the ecosystem that wouldn't otherwise be possible. For example, 9371cb0ef41Sopenharmony_cithis would not necessarily be the case for company-specific or 9381cb0ef41Sopenharmony_ciapplication-specific conditions.</li> 9391cb0ef41Sopenharmony_ci<li>The condition should be such that a Node.js user would expect it to be in 9401cb0ef41Sopenharmony_ciNode.js core documentation. The <code>"types"</code> condition is a good example: It 9411cb0ef41Sopenharmony_cidoesn't really belong in the <a href="https://runtime-keys.proposal.wintercg.org/">Runtime Keys</a> proposal but is a good fit 9421cb0ef41Sopenharmony_cihere in the Node.js docs.</li> 9431cb0ef41Sopenharmony_ci</ul> 9441cb0ef41Sopenharmony_ci<p>The above definitions may be moved to a dedicated conditions registry in due 9451cb0ef41Sopenharmony_cicourse.</p> 9461cb0ef41Sopenharmony_ci<h4>Self-referencing a package using its name<span><a class="mark" href="#self-referencing-a-package-using-its-name" id="self-referencing-a-package-using-its-name">#</a></span><a aria-hidden="true" class="legacy" id="packages_self_referencing_a_package_using_its_name"></a></h4> 9471cb0ef41Sopenharmony_ci<div class="api_metadata"> 9481cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 9491cb0ef41Sopenharmony_ci<table> 9501cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 9511cb0ef41Sopenharmony_ci<tr><td>v13.6.0, v12.16.0</td> 9521cb0ef41Sopenharmony_ci<td><p>Unflag self-referencing a package using its name.</p></td></tr> 9531cb0ef41Sopenharmony_ci<tr><td>v13.1.0, v12.16.0</td> 9541cb0ef41Sopenharmony_ci<td><p><span>Added in: v13.1.0, v12.16.0</span></p></td></tr> 9551cb0ef41Sopenharmony_ci</tbody></table> 9561cb0ef41Sopenharmony_ci</details> 9571cb0ef41Sopenharmony_ci</div> 9581cb0ef41Sopenharmony_ci<p>Within a package, the values defined in the package's 9591cb0ef41Sopenharmony_ci<code>package.json</code> <a href="#exports"><code>"exports"</code></a> field can be referenced via the package's name. 9601cb0ef41Sopenharmony_ciFor example, assuming the <code>package.json</code> is:</p> 9611cb0ef41Sopenharmony_ci<pre><code class="language-json"><span class="hljs-comment">// package.json</span> 9621cb0ef41Sopenharmony_ci<span class="hljs-punctuation">{</span> 9631cb0ef41Sopenharmony_ci <span class="hljs-attr">"name"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"a-package"</span><span class="hljs-punctuation">,</span> 9641cb0ef41Sopenharmony_ci <span class="hljs-attr">"exports"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 9651cb0ef41Sopenharmony_ci <span class="hljs-attr">"."</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./index.mjs"</span><span class="hljs-punctuation">,</span> 9661cb0ef41Sopenharmony_ci <span class="hljs-attr">"./foo.js"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./foo.js"</span> 9671cb0ef41Sopenharmony_ci <span class="hljs-punctuation">}</span> 9681cb0ef41Sopenharmony_ci<span class="hljs-punctuation">}</span></code> <button class="copy-button">copy</button></pre> 9691cb0ef41Sopenharmony_ci<p>Then any module <em>in that package</em> can reference an export in the package itself:</p> 9701cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-comment">// ./a-module.mjs</span> 9711cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> { something } <span class="hljs-keyword">from</span> <span class="hljs-string">'a-package'</span>; <span class="hljs-comment">// Imports "something" from ./index.mjs.</span></code> <button class="copy-button">copy</button></pre> 9721cb0ef41Sopenharmony_ci<p>Self-referencing is available only if <code>package.json</code> has <a href="#exports"><code>"exports"</code></a>, and 9731cb0ef41Sopenharmony_ciwill allow importing only what that <a href="#exports"><code>"exports"</code></a> (in the <code>package.json</code>) 9741cb0ef41Sopenharmony_ciallows. So the code below, given the previous package, will generate a runtime 9751cb0ef41Sopenharmony_cierror:</p> 9761cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-comment">// ./another-module.mjs</span> 9771cb0ef41Sopenharmony_ci 9781cb0ef41Sopenharmony_ci<span class="hljs-comment">// Imports "another" from ./m.mjs. Fails because</span> 9791cb0ef41Sopenharmony_ci<span class="hljs-comment">// the "package.json" "exports" field</span> 9801cb0ef41Sopenharmony_ci<span class="hljs-comment">// does not provide an export named "./m.mjs".</span> 9811cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> { another } <span class="hljs-keyword">from</span> <span class="hljs-string">'a-package/m.mjs'</span>;</code> <button class="copy-button">copy</button></pre> 9821cb0ef41Sopenharmony_ci<p>Self-referencing is also available when using <code>require</code>, both in an ES module, 9831cb0ef41Sopenharmony_ciand in a CommonJS one. For example, this code will also work:</p> 9841cb0ef41Sopenharmony_ci<pre><code class="language-js cjs"><span class="hljs-comment">// ./a-module.js</span> 9851cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> { something } = <span class="hljs-built_in">require</span>(<span class="hljs-string">'a-package/foo.js'</span>); <span class="hljs-comment">// Loads from ./foo.js.</span></code> <button class="copy-button">copy</button></pre> 9861cb0ef41Sopenharmony_ci<p>Finally, self-referencing also works with scoped packages. For example, this 9871cb0ef41Sopenharmony_cicode will also work:</p> 9881cb0ef41Sopenharmony_ci<pre><code class="language-json"><span class="hljs-comment">// package.json</span> 9891cb0ef41Sopenharmony_ci<span class="hljs-punctuation">{</span> 9901cb0ef41Sopenharmony_ci <span class="hljs-attr">"name"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"@my/package"</span><span class="hljs-punctuation">,</span> 9911cb0ef41Sopenharmony_ci <span class="hljs-attr">"exports"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./index.js"</span> 9921cb0ef41Sopenharmony_ci<span class="hljs-punctuation">}</span></code> <button class="copy-button">copy</button></pre> 9931cb0ef41Sopenharmony_ci<pre><code class="language-js cjs"><span class="hljs-comment">// ./index.js</span> 9941cb0ef41Sopenharmony_ci<span class="hljs-variable language_">module</span>.<span class="hljs-property">exports</span> = <span class="hljs-number">42</span>;</code> <button class="copy-button">copy</button></pre> 9951cb0ef41Sopenharmony_ci<pre><code class="language-js cjs"><span class="hljs-comment">// ./other.js</span> 9961cb0ef41Sopenharmony_ci<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-built_in">require</span>(<span class="hljs-string">'@my/package'</span>));</code> <button class="copy-button">copy</button></pre> 9971cb0ef41Sopenharmony_ci<pre><code class="language-console"><span class="hljs-meta prompt_">$ </span><span class="language-bash">node other.js</span> 9981cb0ef41Sopenharmony_ci42</code> <button class="copy-button">copy</button></pre> 9991cb0ef41Sopenharmony_ci</section><section><h3>Dual CommonJS/ES module packages<span><a class="mark" href="#dual-commonjses-module-packages" id="dual-commonjses-module-packages">#</a></span><a aria-hidden="true" class="legacy" id="packages_dual_commonjs_es_module_packages"></a></h3> 10001cb0ef41Sopenharmony_ci<p>Prior to the introduction of support for ES modules in Node.js, it was a common 10011cb0ef41Sopenharmony_cipattern for package authors to include both CommonJS and ES module JavaScript 10021cb0ef41Sopenharmony_cisources in their package, with <code>package.json</code> <a href="#main"><code>"main"</code></a> specifying the 10031cb0ef41Sopenharmony_ciCommonJS entry point and <code>package.json</code> <code>"module"</code> specifying the ES module 10041cb0ef41Sopenharmony_cientry point. 10051cb0ef41Sopenharmony_ciThis enabled Node.js to run the CommonJS entry point while build tools such as 10061cb0ef41Sopenharmony_cibundlers used the ES module entry point, since Node.js ignored (and still 10071cb0ef41Sopenharmony_ciignores) the top-level <code>"module"</code> field.</p> 10081cb0ef41Sopenharmony_ci<p>Node.js can now run ES module entry points, and a package can contain both 10091cb0ef41Sopenharmony_ciCommonJS and ES module entry points (either via separate specifiers such as 10101cb0ef41Sopenharmony_ci<code>'pkg'</code> and <code>'pkg/es-module'</code>, or both at the same specifier via <a href="#conditional-exports">Conditional 10111cb0ef41Sopenharmony_ciexports</a>). Unlike in the scenario where <code>"module"</code> is only used by bundlers, 10121cb0ef41Sopenharmony_cior ES module files are transpiled into CommonJS on the fly before evaluation by 10131cb0ef41Sopenharmony_ciNode.js, the files referenced by the ES module entry point are evaluated as ES 10141cb0ef41Sopenharmony_cimodules.</p> 10151cb0ef41Sopenharmony_ci<h4>Dual package hazard<span><a class="mark" href="#dual-package-hazard" id="dual-package-hazard">#</a></span><a aria-hidden="true" class="legacy" id="packages_dual_package_hazard"></a></h4> 10161cb0ef41Sopenharmony_ci<p>When an application is using a package that provides both CommonJS and ES module 10171cb0ef41Sopenharmony_cisources, there is a risk of certain bugs if both versions of the package get 10181cb0ef41Sopenharmony_ciloaded. This potential comes from the fact that the <code>pkgInstance</code> created by 10191cb0ef41Sopenharmony_ci<code>const pkgInstance = require('pkg')</code> is not the same as the <code>pkgInstance</code> 10201cb0ef41Sopenharmony_cicreated by <code>import pkgInstance from 'pkg'</code> (or an alternative main path like 10211cb0ef41Sopenharmony_ci<code>'pkg/module'</code>). This is the “dual package hazard,” where two versions of the 10221cb0ef41Sopenharmony_cisame package can be loaded within the same runtime environment. While it is 10231cb0ef41Sopenharmony_ciunlikely that an application or package would intentionally load both versions 10241cb0ef41Sopenharmony_cidirectly, it is common for an application to load one version while a dependency 10251cb0ef41Sopenharmony_ciof the application loads the other version. This hazard can happen because 10261cb0ef41Sopenharmony_ciNode.js supports intermixing CommonJS and ES modules, and can lead to unexpected 10271cb0ef41Sopenharmony_cibehavior.</p> 10281cb0ef41Sopenharmony_ci<p>If the package main export is a constructor, an <code>instanceof</code> comparison of 10291cb0ef41Sopenharmony_ciinstances created by the two versions returns <code>false</code>, and if the export is an 10301cb0ef41Sopenharmony_ciobject, properties added to one (like <code>pkgInstance.foo = 3</code>) are not present on 10311cb0ef41Sopenharmony_cithe other. This differs from how <code>import</code> and <code>require</code> statements work in 10321cb0ef41Sopenharmony_ciall-CommonJS or all-ES module environments, respectively, and therefore is 10331cb0ef41Sopenharmony_cisurprising to users. It also differs from the behavior users are familiar with 10341cb0ef41Sopenharmony_ciwhen using transpilation via tools like <a href="https://babeljs.io/">Babel</a> or <a href="https://github.com/standard-things/esm#readme"><code>esm</code></a>.</p> 10351cb0ef41Sopenharmony_ci<h4>Writing dual packages while avoiding or minimizing hazards<span><a class="mark" href="#writing-dual-packages-while-avoiding-or-minimizing-hazards" id="writing-dual-packages-while-avoiding-or-minimizing-hazards">#</a></span><a aria-hidden="true" class="legacy" id="packages_writing_dual_packages_while_avoiding_or_minimizing_hazards"></a></h4> 10361cb0ef41Sopenharmony_ci<p>First, the hazard described in the previous section occurs when a package 10371cb0ef41Sopenharmony_cicontains both CommonJS and ES module sources and both sources are provided for 10381cb0ef41Sopenharmony_ciuse in Node.js, either via separate main entry points or exported paths. A 10391cb0ef41Sopenharmony_cipackage might instead be written where any version of Node.js receives only 10401cb0ef41Sopenharmony_ciCommonJS sources, and any separate ES module sources the package might contain 10411cb0ef41Sopenharmony_ciare intended only for other environments such as browsers. Such a package 10421cb0ef41Sopenharmony_ciwould be usable by any version of Node.js, since <code>import</code> can refer to CommonJS 10431cb0ef41Sopenharmony_cifiles; but it would not provide any of the advantages of using ES module syntax.</p> 10441cb0ef41Sopenharmony_ci<p>A package might also switch from CommonJS to ES module syntax in a <a href="https://semver.org/">breaking 10451cb0ef41Sopenharmony_cichange</a> version bump. This has the disadvantage that the 10461cb0ef41Sopenharmony_cinewest version of the package would only be usable in ES module-supporting 10471cb0ef41Sopenharmony_civersions of Node.js.</p> 10481cb0ef41Sopenharmony_ci<p>Every pattern has tradeoffs, but there are two broad approaches that satisfy the 10491cb0ef41Sopenharmony_cifollowing conditions:</p> 10501cb0ef41Sopenharmony_ci<ol> 10511cb0ef41Sopenharmony_ci<li>The package is usable via both <code>require</code> and <code>import</code>.</li> 10521cb0ef41Sopenharmony_ci<li>The package is usable in both current Node.js and older versions of Node.js 10531cb0ef41Sopenharmony_cithat lack support for ES modules.</li> 10541cb0ef41Sopenharmony_ci<li>The package main entry point, e.g. <code>'pkg'</code> can be used by both <code>require</code> to 10551cb0ef41Sopenharmony_ciresolve to a CommonJS file and by <code>import</code> to resolve to an ES module file. 10561cb0ef41Sopenharmony_ci(And likewise for exported paths, e.g. <code>'pkg/feature'</code>.)</li> 10571cb0ef41Sopenharmony_ci<li>The package provides named exports, e.g. <code>import { name } from 'pkg'</code> rather 10581cb0ef41Sopenharmony_cithan <code>import pkg from 'pkg'; pkg.name</code>.</li> 10591cb0ef41Sopenharmony_ci<li>The package is potentially usable in other ES module environments such as 10601cb0ef41Sopenharmony_cibrowsers.</li> 10611cb0ef41Sopenharmony_ci<li>The hazards described in the previous section are avoided or minimized.</li> 10621cb0ef41Sopenharmony_ci</ol> 10631cb0ef41Sopenharmony_ci<h5>Approach #1: Use an ES module wrapper<span><a class="mark" href="#approach-1-use-an-es-module-wrapper" id="approach-1-use-an-es-module-wrapper">#</a></span><a aria-hidden="true" class="legacy" id="packages_approach_1_use_an_es_module_wrapper"></a></h5> 10641cb0ef41Sopenharmony_ci<p>Write the package in CommonJS or transpile ES module sources into CommonJS, and 10651cb0ef41Sopenharmony_cicreate an ES module wrapper file that defines the named exports. Using 10661cb0ef41Sopenharmony_ci<a href="#conditional-exports">Conditional exports</a>, the ES module wrapper is used for <code>import</code> and the 10671cb0ef41Sopenharmony_ciCommonJS entry point for <code>require</code>.</p> 10681cb0ef41Sopenharmony_ci<pre><code class="language-json"><span class="hljs-comment">// ./node_modules/pkg/package.json</span> 10691cb0ef41Sopenharmony_ci<span class="hljs-punctuation">{</span> 10701cb0ef41Sopenharmony_ci <span class="hljs-attr">"type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"module"</span><span class="hljs-punctuation">,</span> 10711cb0ef41Sopenharmony_ci <span class="hljs-attr">"exports"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 10721cb0ef41Sopenharmony_ci <span class="hljs-attr">"import"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./wrapper.mjs"</span><span class="hljs-punctuation">,</span> 10731cb0ef41Sopenharmony_ci <span class="hljs-attr">"require"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./index.cjs"</span> 10741cb0ef41Sopenharmony_ci <span class="hljs-punctuation">}</span> 10751cb0ef41Sopenharmony_ci<span class="hljs-punctuation">}</span></code> <button class="copy-button">copy</button></pre> 10761cb0ef41Sopenharmony_ci<p>The preceding example uses explicit extensions <code>.mjs</code> and <code>.cjs</code>. 10771cb0ef41Sopenharmony_ciIf your files use the <code>.js</code> extension, <code>"type": "module"</code> will cause such files 10781cb0ef41Sopenharmony_cito be treated as ES modules, just as <code>"type": "commonjs"</code> would cause them 10791cb0ef41Sopenharmony_cito be treated as CommonJS. 10801cb0ef41Sopenharmony_ciSee <a href="esm.html#enabling">Enabling</a>.</p> 10811cb0ef41Sopenharmony_ci<pre><code class="language-js cjs"><span class="hljs-comment">// ./node_modules/pkg/index.cjs</span> 10821cb0ef41Sopenharmony_ci<span class="hljs-built_in">exports</span>.<span class="hljs-property">name</span> = <span class="hljs-string">'value'</span>;</code> <button class="copy-button">copy</button></pre> 10831cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-comment">// ./node_modules/pkg/wrapper.mjs</span> 10841cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> cjsModule <span class="hljs-keyword">from</span> <span class="hljs-string">'./index.cjs'</span>; 10851cb0ef41Sopenharmony_ci<span class="hljs-keyword">export</span> <span class="hljs-keyword">const</span> name = cjsModule.<span class="hljs-property">name</span>;</code> <button class="copy-button">copy</button></pre> 10861cb0ef41Sopenharmony_ci<p>In this example, the <code>name</code> from <code>import { name } from 'pkg'</code> is the same 10871cb0ef41Sopenharmony_cisingleton as the <code>name</code> from <code>const { name } = require('pkg')</code>. Therefore <code>===</code> 10881cb0ef41Sopenharmony_cireturns <code>true</code> when comparing the two <code>name</code>s and the divergent specifier hazard 10891cb0ef41Sopenharmony_ciis avoided.</p> 10901cb0ef41Sopenharmony_ci<p>If the module is not simply a list of named exports, but rather contains a 10911cb0ef41Sopenharmony_ciunique function or object export like <code>module.exports = function () { ... }</code>, 10921cb0ef41Sopenharmony_cior if support in the wrapper for the <code>import pkg from 'pkg'</code> pattern is desired, 10931cb0ef41Sopenharmony_cithen the wrapper would instead be written to export the default optionally 10941cb0ef41Sopenharmony_cialong with any named exports as well:</p> 10951cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">import</span> cjsModule <span class="hljs-keyword">from</span> <span class="hljs-string">'./index.cjs'</span>; 10961cb0ef41Sopenharmony_ci<span class="hljs-keyword">export</span> <span class="hljs-keyword">const</span> name = cjsModule.<span class="hljs-property">name</span>; 10971cb0ef41Sopenharmony_ci<span class="hljs-keyword">export</span> <span class="hljs-keyword">default</span> cjsModule;</code> <button class="copy-button">copy</button></pre> 10981cb0ef41Sopenharmony_ci<p>This approach is appropriate for any of the following use cases:</p> 10991cb0ef41Sopenharmony_ci<ul> 11001cb0ef41Sopenharmony_ci<li>The package is currently written in CommonJS and the author would prefer not 11011cb0ef41Sopenharmony_cito refactor it into ES module syntax, but wishes to provide named exports for 11021cb0ef41Sopenharmony_ciES module consumers.</li> 11031cb0ef41Sopenharmony_ci<li>The package has other packages that depend on it, and the end user might 11041cb0ef41Sopenharmony_ciinstall both this package and those other packages. For example a <code>utilities</code> 11051cb0ef41Sopenharmony_cipackage is used directly in an application, and a <code>utilities-plus</code> package 11061cb0ef41Sopenharmony_ciadds a few more functions to <code>utilities</code>. Because the wrapper exports 11071cb0ef41Sopenharmony_ciunderlying CommonJS files, it doesn't matter if <code>utilities-plus</code> is written in 11081cb0ef41Sopenharmony_ciCommonJS or ES module syntax; it will work either way.</li> 11091cb0ef41Sopenharmony_ci<li>The package stores internal state, and the package author would prefer not to 11101cb0ef41Sopenharmony_cirefactor the package to isolate its state management. See the next section.</li> 11111cb0ef41Sopenharmony_ci</ul> 11121cb0ef41Sopenharmony_ci<p>A variant of this approach not requiring conditional exports for consumers could 11131cb0ef41Sopenharmony_cibe to add an export, e.g. <code>"./module"</code>, to point to an all-ES module-syntax 11141cb0ef41Sopenharmony_civersion of the package. This could be used via <code>import 'pkg/module'</code> by users 11151cb0ef41Sopenharmony_ciwho are certain that the CommonJS version will not be loaded anywhere in the 11161cb0ef41Sopenharmony_ciapplication, such as by dependencies; or if the CommonJS version can be loaded 11171cb0ef41Sopenharmony_cibut doesn't affect the ES module version (for example, because the package is 11181cb0ef41Sopenharmony_cistateless):</p> 11191cb0ef41Sopenharmony_ci<pre><code class="language-json"><span class="hljs-comment">// ./node_modules/pkg/package.json</span> 11201cb0ef41Sopenharmony_ci<span class="hljs-punctuation">{</span> 11211cb0ef41Sopenharmony_ci <span class="hljs-attr">"type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"module"</span><span class="hljs-punctuation">,</span> 11221cb0ef41Sopenharmony_ci <span class="hljs-attr">"exports"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 11231cb0ef41Sopenharmony_ci <span class="hljs-attr">"."</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./index.cjs"</span><span class="hljs-punctuation">,</span> 11241cb0ef41Sopenharmony_ci <span class="hljs-attr">"./module"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./wrapper.mjs"</span> 11251cb0ef41Sopenharmony_ci <span class="hljs-punctuation">}</span> 11261cb0ef41Sopenharmony_ci<span class="hljs-punctuation">}</span></code> <button class="copy-button">copy</button></pre> 11271cb0ef41Sopenharmony_ci<h5>Approach #2: Isolate state<span><a class="mark" href="#approach-2-isolate-state" id="approach-2-isolate-state">#</a></span><a aria-hidden="true" class="legacy" id="packages_approach_2_isolate_state"></a></h5> 11281cb0ef41Sopenharmony_ci<p>A <a href="#nodejs-packagejson-field-definitions"><code>package.json</code></a> file can define the separate CommonJS and ES module entry 11291cb0ef41Sopenharmony_cipoints directly:</p> 11301cb0ef41Sopenharmony_ci<pre><code class="language-json"><span class="hljs-comment">// ./node_modules/pkg/package.json</span> 11311cb0ef41Sopenharmony_ci<span class="hljs-punctuation">{</span> 11321cb0ef41Sopenharmony_ci <span class="hljs-attr">"type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"module"</span><span class="hljs-punctuation">,</span> 11331cb0ef41Sopenharmony_ci <span class="hljs-attr">"exports"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 11341cb0ef41Sopenharmony_ci <span class="hljs-attr">"import"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./index.mjs"</span><span class="hljs-punctuation">,</span> 11351cb0ef41Sopenharmony_ci <span class="hljs-attr">"require"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./index.cjs"</span> 11361cb0ef41Sopenharmony_ci <span class="hljs-punctuation">}</span> 11371cb0ef41Sopenharmony_ci<span class="hljs-punctuation">}</span></code> <button class="copy-button">copy</button></pre> 11381cb0ef41Sopenharmony_ci<p>This can be done if both the CommonJS and ES module versions of the package are 11391cb0ef41Sopenharmony_ciequivalent, for example because one is the transpiled output of the other; and 11401cb0ef41Sopenharmony_cithe package's management of state is carefully isolated (or the package is 11411cb0ef41Sopenharmony_cistateless).</p> 11421cb0ef41Sopenharmony_ci<p>The reason that state is an issue is because both the CommonJS and ES module 11431cb0ef41Sopenharmony_civersions of the package might get used within an application; for example, the 11441cb0ef41Sopenharmony_ciuser's application code could <code>import</code> the ES module version while a dependency 11451cb0ef41Sopenharmony_ci<code>require</code>s the CommonJS version. If that were to occur, two copies of the 11461cb0ef41Sopenharmony_cipackage would be loaded in memory and therefore two separate states would be 11471cb0ef41Sopenharmony_cipresent. This would likely cause hard-to-troubleshoot bugs.</p> 11481cb0ef41Sopenharmony_ci<p>Aside from writing a stateless package (if JavaScript's <code>Math</code> were a package, 11491cb0ef41Sopenharmony_cifor example, it would be stateless as all of its methods are static), there are 11501cb0ef41Sopenharmony_cisome ways to isolate state so that it's shared between the potentially loaded 11511cb0ef41Sopenharmony_ciCommonJS and ES module instances of the package:</p> 11521cb0ef41Sopenharmony_ci<ol> 11531cb0ef41Sopenharmony_ci<li> 11541cb0ef41Sopenharmony_ci<p>If possible, contain all state within an instantiated object. JavaScript's 11551cb0ef41Sopenharmony_ci<code>Date</code>, for example, needs to be instantiated to contain state; if it were a 11561cb0ef41Sopenharmony_cipackage, it would be used like this:</p> 11571cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-keyword">import</span> <span class="hljs-title class_">Date</span> <span class="hljs-keyword">from</span> <span class="hljs-string">'date'</span>; 11581cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> someDate = <span class="hljs-keyword">new</span> <span class="hljs-title class_">Date</span>(); 11591cb0ef41Sopenharmony_ci<span class="hljs-comment">// someDate contains state; Date does not</span></code> <button class="copy-button">copy</button></pre> 11601cb0ef41Sopenharmony_ci<p>The <code>new</code> keyword isn't required; a package's function can return a new 11611cb0ef41Sopenharmony_ciobject, or modify a passed-in object, to keep the state external to the 11621cb0ef41Sopenharmony_cipackage.</p> 11631cb0ef41Sopenharmony_ci</li> 11641cb0ef41Sopenharmony_ci<li> 11651cb0ef41Sopenharmony_ci<p>Isolate the state in one or more CommonJS files that are shared between the 11661cb0ef41Sopenharmony_ciCommonJS and ES module versions of the package. For example, if the CommonJS 11671cb0ef41Sopenharmony_ciand ES module entry points are <code>index.cjs</code> and <code>index.mjs</code>, respectively:</p> 11681cb0ef41Sopenharmony_ci<pre><code class="language-js cjs"><span class="hljs-comment">// ./node_modules/pkg/index.cjs</span> 11691cb0ef41Sopenharmony_ci<span class="hljs-keyword">const</span> state = <span class="hljs-built_in">require</span>(<span class="hljs-string">'./state.cjs'</span>); 11701cb0ef41Sopenharmony_ci<span class="hljs-variable language_">module</span>.<span class="hljs-property">exports</span>.<span class="hljs-property">state</span> = state;</code> <button class="copy-button">copy</button></pre> 11711cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-comment">// ./node_modules/pkg/index.mjs</span> 11721cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> state <span class="hljs-keyword">from</span> <span class="hljs-string">'./state.cjs'</span>; 11731cb0ef41Sopenharmony_ci<span class="hljs-keyword">export</span> { 11741cb0ef41Sopenharmony_ci state, 11751cb0ef41Sopenharmony_ci};</code> <button class="copy-button">copy</button></pre> 11761cb0ef41Sopenharmony_ci<p>Even if <code>pkg</code> is used via both <code>require</code> and <code>import</code> in an application (for 11771cb0ef41Sopenharmony_ciexample, via <code>import</code> in application code and via <code>require</code> by a dependency) 11781cb0ef41Sopenharmony_cieach reference of <code>pkg</code> will contain the same state; and modifying that 11791cb0ef41Sopenharmony_cistate from either module system will apply to both.</p> 11801cb0ef41Sopenharmony_ci</li> 11811cb0ef41Sopenharmony_ci</ol> 11821cb0ef41Sopenharmony_ci<p>Any plugins that attach to the package's singleton would need to separately 11831cb0ef41Sopenharmony_ciattach to both the CommonJS and ES module singletons.</p> 11841cb0ef41Sopenharmony_ci<p>This approach is appropriate for any of the following use cases:</p> 11851cb0ef41Sopenharmony_ci<ul> 11861cb0ef41Sopenharmony_ci<li>The package is currently written in ES module syntax and the package author 11871cb0ef41Sopenharmony_ciwants that version to be used wherever such syntax is supported.</li> 11881cb0ef41Sopenharmony_ci<li>The package is stateless or its state can be isolated without too much 11891cb0ef41Sopenharmony_cidifficulty.</li> 11901cb0ef41Sopenharmony_ci<li>The package is unlikely to have other public packages that depend on it, or if 11911cb0ef41Sopenharmony_ciit does, the package is stateless or has state that need not be shared between 11921cb0ef41Sopenharmony_cidependencies or with the overall application.</li> 11931cb0ef41Sopenharmony_ci</ul> 11941cb0ef41Sopenharmony_ci<p>Even with isolated state, there is still the cost of possible extra code 11951cb0ef41Sopenharmony_ciexecution between the CommonJS and ES module versions of a package.</p> 11961cb0ef41Sopenharmony_ci<p>As with the previous approach, a variant of this approach not requiring 11971cb0ef41Sopenharmony_ciconditional exports for consumers could be to add an export, e.g. 11981cb0ef41Sopenharmony_ci<code>"./module"</code>, to point to an all-ES module-syntax version of the package:</p> 11991cb0ef41Sopenharmony_ci<pre><code class="language-json"><span class="hljs-comment">// ./node_modules/pkg/package.json</span> 12001cb0ef41Sopenharmony_ci<span class="hljs-punctuation">{</span> 12011cb0ef41Sopenharmony_ci <span class="hljs-attr">"type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"module"</span><span class="hljs-punctuation">,</span> 12021cb0ef41Sopenharmony_ci <span class="hljs-attr">"exports"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 12031cb0ef41Sopenharmony_ci <span class="hljs-attr">"."</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./index.cjs"</span><span class="hljs-punctuation">,</span> 12041cb0ef41Sopenharmony_ci <span class="hljs-attr">"./module"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./index.mjs"</span> 12051cb0ef41Sopenharmony_ci <span class="hljs-punctuation">}</span> 12061cb0ef41Sopenharmony_ci<span class="hljs-punctuation">}</span></code> <button class="copy-button">copy</button></pre> 12071cb0ef41Sopenharmony_ci</section><section><h3>Node.js <code>package.json</code> field definitions<span><a class="mark" href="#nodejs-packagejson-field-definitions" id="nodejs-packagejson-field-definitions">#</a></span><a aria-hidden="true" class="legacy" id="packages_node_js_package_json_field_definitions"></a></h3> 12081cb0ef41Sopenharmony_ci<p>This section describes the fields used by the Node.js runtime. Other tools (such 12091cb0ef41Sopenharmony_cias <a href="https://docs.npmjs.com/cli/v8/configuring-npm/package-json">npm</a>) use 12101cb0ef41Sopenharmony_ciadditional fields which are ignored by Node.js and not documented here.</p> 12111cb0ef41Sopenharmony_ci<p>The following fields in <code>package.json</code> files are used in Node.js:</p> 12121cb0ef41Sopenharmony_ci<ul> 12131cb0ef41Sopenharmony_ci<li><a href="#name"><code>"name"</code></a> - Relevant when using named imports within a package. Also used 12141cb0ef41Sopenharmony_ciby package managers as the name of the package.</li> 12151cb0ef41Sopenharmony_ci<li><a href="#main"><code>"main"</code></a> - The default module when loading the package, if exports is not 12161cb0ef41Sopenharmony_cispecified, and in versions of Node.js prior to the introduction of exports.</li> 12171cb0ef41Sopenharmony_ci<li><a href="#packagemanager"><code>"packageManager"</code></a> - The package manager recommended when contributing to 12181cb0ef41Sopenharmony_cithe package. Leveraged by the <a href="corepack.html">Corepack</a> shims.</li> 12191cb0ef41Sopenharmony_ci<li><a href="#type"><code>"type"</code></a> - The package type determining whether to load <code>.js</code> files as 12201cb0ef41Sopenharmony_ciCommonJS or ES modules.</li> 12211cb0ef41Sopenharmony_ci<li><a href="#exports"><code>"exports"</code></a> - Package exports and conditional exports. When present, 12221cb0ef41Sopenharmony_cilimits which submodules can be loaded from within the package.</li> 12231cb0ef41Sopenharmony_ci<li><a href="#imports"><code>"imports"</code></a> - Package imports, for use by modules within the package 12241cb0ef41Sopenharmony_ciitself.</li> 12251cb0ef41Sopenharmony_ci</ul> 12261cb0ef41Sopenharmony_ci<h4><code>"name"</code><span><a class="mark" href="#name" id="name">#</a></span><a aria-hidden="true" class="legacy" id="packages_name"></a></h4> 12271cb0ef41Sopenharmony_ci<div class="api_metadata"> 12281cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 12291cb0ef41Sopenharmony_ci<table> 12301cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 12311cb0ef41Sopenharmony_ci<tr><td>v13.6.0, v12.16.0</td> 12321cb0ef41Sopenharmony_ci<td><p>Remove the <code>--experimental-resolve-self</code> option.</p></td></tr> 12331cb0ef41Sopenharmony_ci<tr><td>v13.1.0, v12.16.0</td> 12341cb0ef41Sopenharmony_ci<td><p><span>Added in: v13.1.0, v12.16.0</span></p></td></tr> 12351cb0ef41Sopenharmony_ci</tbody></table> 12361cb0ef41Sopenharmony_ci</details> 12371cb0ef41Sopenharmony_ci</div> 12381cb0ef41Sopenharmony_ci<ul> 12391cb0ef41Sopenharmony_ci<li>Type: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 12401cb0ef41Sopenharmony_ci</ul> 12411cb0ef41Sopenharmony_ci<pre><code class="language-json"><span class="hljs-punctuation">{</span> 12421cb0ef41Sopenharmony_ci <span class="hljs-attr">"name"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"package-name"</span> 12431cb0ef41Sopenharmony_ci<span class="hljs-punctuation">}</span></code> <button class="copy-button">copy</button></pre> 12441cb0ef41Sopenharmony_ci<p>The <code>"name"</code> field defines your package's name. Publishing to the 12451cb0ef41Sopenharmony_ci<em>npm</em> registry requires a name that satisfies 12461cb0ef41Sopenharmony_ci<a href="https://docs.npmjs.com/files/package.json#name">certain requirements</a>.</p> 12471cb0ef41Sopenharmony_ci<p>The <code>"name"</code> field can be used in addition to the <a href="#exports"><code>"exports"</code></a> field to 12481cb0ef41Sopenharmony_ci<a href="#self-referencing-a-package-using-its-name">self-reference</a> a package using its name.</p> 12491cb0ef41Sopenharmony_ci<h4><code>"main"</code><span><a class="mark" href="#main" id="main">#</a></span><a aria-hidden="true" class="legacy" id="packages_main"></a></h4> 12501cb0ef41Sopenharmony_ci<div class="api_metadata"> 12511cb0ef41Sopenharmony_ci<span>Added in: v0.4.0</span> 12521cb0ef41Sopenharmony_ci</div> 12531cb0ef41Sopenharmony_ci<ul> 12541cb0ef41Sopenharmony_ci<li>Type: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 12551cb0ef41Sopenharmony_ci</ul> 12561cb0ef41Sopenharmony_ci<pre><code class="language-json"><span class="hljs-punctuation">{</span> 12571cb0ef41Sopenharmony_ci <span class="hljs-attr">"main"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./index.js"</span> 12581cb0ef41Sopenharmony_ci<span class="hljs-punctuation">}</span></code> <button class="copy-button">copy</button></pre> 12591cb0ef41Sopenharmony_ci<p>The <code>"main"</code> field defines the entry point of a package when imported by name 12601cb0ef41Sopenharmony_civia a <code>node_modules</code> lookup. Its value is a path.</p> 12611cb0ef41Sopenharmony_ci<p>When a package has an <a href="#exports"><code>"exports"</code></a> field, this will take precedence over the 12621cb0ef41Sopenharmony_ci<code>"main"</code> field when importing the package by name.</p> 12631cb0ef41Sopenharmony_ci<p>It also defines the script that is used when the <a href="modules.html#folders-as-modules">package directory is loaded 12641cb0ef41Sopenharmony_civia <code>require()</code></a>.</p> 12651cb0ef41Sopenharmony_ci<pre><code class="language-js cjs"><span class="hljs-comment">// This resolves to ./path/to/directory/index.js.</span> 12661cb0ef41Sopenharmony_ci<span class="hljs-built_in">require</span>(<span class="hljs-string">'./path/to/directory'</span>);</code> <button class="copy-button">copy</button></pre> 12671cb0ef41Sopenharmony_ci<h4><code>"packageManager"</code><span><a class="mark" href="#packagemanager" id="packagemanager">#</a></span><a aria-hidden="true" class="legacy" id="packages_packagemanager"></a></h4> 12681cb0ef41Sopenharmony_ci<div class="api_metadata"> 12691cb0ef41Sopenharmony_ci<span>Added in: v16.9.0, v14.19.0</span> 12701cb0ef41Sopenharmony_ci</div> 12711cb0ef41Sopenharmony_ci<p></p><div class="api_stability api_stability_1"><a href="documentation.html#stability-index">Stability: 1</a> - Experimental</div><p></p> 12721cb0ef41Sopenharmony_ci<ul> 12731cb0ef41Sopenharmony_ci<li>Type: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 12741cb0ef41Sopenharmony_ci</ul> 12751cb0ef41Sopenharmony_ci<pre><code class="language-json"><span class="hljs-punctuation">{</span> 12761cb0ef41Sopenharmony_ci <span class="hljs-attr">"packageManager"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"<package manager name>@<version>"</span> 12771cb0ef41Sopenharmony_ci<span class="hljs-punctuation">}</span></code> <button class="copy-button">copy</button></pre> 12781cb0ef41Sopenharmony_ci<p>The <code>"packageManager"</code> field defines which package manager is expected to be 12791cb0ef41Sopenharmony_ciused when working on the current project. It can be set to any of the 12801cb0ef41Sopenharmony_ci<a href="corepack.html#supported-package-managers">supported package managers</a>, and will ensure that your teams use the exact 12811cb0ef41Sopenharmony_cisame package manager versions without having to install anything else other than 12821cb0ef41Sopenharmony_ciNode.js.</p> 12831cb0ef41Sopenharmony_ci<p>This field is currently experimental and needs to be opted-in; check the 12841cb0ef41Sopenharmony_ci<a href="corepack.html">Corepack</a> page for details about the procedure.</p> 12851cb0ef41Sopenharmony_ci<h4><code>"type"</code><span><a class="mark" href="#type" id="type">#</a></span><a aria-hidden="true" class="legacy" id="packages_type"></a></h4> 12861cb0ef41Sopenharmony_ci<div class="api_metadata"> 12871cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 12881cb0ef41Sopenharmony_ci<table> 12891cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 12901cb0ef41Sopenharmony_ci<tr><td>v13.2.0, v12.17.0</td> 12911cb0ef41Sopenharmony_ci<td><p>Unflag <code>--experimental-modules</code>.</p></td></tr> 12921cb0ef41Sopenharmony_ci<tr><td>v12.0.0</td> 12931cb0ef41Sopenharmony_ci<td><p><span>Added in: v12.0.0</span></p></td></tr> 12941cb0ef41Sopenharmony_ci</tbody></table> 12951cb0ef41Sopenharmony_ci</details> 12961cb0ef41Sopenharmony_ci</div> 12971cb0ef41Sopenharmony_ci<ul> 12981cb0ef41Sopenharmony_ci<li>Type: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a></li> 12991cb0ef41Sopenharmony_ci</ul> 13001cb0ef41Sopenharmony_ci<p>The <code>"type"</code> field defines the module format that Node.js uses for all 13011cb0ef41Sopenharmony_ci<code>.js</code> files that have that <code>package.json</code> file as their nearest parent.</p> 13021cb0ef41Sopenharmony_ci<p>Files ending with <code>.js</code> are loaded as ES modules when the nearest parent 13031cb0ef41Sopenharmony_ci<code>package.json</code> file contains a top-level field <code>"type"</code> with a value of 13041cb0ef41Sopenharmony_ci<code>"module"</code>.</p> 13051cb0ef41Sopenharmony_ci<p>The nearest parent <code>package.json</code> is defined as the first <code>package.json</code> found 13061cb0ef41Sopenharmony_ciwhen searching in the current folder, that folder's parent, and so on up 13071cb0ef41Sopenharmony_ciuntil a node_modules folder or the volume root is reached.</p> 13081cb0ef41Sopenharmony_ci<pre><code class="language-json"><span class="hljs-comment">// package.json</span> 13091cb0ef41Sopenharmony_ci<span class="hljs-punctuation">{</span> 13101cb0ef41Sopenharmony_ci <span class="hljs-attr">"type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"module"</span> 13111cb0ef41Sopenharmony_ci<span class="hljs-punctuation">}</span></code> <button class="copy-button">copy</button></pre> 13121cb0ef41Sopenharmony_ci<pre><code class="language-bash"><span class="hljs-comment"># In same folder as preceding package.json</span> 13131cb0ef41Sopenharmony_cinode my-app.js <span class="hljs-comment"># Runs as ES module</span></code> <button class="copy-button">copy</button></pre> 13141cb0ef41Sopenharmony_ci<p>If the nearest parent <code>package.json</code> lacks a <code>"type"</code> field, or contains 13151cb0ef41Sopenharmony_ci<code>"type": "commonjs"</code>, <code>.js</code> files are treated as <a href="modules.html">CommonJS</a>. If the volume 13161cb0ef41Sopenharmony_ciroot is reached and no <code>package.json</code> is found, <code>.js</code> files are treated as 13171cb0ef41Sopenharmony_ci<a href="modules.html">CommonJS</a>.</p> 13181cb0ef41Sopenharmony_ci<p><code>import</code> statements of <code>.js</code> files are treated as ES modules if the nearest 13191cb0ef41Sopenharmony_ciparent <code>package.json</code> contains <code>"type": "module"</code>.</p> 13201cb0ef41Sopenharmony_ci<pre><code class="language-js"><span class="hljs-comment">// my-app.js, part of the same example as above</span> 13211cb0ef41Sopenharmony_ci<span class="hljs-keyword">import</span> <span class="hljs-string">'./startup.js'</span>; <span class="hljs-comment">// Loaded as ES module because of package.json</span></code> <button class="copy-button">copy</button></pre> 13221cb0ef41Sopenharmony_ci<p>Regardless of the value of the <code>"type"</code> field, <code>.mjs</code> files are always treated 13231cb0ef41Sopenharmony_cias ES modules and <code>.cjs</code> files are always treated as CommonJS.</p> 13241cb0ef41Sopenharmony_ci<h4><code>"exports"</code><span><a class="mark" href="#exports" id="exports">#</a></span><a aria-hidden="true" class="legacy" id="packages_exports"></a></h4> 13251cb0ef41Sopenharmony_ci<div class="api_metadata"> 13261cb0ef41Sopenharmony_ci<details class="changelog"><summary>History</summary> 13271cb0ef41Sopenharmony_ci<table> 13281cb0ef41Sopenharmony_ci<tbody><tr><th>Version</th><th>Changes</th></tr> 13291cb0ef41Sopenharmony_ci<tr><td>v14.13.0, v12.20.0</td> 13301cb0ef41Sopenharmony_ci<td><p>Add support for <code>"exports"</code> patterns.</p></td></tr> 13311cb0ef41Sopenharmony_ci<tr><td>v13.7.0, v12.17.0</td> 13321cb0ef41Sopenharmony_ci<td><p>Unflag conditional exports.</p></td></tr> 13331cb0ef41Sopenharmony_ci<tr><td>v13.7.0, v12.16.0</td> 13341cb0ef41Sopenharmony_ci<td><p>Implement logical conditional exports ordering.</p></td></tr> 13351cb0ef41Sopenharmony_ci<tr><td>v13.7.0, v12.16.0</td> 13361cb0ef41Sopenharmony_ci<td><p>Remove the <code>--experimental-conditional-exports</code> option. In 12.16.0, conditional exports are still behind <code>--experimental-modules</code>.</p></td></tr> 13371cb0ef41Sopenharmony_ci<tr><td>v13.2.0, v12.16.0</td> 13381cb0ef41Sopenharmony_ci<td><p>Implement conditional exports.</p></td></tr> 13391cb0ef41Sopenharmony_ci<tr><td>v12.7.0</td> 13401cb0ef41Sopenharmony_ci<td><p><span>Added in: v12.7.0</span></p></td></tr> 13411cb0ef41Sopenharmony_ci</tbody></table> 13421cb0ef41Sopenharmony_ci</details> 13431cb0ef41Sopenharmony_ci</div> 13441cb0ef41Sopenharmony_ci<ul> 13451cb0ef41Sopenharmony_ci<li>Type: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string></a> | <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type" class="type"><string[]></a></li> 13461cb0ef41Sopenharmony_ci</ul> 13471cb0ef41Sopenharmony_ci<pre><code class="language-json"><span class="hljs-punctuation">{</span> 13481cb0ef41Sopenharmony_ci <span class="hljs-attr">"exports"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./index.js"</span> 13491cb0ef41Sopenharmony_ci<span class="hljs-punctuation">}</span></code> <button class="copy-button">copy</button></pre> 13501cb0ef41Sopenharmony_ci<p>The <code>"exports"</code> field allows defining the <a href="#package-entry-points">entry points</a> of a package when 13511cb0ef41Sopenharmony_ciimported by name loaded either via a <code>node_modules</code> lookup or a 13521cb0ef41Sopenharmony_ci<a href="#self-referencing-a-package-using-its-name">self-reference</a> to its own name. It is supported in Node.js 12+ as an 13531cb0ef41Sopenharmony_cialternative to the <a href="#main"><code>"main"</code></a> that can support defining <a href="#subpath-exports">subpath exports</a> 13541cb0ef41Sopenharmony_ciand <a href="#conditional-exports">conditional exports</a> while encapsulating internal unexported modules.</p> 13551cb0ef41Sopenharmony_ci<p><a href="#conditional-exports">Conditional Exports</a> can also be used within <code>"exports"</code> to define different 13561cb0ef41Sopenharmony_cipackage entry points per environment, including whether the package is 13571cb0ef41Sopenharmony_cireferenced via <code>require</code> or via <code>import</code>.</p> 13581cb0ef41Sopenharmony_ci<p>All paths defined in the <code>"exports"</code> must be relative file URLs starting with 13591cb0ef41Sopenharmony_ci<code>./</code>.</p> 13601cb0ef41Sopenharmony_ci<h4><code>"imports"</code><span><a class="mark" href="#imports" id="imports">#</a></span><a aria-hidden="true" class="legacy" id="packages_imports"></a></h4> 13611cb0ef41Sopenharmony_ci<div class="api_metadata"> 13621cb0ef41Sopenharmony_ci<span>Added in: v14.6.0, v12.19.0</span> 13631cb0ef41Sopenharmony_ci</div> 13641cb0ef41Sopenharmony_ci<ul> 13651cb0ef41Sopenharmony_ci<li>Type: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object" class="type"><Object></a></li> 13661cb0ef41Sopenharmony_ci</ul> 13671cb0ef41Sopenharmony_ci<pre><code class="language-json"><span class="hljs-comment">// package.json</span> 13681cb0ef41Sopenharmony_ci<span class="hljs-punctuation">{</span> 13691cb0ef41Sopenharmony_ci <span class="hljs-attr">"imports"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 13701cb0ef41Sopenharmony_ci <span class="hljs-attr">"#dep"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 13711cb0ef41Sopenharmony_ci <span class="hljs-attr">"node"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"dep-node-native"</span><span class="hljs-punctuation">,</span> 13721cb0ef41Sopenharmony_ci <span class="hljs-attr">"default"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"./dep-polyfill.js"</span> 13731cb0ef41Sopenharmony_ci <span class="hljs-punctuation">}</span> 13741cb0ef41Sopenharmony_ci <span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span> 13751cb0ef41Sopenharmony_ci <span class="hljs-attr">"dependencies"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span> 13761cb0ef41Sopenharmony_ci <span class="hljs-attr">"dep-node-native"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"^1.0.0"</span> 13771cb0ef41Sopenharmony_ci <span class="hljs-punctuation">}</span> 13781cb0ef41Sopenharmony_ci<span class="hljs-punctuation">}</span></code> <button class="copy-button">copy</button></pre> 13791cb0ef41Sopenharmony_ci<p>Entries in the imports field must be strings starting with <code>#</code>.</p> 13801cb0ef41Sopenharmony_ci<p>Package imports permit mapping to external packages.</p> 13811cb0ef41Sopenharmony_ci<p>This field defines <a href="#subpath-imports">subpath imports</a> for the current package.</p></section> 13821cb0ef41Sopenharmony_ci <!-- API END --> 13831cb0ef41Sopenharmony_ci </div> 13841cb0ef41Sopenharmony_ci </div> 13851cb0ef41Sopenharmony_ci </div> 13861cb0ef41Sopenharmony_ci</body> 13871cb0ef41Sopenharmony_ci</html> 1388