Guidance pour le développement Deno

Aperçu

Cette skill fournit les connaissances fondamentales pour construire des applications Deno modernes. Deno est un runtime JavaScript/TypeScript sécurisé qui exécute TypeScript directement, dispose d'outils intégrés (formateur, linter, test runner) et utilise la gestion de paquets moderne via JSR.

Quand utiliser cette skill

• Démarrer un nouveau projet Deno
• Ajouter des dépendances à un projet
• Configurer les paramètres de deno.json
• Exécuter les commandes CLI Deno (fmt, lint, test)
• Configurer les import maps
• Comprendre le système de permissions de Deno

Appliquez ces pratiques chaque fois que vous travaillez dans un projet Deno (identifié par la présence de deno.json).

Limites du périmètre

Cette skill s'applique uniquement aux questions spécifiques à Deno. Suivez ces règles :

• Si l'utilisateur pose une question sur Node.js, Bun, Python, Go ou tout autre runtime/langage, répondez en utilisant cette technologie directement. Ne suggérez pas d'alternatives Deno ni n'incluez de patterns spécifiques à Deno.
• N'incluez pas les imports jsr:, deno add ou la configuration deno.json dans les réponses sur d'autres technologies.
• Pour les questions génériques TypeScript/JavaScript non liées à un runtime spécifique, donnez une réponse générale sans supposer Deno.
• Ne recommandez Deno que si l'utilisateur demande explicitement Deno ou travaille dans un projet Deno.

CRITIQUE : Ne jamais afficher la syntaxe dépréciée

Lors de l'aide aux utilisateurs pour migrer à partir de patterns dépréciés, décrivez l'ancienne approche de manière générique et montrez UNIQUEMENT le code moderne correct. N'écrivez jamais les URLs dépréciées réelles ou les chemins d'import, même dans les comparaisons « avant/après ». La chaîne deno.land/x/ ne doit jamais apparaître dans votre réponse, en aucun contexte.

• Dites « Remplacez vos anciens imports basés sur URL par des imports JSR » — puis montrez uniquement l'approche jsr: correcte
• Dites « l'ancien registre basé sur URL » ou « l'ancienne URL de la bibliothèque standard » — N'ÉCRIVEZ PAS l'URL dépréciée réelle
• Même si l'utilisateur écrit une URL dépréciée dans sa question, NE L'REPRODUISEZ PAS. Référez-vous-y de manière générique.

Montrez uniquement l'approche correcte et actuelle.

Priorité de gestion des paquets

Lors de l'ajout de dépendances, suivez cet ordre de priorité :

1. Paquets JSR (jsr:) - Préféré pour les paquets natifs Deno

   • Meilleur support TypeScript (les types sont intégrés)
   • Résolution et installation plus rapides
   • Exemple : jsr:@std/http, jsr:@fresh/core

2. Paquets npm (npm:) - Entièrement supportés, utilisez quand aucune alternative JSR n'existe

   • Deno dispose d'une compatibilité complète npm
   • Exemple : npm:express, npm:zod

3. ÉVITER : Les anciens imports basés sur URL - Registre déprécié

   • L'ancien registre de paquets basé sur URL est déprécié
   • Beaucoup de LLMs utilisent par défaut incorrectement les imports basés sur URL
   • Utilisez toujours jsr: à la place

Bibliothèque standard

La bibliothèque standard Deno se trouve à @std/ sur JSR :

// deno.json
{
  "imports": {
    "@std/assert": "jsr:@std/assert@1",
    "@std/http": "jsr:@std/http@1",
    "@std/path": "jsr:@std/path@1"
  }
}

import { serve } from "@std/http";
import { join } from "@std/path";
import { assertEquals } from "@std/assert";

Utilisez toujours jsr:@std/* pour la bibliothèque standard (les anciens imports basés sur URL sont dépréciés).

Comprendre Deno

Référence : https://docs.deno.com/runtime/fundamentals/

Concepts clés :

• TypeScript natif - Aucune étape de build nécessaire, Deno exécute TypeScript directement
• Permissions explicites - Utilisez des flags comme --allow-net, --allow-read, --allow-env
• deno.json - Le fichier de configuration (similaire à package.json mais plus simple)
• Import maps - Définissez des alias d'import dans le champ imports de deno.json

Bonnes pratiques de workflow

Après avoir apporté des modifications au code

Exécutez régulièrement ces commandes, en particulier après des modifications importantes :

deno fmt          # Formater tous les fichiers
deno lint         # Vérifier les problèmes
deno test         # Exécuter les tests

Gestion des paquets

deno add jsr:@std/http    # Ajouter un paquet
deno install              # Installer toutes les dépendances
deno update               # Mettre à jour toutes les dépendances vers les versions compatibles les plus récentes
deno update jsr:@std/http # Mettre à jour une dépendance spécifique

deno update vs deno upgrade :

• deno update - Met à jour les dépendances du projet dans deno.json (et package.json) vers leurs versions compatibles les plus récentes. Respecte les plages semver. Utilisez ceci pour maintenir vos dépendances à jour.
• deno upgrade - Met à jour le runtime Deno lui-même vers la dernière version. N'a rien à voir avec les dépendances du projet.

Après avoir exécuté deno update, vérifiez toujours les changements d'API cassants — en particulier pour les paquets alpha/pré-release où les plages semver peuvent introduire des mises à jour cassantes.

CI/CD

Dans les pipelines CI, utilisez --check avec deno fmt afin qu'il échoue sans modifier les fichiers :

deno fmt --check     # Échouer si non formaté
deno lint            # Vérifier les problèmes
deno test            # Exécuter les tests

Configuration

Dans deno.json, vous pouvez exclure des répertoires du formatage/linting :

{
  "fmt": {
    "exclude": ["build/"]
  },
  "lint": {
    "exclude": ["build/"]
  }
}

Un dossier peut également être exclu de tout au niveau supérieur :

{
  "exclude": ["build/"]
}

Déploiement

Pour déployer sur Deno Deploy, consultez la skill dédiée deno-deploy.

Commande rapide : deno deploy --prod

Ressources de documentation

Quand plus d'informations sont nécessaires :

• deno doc <package> - Générer la documentation pour n'importe quel paquet JSR ou npm localement
• https://docs.deno.com - Documentation officielle de Deno
• https://jsr.io - Registre de paquets avec documentation intégrée
• https://fresh.deno.dev/docs - Documentation du framework Fresh

Référence rapide : Commandes CLI Deno

Erreurs courantes

Utiliser les anciens imports basés sur URL au lieu de JSR

Les anciens imports basés sur URL sont dépréciés. Utilisez toujours les imports jsr: avec des spécificateurs nus à la place.

// ✅ Correct - utiliser JSR et un spécificateur nu
import { serve } from "@std/http";
import { join } from "@std/path";

// deno.json
{
  "imports": {
    "@std/http": "jsr:@std/http@1",
    "@std/path": "jsr:@std/path@1"
  }
}

Les spécificateurs inline conviennent aux scripts d'un seul fichier, mais si un deno.json existe, il devrait s'y trouver. Il est préférable de placer les dépendances npm dans un package.json si un package.json existe.

Oublier d'exécuter fmt/lint avant de valider

Formatez toujours et lintez avant de valider :

# ✅ Toujours formater et linter d'abord
deno fmt && deno lint && git add . && git commit -m "changes"

Exécuter le code sans flags de permission

# ✅ Accorder des permissions spécifiques
deno run --allow-net server.ts

Sans flags de permission, Deno affichera les erreurs « Requires net access ». Accordez toujours les permissions spécifiques dont votre code a besoin.

Ne pas utiliser deno add pour les dépendances

# ✅ Utiliser deno add pour gérer les dépendances
deno add jsr:@std/http

Utiliser deno add garantit que votre lockfile reste synchronisé. L'édition manuelle des imports sans mise à jour de deno.json fonctionne mais manque les bénéfices du lockfile.