Deno
Objectif
Fournir des configurations par défaut portables pour les projets Deno modernes, en particulier lorsque la base de code mélange Deno avec des outils orientés Node, nécessite un chemin de migration propre depuis les anciens motifs Deno, ou adopte Deno dans un dépôt TypeScript ou Node existant.
Quand utiliser ce skill
- Écrire des scripts, serveurs ou code edge Deno.
- Configurer
deno.json, les tâches et les sources de dépendances. - Adapter les fichiers
tsconfig.jsonoueslint.config.*existants pour coexister avec Deno. - Mélanger du code Deno avec du code Node ou TypeScript dans un même dépôt.
- Réviser les permissions, les tests ou les motifs d'exécution Deno.
Par défaut
- Utiliser
deno.jsoncomme source de vérité Deno. - Privilégier
deno check,deno task,deno fmt,deno lintetdeno testplutôt que des wrappers ad hoc lorsque Deno possède le workflow. - Les outils natifs de Deno sont suffisants pour le code appartenant à Deno ; utiliser Yarn uniquement si le dépôt contient également des packages ou scripts gérés par Node en dehors du périmètre Deno.
- Conserver
tsconfig.jsonuniquement pour les chemins appartenant à Node ou pour les cas de graphe de projet TypeScript que les espaces de travail Deno et les portées de répertoire ne peuvent pas exprimer proprement. - Se rappeler que Node moderne exécute également TypeScript directement via le stripping de types intégré ; choisir Deno pour son modèle d'exécution, de permissions, de dépendances et d'outillage, et non simplement pour éviter
tscouts-node. - Privilégier
deno lintetdeno fmtpour les fichiers appartenant à Deno ; ajouter ESLint uniquement si le dépôt ou l'éditeur a vraiment besoin de l'écosystème ESLint. - Lors du remplacement d'ESLint par
deno lint, inspecter et reporter l'intention ESLint existante dans les includes, excludes, règles de lint ou exceptions documentées dedeno.jsonau lieu de jeter la configuration en bloc. - Lors du remplacement de
tscpardeno check, inspecter letsconfig.jsonexistant et traduire les options de compilation, includes, excludes, libs et attentes de rigueur pertinentes dansdeno.jsonou untsconfig.jsonconservé clairement délimité. - Lorsque des outils d'éditeur basés sur npm tels qu'ESLint doivent s'exécuter dans un dépôt Deno, définir
nodeModulesDir: "auto"et envelopper la commande dansdeno task. - Lorsque Deno gère la gestion des dépendances, installer les dépendances avec
deno add, et non en traitantdeno run npm:<package>comme un substitut à l'installation. Utiliserdeno add --dev npm:<package>pour les CLI et outils de développement uniquement. - Pour les outils CLI installés, nommer la
deno taskd'après l'outil et invoquer le binaire installé par son nom, par exemple aprèsdeno add --dev npm:sample-tool, ajouter"sample-tool": "sample-tool". - Privilégier les modules
.tspar défaut dans le code appartenant à Deno ; ne pas passer à JavaScript simplement pour éviter une étape de build dont Deno n'a pas besoin. - Privilégier les packages JSR, les spécificateurs
npm:ou les entrées de carte d'import explicites plutôt que des importations URL héritées dispersées. - Lorsqu'une CLI basée sur npm a un comportement d'installation ou de post-installation qui ne coopère pas proprement avec une exécution ponctuelle, privilégier
nodeModulesDir: "auto", autoriser le package dansallowScripts, ajouter la dépendance avecdeno addoudeno add --dev, et invoquer le binaire installé depuis unedeno task. - Deno 2 est intentionnellement compatible avec
package.json, les packages npm et les built-ins Node ; conserver la configuration spécifique à Deno dansdeno.jsonau lieu d'essayer de faire porter les deux mondes partsconfig.json. - Privilégier les API Web standard et
Deno.servepour les serveurs. - Traiter les permissions comme une décision de conception, pas une réflexion après coup.
Cadre des tâches
| Commande ou action | Quoi | Pourquoi | Quand | Résultat attendu |
|---|---|---|---|---|
Adopter tsconfig.json et ESLint avec précaution | Décider ce qui reste dans la configuration appartenant à Node et ce qui passe dans deno.json. | Les dépôts hybrides deviennent vite bruyants lorsque les deux chaînes d'outils tentent de posséder les mêmes fichiers. | Lors de l'introduction de Deno dans une base de code TypeScript ou Node existante. | Les outils Deno et Node ont chacun des limites de propriété explicites. |
Configurer deno.json | Définir les tâches, options de compilation et conventions de dépendances dans le fichier de configuration Deno. | Deno doit posséder son propre workflow plutôt que d'emprunter accidentellement une configuration centrée sur Node. | Au démarrage ou lors de la restructuration d'un projet Deno. | Les commandes Deno et le comportement de l'éditeur sont cohérents. |
| Installer une CLI npm appartenant à Deno | Exécuter deno add --dev npm:<package> pour les outils de développement, puis ajouter une tâche du même nom qui invoque le binaire installé. | La dépendance, le fichier de verrouillage, le binaire local et le point d'entrée de la tâche restent alignés sous le gestionnaire de packages Deno. | Lors de l'ajout d'outils tels que des générateurs de code, des CLI d'automatisation de navigateur, des linters ou des formateurs à un workflow appartenant à Deno. | deno.json et le fichier de verrouillage enregistrent la dépendance, et deno task <tool> exécute la CLI installée. |
| Définir des limites hybrides | Séparer les chemins appartenant à Deno des chemins appartenant à Node dans les dépôts mixtes. | Les conflits d'outils sont l'une des pannes les plus courantes dans les dépôts hybrides. | Lorsque du code Deno côtoie des outils Node ou TS. | Les éditeurs et les commandes ne se battent pas pour les mêmes fichiers. |
| Réviser les permissions | Choisir des permissions explicites et des wrappers de tâches pour l'accès à l'exécution. | Le modèle de sécurité de Deno n'est utile que lorsque les permissions sont délibérées. | Avant d'exécuter de nouveaux scripts ou d'exposer un workflow CLI Deno. | L'accès au système de fichiers, au réseau et à l'environnement est intentionnel et vérifiable. |
| Dépanner les workflows Deno | Utiliser les vérifications natives Deno, les indicateurs de débogage et l'outillage du graphe de modules avant de deviner. | De nombreux problèmes Deno sont des problèmes de configuration, de permissions ou de propriété plutôt que des bugs de code. | Lorsqu'un dépôt hybride ou une chaîne d'outils migrée se comporte de manière inattendue. | La cause racine est réduite à la configuration, aux permissions ou au comportement d'exécution. |
Règles de base
TypeScript, tsconfig.json et bibliothèques
- Placer les paramètres du compilateur Deno dans
deno.jsonsouscompilerOptions; ne pas copier untsconfig.jsonNode complet juste pour faire fonctionnerdeno check. - Les espaces de travail Node plus TypeScript existants peuvent conserver
tsconfig.json; Deno le sonde lorsqu'un répertoire contient égalementdeno.jsonoupackage.json. - Si un
deno.jsonparent définit descompilerOptions, celles-ci priment sur les optionstsconfig.jsonqui se chevauchent. - Si l'objectif est de remplacer
tsc, d'abord inventorier le comportement actuel detsconfig.json. Conserver les décisions significatives de rigueur, de résolution de modules, JSX, bibliothèque, include et exclude dans la configuration Deno ou documenter pourquoi elles ne s'appliquent plus. - Utiliser
compilerOptions.libdansdeno.jsonpour modéliser la surface d'exécution réelle. Pour le code SSR ou navigateur plus Deno, privilégier des combinaisons comme["dom", "dom.iterable", "dom.asynciterable", "deno.ns"]; pour les workers Deno, privilégier["deno.worker"]. - Utiliser
compilerOptions.checkJs,// @ts-check,@ts-types,@ts-self-typesoucompilerOptions.typeslorsque les modules JavaScript ont besoin d'une vérification de type ou de déclarations explicites. - Conserver
tsconfig.jsonuniquement lorsque des dossiers appartenant à Node, des références de projet TS, ou une granularité d'include ou exclude l'exigent encore.
Linting, formatage et ESLint
- Utiliser
deno lintet la sectionlintdansdeno.jsoncomme propriétaire de lint par défaut pour le code appartenant à Deno. - Utiliser
deno fmtet la sectionfmtdansdeno.jsoncomme formateur par défaut pour le code appartenant à Deno. deno lintcouvre déjà un ensemble de règles recommandé inspiré d'ESLint ; ne pas conserver ESLint par habitude.- Si l'objectif est de remplacer ESLint, d'abord inventorier le comportement actuel de
eslint.config.*. Conserver les portées de fichiers, globals, ignores et l'intention des règles significatifs dans la configuration Deno lint/fmt ou documenter quelles règles sont intentionnellement abandonnées car Deno les couvre ou les rejette déjà. - Si des règles Deno personnalisées sont nécessaires, envisager
lint.plugins; noter que l'API de plugin de lint est expérimentale et nécessite Deno 2.2 ou plus récent. - Si le dépôt ou l'éditeur a toujours besoin d'ESLint, en faire un outil secondaire explicite : définir
nodeModulesDir: "auto", créereslint.config.js, et envelopper l'invocation dansdeno task, par exempledeno task eslint. - Conserver un seul propriétaire de lint par ensemble de fichiers autant que possible. Si
deno lintet ESLint s'exécutent tous deux sur les mêmes fichiers, documenter pourquoi ou s'attendre à des diagnostics en double et conflictuels.
Compatibilité Node et dépôts hybrides
- Deno 2 comprend
package.json,node_modules, les espaces de travail npm et les built-ins Node ; les dépôts hybrides sont un chemin pris en charge, pas une solution de contournement. - Node moderne peut aussi exécuter TypeScript directement. Dans les dépôts hybrides, décider de la propriété Node contre Deno en fonction des permissions, du modèle de dépendances, de l'exécuteur de tâches et de la cible de déploiement plutôt que de la seule exécution TypeScript.
- Si un
package.jsonexiste et que vous voulez que Deno crée et rafraîchisse automatiquementnode_modules, définirnodeModulesDir: "auto". Avecpackage.json, Deno 2 utilise par défaut"manual". nodeModulesDirest un paramètre de racine d'espace de travail ; ne pas essayer de le définir par membre d'espace de travail.- Utiliser
deno installoudeno addlorsque Deno possède le flux de mise à jour des dépendances. Ne pas supposer le comportement d'installation automatique de Deno 1. - Utiliser
deno add --dev npm:<package>pour les CLI npm de développement uniquement dans les dépôts appartenant à Deno. Après l'ajout, exposer le binaire via unedeno taskcomme"sample-tool": "sample-tool"au lieu de"sample-tool": "deno run -A npm:sample-tool". - Valider les mises à jour du manifeste et du fichier de verrouillage produites par
deno add; un alias de tâche seul n'est pas une installation de dépendance. - Ne pas activer l'outillage Deno pour un espace de travail mixte entier si un seul sous-arbre est Deno.
- Privilégier l'activation d'éditeur basée sur le chemin comme
deno.enablePathsafin que les outils Node et Deno ne se battent pas pour les mêmes fichiers. - Garder la frontière Deno explicite dans la structure des dossiers, les tâches et la documentation.
Permissions, environnement et sécurité
- Privilégier les indicateurs
--allow-*étroits ou des ensembles de permissions nommés dansdeno.jsonplutôt que-A. - Utiliser
-Pou--permission-set=<nom>lorsque le dépôt définit des ensembles de permissions dansdeno.json. - Utiliser
--env-filelorsque la CLI doit charger des fichiers.env, ou@std/dotenvlorsque le programme lui-même doit les charger ; les deux nécessitent toujours des permissions explicites d'environnement et de fichier. - Privilégier le moindre privilège pour le code d'application et garder l'accès à l'environnement, au système de fichiers, au réseau et aux sous-processus évident dans les tâches et les exemples.
- Traiter
--allow-runet--allow-fficomme des échappatoires de bac à sable. Éviter--allow-run=denosauf si une confiance totale est explicitement intentionnelle. - Pour le débogage ou l'audit des permissions, utiliser
DENO_TRACE_PERMISSIONS=1etDENO_AUDIT_PERMISSIONS=<chemin>.
Dépannage et migration
- Utiliser
deno check,deno check --alloudeno run --checklorsque le succès d'exécution et le comportement de vérification de type divergent. - Utiliser
deno info <point d'entrée>pour inspecter le graphe de modules et comprendre le comportement d'importation, de cache et de permissions. - Utiliser
deno lint --fixpour un nettoyage de migration courant avant d'éditer manuellement chaque problème de lint. - Pour la configuration du débogueur, utiliser
--inspect-brklorsque le processus est de courte durée,--log-level=debuglorsque l'inspecteur ou la résolution de modules est déroutant, et--strace-opslorsque l'exécution est bloquée ou anormalement lente. - Utiliser les indicateurs de profilage CPU comme
--cpu-prof,--cpu-prof-mdou--cpu-prof-flamegraphlorsque la question de dépannage concerne vraiment les performances. - Les conseils de migration doivent refléter les valeurs par défaut de Deno 2 :
nodeModulesDirutilise désormais"none" | "auto" | "manual",deno cacheest devenudeno install --entrypoint,deno vendorest devenu"vendor": true,Deno.run()doit devenirnew Deno.Command(), etDeno.serveHttp()doit devenirDeno.serve(). - Utiliser des attributs d'import comme
with { type: "json" }au lieu des assertions d'import obsolètes.
Pièges
- Si les outils Deno et Node revendiquent tous deux les mêmes fichiers, les diagnostics de l'éditeur deviennent bruyants et trompeurs.
- Si
package.jsonexiste, Deno 2 définitnodeModulesDirpar défaut sur"manual"; oublier ceci est une raison courante pour laquelle les outils basés sur npm semblent à moitié installés. - Si l'extension ESLint de VS Code fait partie du workflow, elle ne résoudra pas les packages depuis le cache global de Deno seul ; elle a besoin d'un répertoire
node_moduleslocal. deno runignore la vérification de type par défaut, donc une exécution réussie n'est pas une preuve quedeno checkréussira.- Une
deno taskqui délègue àdeno run npm:<package>est un raccourci d'exécution ponctuelle, pas une installation de dépendance appropriée. Ne pas l'utiliser comme réponse par défaut à « installer et configurer cette CLI » dans un dépôt appartenant à Deno. -Aest acceptable pour les outils de confiance, mais c'est la mauvaise valeur par défaut pour le code d'application ordinaire.- Certaines CLI npm, y compris Supabase dans de vrais dépôts hybrides, reposent sur un comportement au moment de l'installation qui peut être moins fiable via
deno run npm:...qu'avec un binaire installé sousnode_modules. - Les anciens motifs d'importation URL et d'activation d'espace de travail entier sont des aides de transition, pas des valeurs par défaut modernes.
Validation
deno.jsonpossède la configuration et les tâches Deno.- Tout
tsconfig.jsonou propriété ESLint conservé est explicite et limité aux fichiers appropriés. - Le remplacement d'ESLint ou de
tscpréserve le comportement utile de la configuration existante ou documente pourquoi il a été intentionnellement abandonné. - Les parties Deno et Node d'un dépôt hybride ne se battent pas pour l'outillage.
- Les spécificateurs de dépendance sont modernes et explicites.
- Les CLI npm appartenant à Deno sont ajoutées avec
deno addoudeno add --dev, enregistrées dans le manifeste et le fichier de verrouillage, et exécutées via des tâches qui invoquent les noms de binaires installés. nodeModulesDir, l'activation de l'éditeur et tout outillage Deno basé sur npm sont configurés intentionnellement.- Si une CLI npm est pilotée depuis des tâches Deno, le dépôt configure intentionnellement
nodeModulesDiretallowScriptsplutôt que de compter sur des effets secondaires d'installation accidentels. - Les permissions sont intentionnelles et documentées là où elles comptent.
- Les conseils de dépannage commencent par des vérifications natives Deno avant de recourir à des conseils de débogage Node ou TypeScript génériques.
Références
- Lire
./references/adoption-playbook.mdlorsque la tâche concernetsconfig.json, ESLint, la migration hybride Deno ou Node, ou le dépannage d'une frontière Deno. - Résumé LLM Deno : https://docs.deno.com/llms-summary.txt
- Référence de configuration Deno : https://docs.deno.com/runtime/fundamentals/configuration/
- Référence de configuration TypeScript Deno : https://docs.deno.com/runtime/reference/ts_config_migration/
- Référence de sécurité Deno : https://docs.deno.com/runtime/fundamentals/security/
- Lire `./references/che...