npm v12 Full Migration Guide in 2026: Allowlist Setup, prebuildify & Team Rollout ChecklistGuide Complet de Migration npm v12 en 2026 : Allowlist, prebuildify & Checklist Équipe

npm v12 is arriving in July 2026 — and it ships with three breaking changes that will silently break CI pipelines, crash production apps, and block installs for teams that don't prepare. The good news: npm 11.16.0, already available, gives you a warning-only mode so you can audit everything before the upgrade. This guide covers every step: understanding what changes, auditing your dependency graph, building your allowlist with npm approve-scripts, migrating native modules to prebuildify, updating CI/CD pipelines, and rolling out the change across your team with zero downtime.

npm v12 arrive en juillet 2026 avec trois breaking changes qui vont silencieusement casser des pipelines CI, crasher des apps en production, et bloquer des installations pour les équipes qui ne se préparent pas. La bonne nouvelle : npm 11.16.0, déjà disponible, offre un mode warnings-only pour auditer tout avant la mise à jour. Ce guide couvre chaque étape : comprendre ce qui change, auditer le graphe de dépendances, construire l’allowlist avec npm approve-scripts, migrer les modules natifs vers prebuildify, mettre à jour les pipelines CI/CD, et déployer le changement dans toute l’équipe.

Why npm v12 Breaks Install Scripts by Default

Pourquoi npm v12 Bloque les Scripts d’Installation par Défaut

Install scripts — preinstall, install, postinstall, and prepare — have always been npm's most dangerous feature. They execute arbitrary shell code with the full permissions of the developer or CI runner the moment you run npm install. The Phantom Gyp attack in June 2026 demonstrated how a 157-byte binding.gyp file could trick npm into running node-gyp — bypassing even --ignore-scripts — and compromised 57 packages across three Miasma worm waves. The attack surface was real and exploited at scale.

Les scripts d’installation — preinstall, install, postinstall et prepare — ont toujours été la fonctionnalité la plus dangereuse de npm. Ils exécutent du code shell arbitraire avec les permissions complètes du développeur ou du runner CI dès que vous faites npm install. L’attaque Phantom Gyp en juin 2026 a démontré comment un fichier binding.gyp de 157 octets pouvait tromper npm pour exécuter node-gyp — en bypassant même --ignore-scripts — et a compromis 57 packages sur trois vagues du ver Miasma. La surface d’attaque était réelle et exploitée à grande échelle.

npm v12 closes this attack surface permanently. Instead of running scripts by default and hoping developers notice suspicious ones, it requires explicit approval for every package that needs to run scripts. This is the same model browsers use for extensions: deny by default, approve what you trust.

npm v12 ferme définitivement cette surface d’attaque. Au lieu d’exécuter des scripts par défaut en espérant que les développeurs repèrent les suspects, il exige une approbation explicite pour chaque package ayant besoin de scripts. C’est le même modèle que les navigateurs utilisent pour les extensions : refus par défaut, approbation de ce en quoi vous avez confiance.

The Three Breaking Changes in Detail

Les Trois Breaking Changes en Détail

1. allowScripts defaults to OFF

1. allowScripts passe à OFF par défaut

Starting with npm v12, npm install and npm ci will no longer execute any lifecycle scripts (preinstall, install, postinstall, prepare) from dependency packages. This includes the implicit node-gyp rebuild triggered by the presence of a binding.gyp file. Any package whose native binary requires compilation at install time will silently skip that step. The app will appear to install correctly — npm ci exits with code 0 — but will crash at runtime when it tries to require() the missing .node binary.

Dès npm v12, npm install et npm ci n’exécuteront plus aucun lifecycle script (preinstall, install, postinstall, prepare) des packages de dépendances. Cela inclut le node-gyp rebuild implicite déclenché par la présence d’un fichier binding.gyp. Tout package dont le binaire natif nécessite une compilation au moment de l’installation ignorera silencieusement cette étape. L’app semblera s’installer correctement — npm ci sort avec le code 0 — mais crashera au runtime quand elle essaiera de require() le binaire .node manquant.

Common packages affected: sharp (image processing), bcrypt (password hashing), canvas (server-side rendering), esbuild (bundler), @tailwindcss/oxide (CSS), sqlite3, better-sqlite3, native Node.js addons. Packages that ship prebuilt binaries in the npm tarball (like esbuild since v0.21) are not affected if they no longer need a postinstall download step.

Packages couramment affectés : sharp (traitement d’image), bcrypt (hachage de mots de passe), canvas (rendu côté serveur), esbuild (bundler), @tailwindcss/oxide (CSS), sqlite3, better-sqlite3, les addons Node.js natifs. Les packages qui livrent des binaires précompilés dans le tarball npm (comme esbuild depuis v0.21) ne sont pas affectés s’ils n’ont plus besoin d’un téléchargement postinstall.

2. Git Dependencies Blocked by Default

2. Dépendances Git Bloquées par Défaut

npm v12 will refuse to resolve Git dependencies (e.g., "my-lib": "github:org/repo#commit") unless you explicitly pass --allow-git or configure it in .npmrc. The security rationale: a Git dependency's own .npmrc file could override the system's Git executable path, creating an arbitrary code execution path that --ignore-scripts could not protect against. Note that file: and link: dependencies are not blocked in v12 — these remain valid alternatives for monorepo and local package setups.

npm v12 refusera de résoudre les dépendances Git (ex. "my-lib": "github:org/repo#commit") sauf si vous passez explicitement --allow-git ou le configurez dans .npmrc. La raison sécurité : le propre fichier .npmrc d’une dépendance Git pouvait récrire le chemin de l’exécutable Git du système, créant un vecteur d’exécution de code arbitraire que --ignore-scripts ne pouvait pas bloquer. Notez que les dépendances file: et link: ne sont pas bloquées dans v12 — elles restent des alternatives valides pour les monorepos et packages locaux.

3. Remote URL Dependencies Blocked by Default

3. Dépendances URL Distantes Bloquées par Défaut

Any dependency resolved from an HTTPS tarball URL (e.g., "my-pkg": "https://example.com/pkg-1.0.0.tgz") will be blocked unless you pass --allow-remote. This closes the scenario where a package resolves to an attacker-controlled server hosting a malicious tarball. As with Git dependencies, you can configure this per-project in .npmrc if your organization genuinely requires remote URL dependencies.

Toute dépendance résolue depuis une URL HTTPS de tarball (ex. "my-pkg": "https://example.com/pkg-1.0.0.tgz") sera bloquée sauf si vous passez --allow-remote. Cela ferme le scénario où un package se résout vers un serveur contrôlé par un attaquant hébergeant un tarball malveillant. Comme pour les dépendances Git, vous pouvez configurer cela par projet dans .npmrc si votre organisation a de véritables besoins en dépendances URL distantes.

Step-by-Step Migration: Start Today with npm 11.16.0

Migration Pas à Pas : Commencez Aujourd’hui avec npm 11.16.0

All three breaking changes are available in warning-only mode in npm 11.16.0+. This means you can audit everything and build your allowlist without touching v12 yet. Start here.

Les trois breaking changes sont disponibles en mode warnings-only dans npm 11.16.0+. Cela signifie que vous pouvez tout auditer et construire votre allowlist sans toucher à v12 pour l’instant. Commencez ici.

Step 1 — Upgrade to npm 11.16.0

Étape 1 — Mettre à jour vers npm 11.16.0

# Check your current version
npm --version

# Upgrade globally
npm install -g npm@latest

# Pin the version in your CI (recommended — see CI section below)
# engines field in package.json for local enforcement:
# "engines": { "npm": ">=11.16.0" }

Step 2 — Run Your Normal Install and Review Warnings

Étape 2 — Faire l’Installation Normale et Lire les Avertissements

Once you're on 11.16.0, a plain npm install will print warnings for every package that would be blocked in v12. These warnings look like:

Une fois sur 11.16.0, un simple npm install affichera des avertissements pour chaque package qui serait bloqué dans v12. Ces avertissements ressemblent à :

npm warn install-scripts sharp@0.33.5 has scripts and will not run them
npm warn install-scripts esbuild@0.24.2 has scripts and will not run them
npm warn git-dep my-internal-lib@github:org/my-internal-lib#abc123 uses a git source
npm warn remote-dep some-build-tool@https://cdn.example.com/tool-1.0.tgz uses a remote URL

Collect these warnings. They form the complete list of packages you need to address before upgrading to v12.

Collectez ces avertissements. Ils constituent la liste complète des packages à traiter avant de passer à v12.

Step 3 — Build the Install-Scripts Allowlist

Étape 3 — Construire l’Allowlist des Scripts d’Installation

Run the interactive audit command to see every package with install scripts and decide which ones to trust:

Exécutez la commande d’audit interactive pour voir chaque package avec des install scripts et décider lesquels approuver :

# List packages with pending install scripts (interactive)
npm approve-scripts --allow-scripts-pending

# Approve a specific package (pinned to current installed version by default)
npm approve-scripts sharp esbuild canvas bcrypt

# Approve a package but allow any future version (use cautiously)
npm approve-scripts --no-allow-scripts-pin sharp

# Approve everything installed (only if you've audited all scripts first)
npm approve-scripts --all

After running these commands, your package.json will contain an allowScripts block like this:

Après ces commandes, votre package.json contiendra un bloc allowScripts comme celui-ci :

{
  "name": "my-app",
  "version": "1.0.0",
  "allowScripts": {
    "sharp@0.33.5": true,
    "esbuild@0.24.2": true,
    "canvas@2.11.2": true,
    "bcrypt@5.1.1": true
  },
  "dependencies": { ... }
}

Important: commit this allowScripts block to your repository so your whole team and all CI runners share the same approved list. Never use npm approve-scripts --all blindly on a new project without reviewing what each script does — a malicious postinstall is precisely what you're protecting against.

Important : committez ce bloc allowScripts dans votre dépôt pour que toute l’équipe et tous les runners CI partagent la même liste approuvée. N’utilisez jamais npm approve-scripts --all à l’aveugle sur un nouveau projet sans vérifier ce que fait chaque script — un postinstall malveillant est exactement ce contre quoi vous vous protégez.

Step 4 — Handle Git and Remote URL Dependencies

Étape 4 — Traiter les Dépendances Git et URL Distantes

Identify all Git and remote URL dependencies in your project. On npm 11.16.0, they will already show warnings:

Identifiez toutes les dépendances Git et URL distantes dans votre projet. Sur npm 11.16.0, elles afficheront déjà des avertissements :

# Find git and remote URL deps in your lockfile
grep -E "(git\+|github:|gitlab:|bitbucket:|https://.*\.tgz)" package-lock.json

# Or use npm ls (slower but traverses full tree)
npm ls --all 2>&1 | grep -E "(git\+|https://.*\.tgz)"

For each Git dependency, evaluate the migration path:

Pour chaque dépendance Git, évaluez la voie de migration :

• Internal package not yet published to npm → Publish it to your private registry (GitHub Packages, Verdaccio, Artifactory) and switch to a normal version specifier. See our private registry hardening guide.
• Package interne pas encore publié sur npm → Publiez-le sur votre registry privé (GitHub Packages, Verdaccio, Artifactory) et passez à un specifier de version normal. Voir notre guide hardening registry privé.
• Fork of an open-source package → Publish your fork under a scoped name (@yourorg/package-name) to npm or your private registry.
• Fork d’un package open source → Publiez votre fork sous un nom scopped (@votre-org/nom-package) sur npm ou votre registry privé.
• Monorepo local package → Use file: or link: instead of a Git URL — these are not blocked in v12. Example: "my-shared-utils": "file:../packages/shared-utils".
• Package local monorepo → Utilisez file: ou link: au lieu d’une URL Git — ils ne sont pas bloqués dans v12. Exemple : "my-shared-utils": "file:../packages/shared-utils".
• Genuinely need Git deps temporarily → Add allow-git=true to your .npmrc as a bridge, and set a deadline to migrate. Document why.
• Besoin temporaire de déps Git → Ajoutez allow-git=true dans votre .npmrc comme pont, et fixez une deadline de migration. Documentez pourquoi.

Migrating Native Modules: From prebuild-install to prebuildify

Migration des Modules Natifs : De prebuild-install à prebuildify

If you maintain a package with native Node.js bindings (a .node addon built from C/C++ using node-gyp), npm v12 is your forcing function to adopt the modern approach. The old pattern — ship source and compile on the developer's machine via a postinstall script — is now blocked. There are two viable paths:

Si vous maintenez un package avec des bindings Node.js natifs (un addon .node construit depuis C/C++ avec node-gyp), npm v12 vous force à adopter l’approche moderne. L’ancienne stratégie — livrer le source et compiler sur la machine du développeur via un script postinstall — est maintenant bloquée. Il existe deux voies viables :

Option A: prebuildify (Recommended)

Option A : prebuildify (Recommandé)

prebuildify bundles prebuilt binaries for all target platforms directly inside the npm package tarball. When the user runs npm install, no compilation or download happens — the binary is already there. The companion node-gyp-build picks the right binary at runtime.

prebuildify intègre les binaires précompilés pour toutes les plateformes cibles directement dans le tarball npm. Quand l’utilisateur fait npm install, aucune compilation ni téléchargement ne se produit — le binaire est déjà là. Le companion node-gyp-build sélectionne le bon binaire au runtime.

# Install build deps (in your package, not the consumer's)
npm install --save-dev prebuildify
npm install --save node-gyp-build

{
  "scripts": {
    "prebuild": "prebuildify --napi --strip"
  },
  "dependencies": {
    "node-gyp-build": "^4.8.0"
  }
}

// In your package's main index.js — runtime binary selection
const binding = require('node-gyp-build')(__dirname);
module.exports = binding;

In your CI/CD pipeline for publishing, run npm run prebuild on each target platform (Linux x64, Linux arm64, macOS, Windows) and include the resulting prebuilds/ directory in your npm tarball via .npmignore or files in package.json. GitHub Actions matrix builds are the standard approach:

Dans votre pipeline CI/CD de publication, exécutez npm run prebuild sur chaque plateforme cible (Linux x64, Linux arm64, macOS, Windows) et incluez le répertoire prebuilds/ résultant dans votre tarball npm via .npmignore ou files dans package.json. Les builds en matrice GitHub Actions sont l’approche standard :

# .github/workflows/publish.yml (for native module maintainers)
name: Publish with prebuilds
on:
  push:
    tags: ['v*']

jobs:
  build:
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
    runs-on: ${{ matrix.os }}

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - run: npm ci
      - run: npm run prebuild
      - uses: actions/upload-artifact@v4
        with:
          name: prebuilds-${{ matrix.os }}

          path: prebuilds/

  publish:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/download-artifact@v4
        with:
          path: prebuilds/
          merge-multiple: true
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          registry-url: 'https://registry.npmjs.org'
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Option B: Allowlist Your Script (Short-Term Bridge)

Option B : Allowlister le Script (Solution Temporaire)

If you consume a native module that you don't maintain (like sharp or canvas), and the upstream package hasn't migrated to prebuildify yet, use npm approve-scripts to explicitly allowlist it in your project. This is safe because you're making a deliberate, audited choice rather than running arbitrary code from an untrusted update.

Si vous consommez un module natif que vous ne maintenez pas (comme sharp ou canvas), et que le package upstream n’a pas encore migré vers prebuildify, utilisez npm approve-scripts pour l’allowlister explicitement dans votre projet. C’est sécurisé car vous faites un choix délibéré et audité plutôt que d’exécuter du code arbitraire d’une mise à jour non vérifiée.

CI/CD Migration: Complete GitHub Actions YAML

Migration CI/CD : YAML GitHub Actions Complet

The most common failure mode when teams upgrade to npm v12 is: CI passes, deployment succeeds, app crashes in production because a native binary was never compiled. The fix is to pin npm in CI, commit the allowlist, and verify native binaries load correctly in your test suite.

L’échec le plus fréquent lors du passage à npm v12 est : CI passe, le déploiement réussit, l’app crashe en production parce qu’un binaire natif n’a jamais été compilé. La correction est de pin npm en CI, committer l’allowlist, et vérifier que les binaires natifs se chargent correctement dans votre suite de tests.

# .github/workflows/ci.yml — npm v12 ready
name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'npm'

      # Pin npm to 11.16.0+ now (warning mode), switch to 12.x when ready
      - name: Pin npm version
        run: npm install -g npm@11.16.0

      # npm ci respects allowScripts from package.json automatically
      # No flags needed — allowlist is already committed
      - name: Install dependencies
        run: npm ci

      # Sanity check: verify native binaries load
      - name: Verify native binaries
        run: |
          node -e "require('sharp'); console.log('sharp OK')" || true
          node -e "require('bcrypt'); console.log('bcrypt OK')" || true

      - name: Run tests
        run: npm test

      # Check for new install-script warnings that need allowlisting
      - name: Check for unapproved install scripts
        run: |
          WARNINGS=$(npm install --dry-run 2>&1 | grep "warn install-scripts" || true)
          if [ -n "$WARNINGS" ]; then
            echo "::warning::New packages with install scripts detected — run npm approve-scripts"
            echo "$WARNINGS"
          fi

When you're ready to upgrade to npm v12 itself, change the version pin from 11.16.0 to 12.x. Everything else stays the same — the committed allowScripts block in package.json is automatically honored by v12.

Quand vous êtes prêt à passer à npm v12 lui-même, changez le pin de version de 11.16.0 à 12.x. Tout le reste reste identique — le bloc allowScripts committé dans package.json est automatiquement honoré par v12.

Team Rollout Checklist

Checklist de Déploiement Équipe

Use this checklist to coordinate the migration across your team without disrupting ongoing development.

Utilisez cette checklist pour coordonner la migration dans toute votre équipe sans perturber le développement en cours.

How CVE Monitoring Completes the Picture

Comment le Monitoring CVE Complète le Tableau

The allowScripts allowlist tells npm which packages are allowed to run scripts — but it doesn't tell you when one of those approved packages gets a malicious version published. After the Mastra takeover in June 2026, @mastra/core was in many teams' allowlists. When 143 packages got backdoored RAT payloads injected into their postinstall, the allowlist didn't help — the packages were already trusted.

L’allowlist allowScripts dit à npm quels packages sont autorisés à exécuter des scripts — mais elle ne vous dit pas quand l’un de ces packages approuvés reçoit une version malveillante. Après la prise de contrôle de Mastra en juin 2026, @mastra/core figurait dans les allowlists de nombreuses équipes. Quand 143 packages ont reçu des payloads RAT backdoor injectés dans leur postinstall, l’allowlist n’a pas aidé — les packages étaient déjà de confiance.

This is the gap that CVE monitoring fills: it scans your lockfile daily against OSV.dev, GHSA, and NVD, and alerts you the moment a CVE is published against any package in your package-lock.json — including the ones in your allowlist. If a package you've approved for script execution gets a critical vulnerability, you need to know before your next deployment, not after.

C’est la lacune que le monitoring CVE comble : il scanne votre lockfile quotidiennement contre OSV.dev, GHSA et NVD, et vous alerte dès qu’une CVE est publiée contre n’importe quel package de votre package-lock.json — y compris ceux dans votre allowlist. Si un package que vous avez approuvé pour l’exécution de scripts reçoit une vulnérabilité critique, vous devez le savoir avant votre prochain déploiement, pas après.

Frequently Asked Questions

Questions Fréquentes