npm

<!DOCTYPE html><html><head> <meta charset="utf-8"> <title>.npm-extension</title> <style> body { background-color: #ffffff; color: #24292e; margin: 0; line-height: 1.5; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji"; } #rainbar { height: 10px; background-image: linear-gradient(139deg, #fb8817, #ff4b01, #c12127, #e02aff); } a { text-decoration: none; color: #0366d6; } a:hover { text-decoration: underline; } pre { margin: 1em 0px; padding: 1em; border: solid 1px #e1e4e8; border-radius: 6px; display: block; overflow: auto; white-space: pre; background-color: #f6f8fa; color: #393a34; } code { font-family: SFMono-Regular, Consolas, "Liberation Mono", Menlo, Courier, monospace; font-size: 85%; padding: 0.2em 0.4em; background-color: #f6f8fa; color: #393a34; } pre > code { padding: 0; background-color: inherit; color: inherit; } h1, h2, h3 { font-weight: 600; } #logobar { background-color: #333333; margin: 0 auto; padding: 1em 4em; } #logobar .logo { float: left; } #logobar .title { font-weight: 600; color: #dddddd; float: left; margin: 5px 0 0 1em; } #logobar:after { content: ""; display: block; clear: both; } #content { margin: 0 auto; padding: 0 4em; } #table_of_contents > h2 { font-size: 1.17em; } #table_of_contents ul:first-child { border: solid 1px #e1e4e8; border-radius: 6px; padding: 1em; background-color: #f6f8fa; color: #393a34; } #table_of_contents ul { list-style-type: none; padding-left: 1.5em; } #table_of_contents li { font-size: 0.9em; } #table_of_contents li a { color: #000000; } header.title { border-bottom: solid 1px #e1e4e8; } header.title > h1 { margin-bottom: 0.25em; } header.title > .description { display: block; margin-bottom: 0.5em; line-height: 1; } header.title .version { font-size: 0.8em; color: #666666; } footer#edit { border-top: solid 1px #e1e4e8; margin: 3em 0 4em 0; padding-top: 2em; } table { width: 100%; margin: 1em 0; border-radius: 6px; border: 1px solid #e1e4e8; overflow: hidden; border-collapse: separate; border-spacing: 0; } table thead { background-color: #f6f8fa; } table tbody { background-color: #ffffff; } table th, table td { padding: 0.75em; text-align: left; border-right: 1px solid #e1e4e8; border-bottom: 1px solid #e1e4e8; } table th:last-child, table td:last-child { border-right: none; } table tbody tr:last-child td { border-bottom: none; } table th { font-weight: 600; background-color: #f6f8fa; } table code { white-space: nowrap; } </style> </head> <body> <div id="banner"> <div id="rainbar"></div> <div id="logobar"> <svg class="logo" role="img" height="32" width="32" viewBox="0 0 700 700"> <polygon fill="#cb0000" points="0,700 700,700 700,0 0,0"></polygon> <polygon fill="#ffffff" points="150,550 350,550 350,250 450,250 450,550 550,550 550,150 150,150"></polygon> </svg> <div class="title"> npm command-line interface </div> </div> </div> <section id="content"> <header class="title"> <h1 id="----npm-extension----1201"> <span>.npm-extension</span> <span class="version">@12.0.1</span> </h1> <span class="description">Imperative, root-owned manifest repairs</span> </header> <section id="table_of_contents"> <h2 id="table-of-contents">Table of contents</h2> <div id="_table_of_contents"><ul><li><a href="#description">Description</a></li><li><a href="#example">Example</a></li><li><a href="#the-transformmanifest-function">The <code>transformManifest</code> function</a></li><li><a href="#supported-mutations">Supported mutations</a></li><li><a href="#discovery-and-extension-file">Discovery and <code>extension-file</code></a></li><li><a href="#interaction-with-packageextensions-and-overrides">Interaction with <code>packageExtensions</code> and <code>overrides</code></a></li><li><a href="#lockfile-and-npm-ci">Lockfile and <code>npm ci</code></a></li><li><a href="#disabling">Disabling</a></li><li><a href="#publishing">Publishing</a></li><li><a href="#see-also">See also</a></li></ul></div> </section> <div id="_content"><h3 id="description">Description</h3> <p>A root-owned <code>.npm-extension.mjs</code> or <code>.npm-extension.cjs</code> file lets a project imperatively repair the manifests of third-party dependencies before npm resolves the dependency tree. It exports a <code>transformManifest(pkg, context)</code> function that receives a candidate dependency manifest and returns the effective manifest npm should use.</p> <p><code>.npm-extension</code> is the imperative counterpart to the declarative <a href="../configuring-npm/package-json#packageextensions.html"><code>packageExtensions</code></a> field, and runs in the same pre-resolution phase, <strong>before</strong> <code>packageExtensions</code>. Prefer <code>packageExtensions</code> for simple, data-only repairs; reach for <code>.npm-extension</code> when you need comments and links explaining a repair, conditional logic, repeated repairs expressed as code, deletion or range rewrites, stale-repair guards, or a policy location outside <code>package.json</code>.</p> <h3 id="example">Example</h3> <pre><code class="language-js">// .npm-extension.mjs export function transformManifest (pkg, context) { if (pkg.name === 'foo' && pkg.version.startsWith('1.')) { pkg.dependencies = { ...pkg.dependencies, bar: '^2.0.0' } context.log(`added bar to ${pkg.name}@${pkg.version}`) } return pkg } </code></pre> <p>The <code>.cjs</code> form uses CommonJS exports instead:</p> <pre><code class="language-js">// .npm-extension.cjs module.exports = { transformManifest (pkg, context) { return pkg }, } </code></pre> <h3 id="the-transformmanifest-function">The <code>transformManifest</code> function</h3> <p><code>transformManifest(pkg, context)</code> receives a deeply isolated copy of a candidate dependency manifest. It may mutate and return that copy, or return a new manifest object. It <strong>must</strong> return a manifest object synchronously; returning <code>null</code>, <code>undefined</code>, a primitive, an array, or a promise fails the install.</p> <p>The <code>context</code> argument is intentionally small:</p> <ul> <li><code>context.log(message)</code> writes an npm debug log message.</li> <li><code>context.root</code> is the absolute path to the project root.</li> <li><code>context.extensionPoint</code> is the string <code>"transformManifest"</code>.</li> </ul> <p>npm provides no registry, fetch, lockfile, or extraction helpers. Keep the extension file self-contained or limited to Node builtins; npm does not guarantee that project dependencies are available when the file is loaded.</p> <h3 id="supported-mutations">Supported mutations</h3> <p>Only the four resolution-affecting fields may change:</p> <ul> <li><code>dependencies</code></li> <li><code>optionalDependencies</code></li> <li><code>peerDependencies</code></li> <li><code>peerDependenciesMeta</code></li> </ul> <p>Within those fields you may add, replace, or delete entries. Changing any other field (such as <code>scripts</code>, <code>bin</code>, <code>engines</code>, <code>os</code>, <code>cpu</code>, <code>exports</code>, or <code>main</code>) is rejected, and the install fails with an error naming <code>.npm-extension</code> and the package being processed. The package tarball and the installed <code>node_modules/<pkg>/package.json</code> are never rewritten.</p> <h3 id="discovery-and-extension-file">Discovery and <code>extension-file</code></h3> <p>npm looks for a single <code>.npm-extension.mjs</code> or <code>.npm-extension.cjs</code> at the project root (the workspace root in a workspace project). Having both files present is an error. A <code>.npm-extension</code> file in a dependency or in a non-root workspace is ignored; a non-root workspace file produces a warning.</p> <p>The <a href="../using-npm/config#extension-file.html"><code>extension-file</code></a> config selects a different project-local file. It must resolve inside the project root and use a <code>.mjs</code> or <code>.cjs</code> extension, and it is honored only from project config or the command line — never from user, global, or builtin config.</p> <h3 id="interaction-with-packageextensions-and-overrides">Interaction with <code>packageExtensions</code> and <code>overrides</code></h3> <p>When both are present, <code>transformManifest</code> runs first and <code>packageExtensions</code> is applied to its output. Avoid targeting the same package with both unless you intend to rely on that ordering. <code>overrides</code> still controls the final resolution target of any edge, including edges created by <code>transformManifest</code>.</p> <h3 id="lockfile-and-npm-ci">Lockfile and <code>npm ci</code></h3> <p>A lockfile influenced by <code>.npm-extension</code> records an <code>npmExtensionHash</code> (a digest of the selected file's bytes and module format) on its root entry, and minimal <code>npmExtensionApplied</code> provenance on each affected package entry. Extension state requires <code>lockfileVersion: 4</code>.</p> <p>Changing the file's contents makes <code>npm install</code> re-resolve the affected packages. <code>npm ci</code> does <strong>not</strong> import or execute <code>.npm-extension</code>; it verifies the recorded hash against the file and reifies the locked graph, failing if the file and lockfile disagree (or if one has extension state and the other does not).</p> <p>The hash proves only that the install uses the same extension file bytes that generated the lockfile. It does not make arbitrary JavaScript deterministic: extension output that depends on environment variables, the network, the clock, or files imported by the extension can still produce non-reproducible installs. Treat <code>.npm-extension</code> as trusted, deterministic project code, and only enable it in repositories you trust.</p> <h3 id="disabling">Disabling</h3> <p>Set <a href="../using-npm/config#ignore-extension.html"><code>ignore-extension</code></a> to skip importing and executing <code>.npm-extension</code>. <a href="../using-npm/config#ignore-scripts.html"><code>ignore-scripts</code></a> implies <code>ignore-extension</code>, since both disable root-owned install-time code. <code>npm ci</code> still verifies the file hash even when execution is disabled.</p> <h3 id="publishing">Publishing</h3> <p><code>.npm-extension.mjs</code> and <code>.npm-extension.cjs</code> are project configuration, not package contents. npm excludes the root file from the package tarball produced by <code>npm pack</code> and <code>npm publish</code>, even when the package's <code>files</code> list would include it, so a public package can keep <code>.npm-extension</code> in its repository for local use without publishing it.</p> <h3 id="see-also">See also</h3> <ul> <li><a href="../configuring-npm/package-json#packageextensions.html">package.json <code>packageExtensions</code></a></li> <li><a href="../configuring-npm/package-lock-json.html">package-lock.json</a></li> <li><a href="../using-npm/config.html">config</a></li> </ul></div> <footer id="edit"> <a href="https://github.com/npm/cli/edit/latest/docs/lib/content/configuring-npm/npm-extension.md"> <svg role="img" viewBox="0 0 16 16" width="16" height="16" fill="currentcolor" style="vertical-align: text-bottom; margin-right: 0.3em;"> <path fill-rule="evenodd" d="M11.013 1.427a1.75 1.75 0 012.474 0l1.086 1.086a1.75 1.75 0 010 2.474l-8.61 8.61c-.21.21-.47.364-.756.445l-3.251.93a.75.75 0 01-.927-.928l.929-3.25a1.75 1.75 0 01.445-.758l8.61-8.61zm1.414 1.06a.25.25 0 00-.354 0L10.811 3.75l1.439 1.44 1.263-1.263a.25.25 0 000-.354l-1.086-1.086zM11.189 6.25L9.75 4.81l-6.286 6.287a.25.25 0 00-.064.108l-.558 1.953 1.953-.558a.249.249 0 00.108-.064l6.286-6.286z"></path> </svg> Edit this page on GitHub </a> </footer> </section> </body></html>