Migration vers Deno

Nécessite Deno 2.9 ou version ultérieure. Pour une utilisation générale de Deno après la migration, consultez la skill deno.

La plupart des projets Node fonctionnent déjà sous Deno

Deno lit un package.json existant, résout les mêmes packages npm, écrit un vrai node_modules, exécute les mêmes scripts et supporte les built-ins node:. TypeScript s'exécute sans étape de build.

Il n'y a généralement aucun code à modifier — seulement le binaire que vous invoquez. Ne commencez pas par réécrire les imports en jsr:, remplacer les dépendances par des spécifiques à Deno ou restructurer les répertoires. C'est la façon la plus courante de rendre les choses impossibles.

Migration par étapes

Chaque étape est indépendamment utile et réversible. Arrêtez-vous où cela convient au projet ; beaucoup d'équipes s'arrêtent à l'étape 1.

Étape 1 — Deno comme gestionnaire de paquets uniquement

deno install

Lit package.json, résout les mêmes dépendances, écrit node_modules et crée deno.lock — amorcé à partir de tout package-lock.json, yarn.lock, bun.lock ou lockfile pnpm existant, de sorte que les épingles et les hachages d'intégrité se transfèrent au lieu de dériver.

L'application s'exécute toujours sous node ; les collègues ne sont pas affectés. Validez deno.lock une fois vérifié. Pour annuler : supprimez deno.lock et node_modules, puis lancez npm install.

Étape 2 — L'exécuter avec Deno

deno run -A main.js      # ou : deno -A main.js
deno task build          # exécute scripts.build depuis package.json

Utilisez -A ici. L'objectif est de confirmer que le programme fonctionne, non de concevoir une politique de permissions — modifier les deux à la fois rend les défaillances ambiguës.

Étape 3 — Resserrer les permissions

Remplacez -A par l'ensemble le plus restreint qui fonctionne : exécutez-le, lisez ce qu'il demande, accordez exactement cela.

deno run --allow-net=api.example.com --allow-read=./config --allow-env=PORT main.js

Cela offre quelque chose que Node ne peut pas proposer, et vaut la peine d'être fait avant le déploiement.

Étape 4 — Optionnellement, adopter la chaîne d'outils intégrée

deno fmt pour prettier, deno lint pour eslint, deno test pour jest ou vitest, deno check pour tsc, deno watch pour nodemon, deno compile pour pkg.

Optionnel, et généralement pas utile pour un projet existant. Ce ne sont pas des remplaçants directs ; la parité est incomplète, il s'agit donc d'une vraie migration, pas d'un changement de config. Un projet satisfait de prettier, eslint et vitest devrait les garder et utiliser Deno uniquement comme runtime et gestionnaire de paquets. Préférez les outils intégrés pour les nouveaux projets. Si vous en migrez un existant, allez un outil à la fois.

Équivalents de commandes

† Orthographe de Yarn Berry (v2+). Yarn Classic (v1) utilise yarn install --frozen-lockfile et yarn audit.

‡ Yarn Classic uniquement — Berry a supprimé yarn outdated.

dx est un binaire séparé installé avec Deno, et un alias pour deno x. Il n'apparaît pas dans la sortie deno --help de niveau supérieur. Comme npx, il exécute le paquet avec le sandbox désactivé.

Les quatre choses qui cassent réellement

Requires net access to "..." (ou read, env, run)

Deno n'accorde rien par défaut. Ajoutez cette permission spécifique, ou -A tant que vous établissez toujours que le programme fonctionne du tout.

ReferenceError: require is not defined

Un fichier contenant du CommonJS est analysé comme ESM. .cjs est toujours CommonJS, .mjs toujours ESM ; .js et .ts suivent "type" dans le package.json le plus proche. Pour un projet CommonJS, définissez "type": "commonjs".

Une dépendance est cassée, ou postinstall n'a jamais été exécuté

Les lifecycle scripts ne s'exécutent pas par défaut. Les addons natifs le remarquent immédiatement. Les approbations sont enregistrées dans le fichier de config, c'est donc une seule fois :

deno approve-scripts                              # sélecteur interactif
deno install --allow-scripts=npm:better-sqlite3   # ou nommez-les directement

Un outil ne peut pas trouver de fichiers dans node_modules

La disposition de Deno est de style pnpm : fichiers réels dans node_modules/.deno/, exposés via des symlinks. Les outils supposant l'arborescence plate remontée de npm ont besoin de :

{ "nodeModulesLinker": "hoisted" }

Ce qui n'a pas d'équivalent Deno

Dites-le plutôt que d'improviser une contournement qui ne tiendra pas :

• Yarn Plug'n'Play. Deno crée un vrai node_modules ; .pnp.cjs n'est pas utilisé et les paramètres de résolveur .yarnrc.yml ne se transfèrent pas.
• yarn patch / dépendances patchées pnpm. Vendez ou forkez.
• overrides / resolutions. Épinglez via une entrée de carte d'import à la place.
• Registry et tuning de résolveur dans .npmrc / .yarnrc.yml.
• Fonctionnalités de build Bun — macros, HTMLRewriter, points d'entrée HTML.

Détails par outil

• references/FROM_NPM.md — amorçage du lockfile, disposition node_modules, overrides
• references/FROM_YARN.md — Plug'n'Play, Berry vs Classic, workspaces
• references/FROM_PNPM.md — pnpm-workspace.yaml, catalog:, patches
• references/FROM_BUN.md — traduction API Bun, bunfig.toml
• references/NODE_APIS.md — built-ins node:, DENO_COMPAT, CJS/ESM

Lectures complémentaires

• https://docs.deno.com/runtime/migrate/ — guides de migration officiels
• https://docs.deno.com/runtime/fundamentals/node/ — compatibilité Node et npm
• https://docs.deno.com/runtime/reference/node_apis/ — statut des API Node par module