Deno
Zweck
Bietet portable Standardwerte für moderne Deno-Projekte, insbesondere wenn die Codebasis Deno mit Node-orientierten Tools mischt, einen sauberen Migrationspfad von älteren Deno-Mustern benötigt oder Deno in ein bestehendes TypeScript- oder Node-Repository integriert wird.
Wann diese Fertigkeit verwendet werden sollte
- Schreiben von Deno-Skripten, Servern oder Edge-Code.
- Konfigurieren von
deno.json, Aufgaben und Abhängigkeitsquellen. - Anpassen bestehender
tsconfig.json- odereslint.config.*-Dateien für die Koexistenz mit Deno. - Mischen von Deno-Code mit Node- oder TypeScript-Code in einem Repository.
- Überprüfen von Deno-Berechtigungen, Tests oder Laufzeitmustern.
Standardwerte
- Verwenden Sie
deno.jsonals die maßgebliche Quelle für Deno. - Bevorzugen Sie
deno check,deno task,deno fmt,deno lintunddeno testgegenüber Ad-hoc-Wrappern, wenn Deno den Workflow besitzt. - Die nativen Tools von Deno sind für Deno-eigenen Code ausreichend; verwenden Sie Yarn nur, wenn das Repository auch Node-verwaltete Pakete oder Skripte außerhalb der Deno-Grenze enthält.
- Behalten Sie
tsconfig.jsonnur für Node-eigene Pfade oder für TypeScript-Projektgraph-Fälle, die Deno-Arbeitsbereiche und Verzeichnisbereiche nicht sauber ausdrücken können. - Denken Sie daran, dass modernes Node TypeScript auch direkt durch integriertes Type-Stripping ausführt; wählen Sie Deno wegen seines Laufzeit-, Berechtigungs-, Abhängigkeits- und Tooling-Modells, nicht nur um
tscoderts-nodezu vermeiden. - Bevorzugen Sie
deno lintunddeno fmtfür Deno-eigene Dateien; fügen Sie ESLint nur hinzu, wenn das Repository oder der Editor wirklich das ESLint-Ökosystem benötigt. - Wenn Sie ESLint durch
deno lintersetzen, prüfen Sie die bestehende ESLint-Intention und übertragen Sie sie in die Includes, Excludes, Lint-Regeln oder dokumentierte Ausnahmen vondeno.json, anstatt die Konfiguration vollständig zu verwerfen. - Wenn Sie
tscdurchdeno checkersetzen, prüfen Sie die vorhandenetsconfig.jsonund übersetzen Sie relevante Compiler-Optionen, Includes, Excludes, Libs und Strenge-Erwartungen indeno.jsonoder eine klar abgegrenzte beibehaltenetsconfig.json. - Wenn npm-gestützte Editor-Tools wie ESLint in einem Deno-Repository ausgeführt werden müssen, setzen Sie
nodeModulesDir: "auto"und umschließen Sie den Befehl mitdeno task. - Wenn Deno das Abhängigkeitsmanagement besitzt, installieren Sie Abhängigkeiten mit
deno add, nicht indem Siedeno run npm:<package>als Ersatz für die Installation behandeln. Verwenden Siedeno add --dev npm:<package>für reine Entwicklungs-CLIs und Tools. - Für installierte CLI-Tools benennen Sie die
deno tasknach dem Tool und rufen Sie die installierte Binärdatei beim Namen auf, z. B. nachdeno add --dev npm:sample-toolfügen Sie"sample-tool": "sample-tool"hinzu. - Bevorzugen Sie standardmäßig
.ts-Module in Deno-eigenem Code; wechseln Sie nicht zu JavaScript, nur um einen Build-Schritt zu vermeiden, den Deno nicht benötigt. - Bevorzugen Sie JSR-Pakete,
npm:-Spezifizierer oder explizite Import-Map-Einträge gegenüber verstreuten Legacy-URL-Imports. - Wenn eine npm-gestützte CLI ein Installations- oder Postinstall-Verhalten hat, das nicht sauber mit einmaliger Ausführung zusammenarbeitet, bevorzugen Sie
nodeModulesDir: "auto", erlauben Sie das Paket inallowScripts, fügen Sie die Abhängigkeit mitdeno addoderdeno add --devhinzu und rufen Sie die installierte Binärdatei aus einemdeno taskauf. - Deno 2 ist absichtlich kompatibel mit
package.json, npm-Paketen und Node-Builtins; behalten Sie Deno-spezifische Konfiguration indeno.json, anstatt zu versuchen,tsconfig.jsonbeide Welten tragen zu lassen. - Bevorzugen Sie Web-Standard-APIs und
Deno.servefür Server. - Behandeln Sie Berechtigungen als Designentscheidung, nicht als nachträglichen Einfall.
Aufgabenrahmen
| Befehl oder Aktion | Was | Warum | Wann | Erwartetes Ergebnis |
|---|---|---|---|---|
Übernahme von tsconfig.json und ESLint sorgfältig | Entscheiden, was in der Node-eigenen Konfiguration bleibt und was in deno.json übergeht. | Hybride Repos werden schnell laut, wenn beide Toolchains dieselben Dateien besitzen wollen. | Wenn Deno in eine bestehende TypeScript- oder Node-Codebasis eingeführt wird. | Deno- und Node-Tools haben explizite Eigentumsgrenzen. |
Konfigurieren von deno.json | Definieren von Aufgaben, Compiler-Optionen und Abhängigkeitskonventionen in Denos Konfigurationsdatei. | Deno sollte seinen eigenen Workflow besitzen, anstatt Node-zentrierte Konfiguration versehentlich zu übernehmen. | Beim Starten oder Umstrukturieren eines Deno-Projekts. | Deno-Befehle und Editor-Verhalten sind konsistent. |
| Installieren einer Deno-eigenen npm-CLI | Führen Sie deno add --dev npm:<package> für Entwicklungstools aus, fügen Sie dann eine gleichnamige Aufgabe hinzu, die die installierte Binärdatei aufruft. | Die Abhängigkeit, Lockdatei, lokale Binärdatei und der Aufgaben-Einstiegspunkt bleiben unter Denos Paketmanager abgestimmt. | Beim Hinzufügen von Tools wie Codegeneratoren, Browser-Automatisierungs-CLIs, Linter oder Formatierer zu einem Deno-eigenen Workflow. | deno.json und die Lockdatei zeichnen die Abhängigkeit auf, und deno task <tool> führt die installierte CLI aus. |
| Festlegen hybrider Grenzen | Trennen Sie Deno-eigene Pfade von Node-eigenen Pfaden in gemischten Repositories. | Tooling-Konflikte sind einer der häufigsten Fehler in Hybrid-Repos. | Wenn Deno-Code neben Node- oder TS-Tools lebt. | Editoren und Befehle kämpfen nicht um dieselben Dateien. |
| Überprüfen von Berechtigungen | Wählen Sie explizite Berechtigungen und Aufgaben-Wrapper für den Laufzeitzugriff. | Denos Sicherheitsmodell hilft nur, wenn Berechtigungen bewusst gewählt werden. | Bevor Sie neue Skripte ausführen oder einen Deno-CLI-Workflow bereitstellen. | Dateisystem-, Netzwerk- und Umgebungszugriff sind absichtlich und prüfbar. |
| Fehlerbehebung bei Deno-Workflows | Verwenden Sie Deno-native Prüfungen, Debugger-Flags und Modul-Graph-Tools, bevor Sie raten. | Viele Deno-Probleme sind Konfigurations-, Berechtigungs- oder Eigentumsprobleme und keine Code-Fehler. | Wenn ein Hybrid-Repo oder eine migrierte Toolchain unerwartet reagiert. | Die Grundursache wird auf Konfiguration, Berechtigungen oder Laufzeitverhalten eingegrenzt. |
Kernregeln
TypeScript, tsconfig.json und Bibliotheken
- Legen Sie Deno-Compiler-Einstellungen in
deno.jsonuntercompilerOptionsfest; kopieren Sie keine vollständige Node-tsconfig.json, nur umdeno checkauszuführen. - Bestehende Node- plus TypeScript-Arbeitsbereiche können
tsconfig.jsonbehalten; Deno prüft sie, wenn ein Verzeichnis auchdeno.jsonoderpackage.jsonenthält. - Wenn ein übergeordnetes
deno.jsoncompilerOptionsdefiniert, haben diese Vorrang vor überlappendentsconfig.json-Optionen. - Wenn das Ziel darin besteht,
tsczu ersetzen, inventarisieren Sie zunächst das aktuelletsconfig.json-Verhalten. Bewahren Sie sinnvolle Strenge, Modulauflösung, JSX, Bibliotheks-, Include- und Exclude-Entscheidungen in der Deno-Konfiguration oder dokumentieren Sie, warum sie nicht mehr gelten. - Verwenden Sie
compilerOptions.libindeno.json, um die tatsächliche Laufzeitoberfläche zu modellieren. Für SSR- oder Browser- plus Deno-Code bevorzugen Sie Kombinationen wie["dom", "dom.iterable", "dom.asynciterable", "deno.ns"]; für Deno-Worker bevorzugen Sie["deno.worker"]. - Verwenden Sie
compilerOptions.checkJs,// @ts-check,@ts-types,@ts-self-typesodercompilerOptions.types, wenn JavaScript-Module eine explizite Typprüfung oder Deklarationen benötigen. - Behalten Sie
tsconfig.jsonnur, wenn Node-eigene Ordner, TS-Projektreferenzen oder Include- oder Exclude-Granularität es weiterhin erfordern.
Linting, Formatierung und ESLint
- Verwenden Sie
deno lintund den Abschnittlintindeno.jsonals Standard-Lint-Eigentümer für Deno-eigenen Code. - Verwenden Sie
deno fmtund den Abschnittfmtindeno.jsonals Standard-Formatierung für Deno-eigenen Code. deno lintdeckt bereits ein empfohlenes Regelset ab, das von ESLint inspiriert ist; behalten Sie ESLint nicht aus Gewohnheit.- Wenn das Ziel darin besteht, ESLint zu ersetzen, inventarisieren Sie zunächst das aktuelle
eslint.config.*-Verhalten. Bewahren Sie sinnvolle Dateibereiche, Globals, Ignores und Regelabsichten in der Deno-Lint/Fmt-Konfiguration oder dokumentieren Sie, welche Regeln absichtlich fallen gelassen werden, weil Deno sie bereits abdeckt oder ablehnt. - Wenn benutzerdefinierte Deno-spezifische Regeln erforderlich sind, ziehen Sie
lint.pluginsin Betracht; beachten Sie, dass die Lint-Plugin-API experimentell ist und Deno 2.2 oder neuer erfordert. - Wenn das Repository oder der Editor weiterhin ESLint benötigt, machen Sie es zu einem expliziten sekundären Tool: setzen Sie
nodeModulesDir: "auto", erstellen Sieeslint.config.jsund umschließen Sie den Aufruf mitdeno task, z. B.deno task eslint. - Behalten Sie nach Möglichkeit einen Lint-Eigentümer pro Dateisatz. Wenn sowohl
deno lintals auch ESLint auf denselben Dateien ausgeführt werden, dokumentieren Sie warum oder rechnen Sie mit doppelten und widersprüchlichen Diagnosen.
Node-Kompatibilität und hybride Repositories
- Deno 2 versteht
package.json,node_modules, npm-Arbeitsbereiche und Node-Builtins; hybride Repos sind ein unterstützter Pfad, keine Problemumgehung. - Modernes Node kann TypeScript auch direkt ausführen. Entscheiden Sie in hybriden Repos über Node- versus Deno-Eigentum anhand von Berechtigungen, Abhängigkeitsmodell, Task-Runner und Bereitstellungsziel, nicht nur anhand der TypeScript-Ausführung.
- Wenn eine
package.jsonexistiert und Sie möchten, dass Denonode_modulesautomatisch erstellt und aktualisiert, setzen SienodeModulesDir: "auto". Mitpackage.jsonstandardmäßig Deno 2 sonst auf"manual". nodeModulesDirist eine Arbeitsbereichs-Stamm-Einstellung; versuchen Sie nicht, sie pro Arbeitsbereichsmitglied zu setzen.- Verwenden Sie
deno installoderdeno add, wenn Deno den Abhängigkeitsaktualisierungsfluss besitzt. Gehen Sie nicht vom automatischen Installationsverhalten von Deno 1 aus. - Verwenden Sie
deno add --dev npm:<package>für reine Entwicklungs-npm-CLIs in Deno-eigenen Repositories. Nach dem Hinzufügen machen Sie die Binärdatei über einendeno taskverfügbar, z. B."sample-tool": "sample-tool"anstelle von"sample-tool": "deno run -A npm:sample-tool". - Checken Sie die durch
deno adderstellten Manifest- und Lockdatei-Updates ein; ein Task-Alias allein ist keine Abhängigkeitsinstallation. - Aktivieren Sie Deno-Tooling nicht für einen gesamten gemischten Arbeitsbereich, wenn nur ein Teilbaum Deno ist.
- Bevorzugen Sie pfadbasierte Editor-Aktivierung wie
deno.enablePaths, damit Node- und Deno-Tools nicht um dieselben Dateien kämpfen. - Halten Sie die Deno-Grenze in der Ordnerstruktur, in Aufgaben und in der Dokumentation explizit.
Berechtigungen, Umgebung und Sicherheit
- Bevorzugen Sie enge
--allow-*-Flags oder benannte Berechtigungssätze indeno.jsongegenüber-A. - Verwenden Sie
-Poder--permission-set=<name>, wenn das Repository Berechtigungssätze indeno.jsondefiniert. - Verwenden Sie
--env-file, wenn die CLI.env-Dateien laden soll, oder@std/dotenv, wenn das Programm sie selbst laden muss; beide benötigen dennoch explizite Umgebungs- und Dateiberechtigungen. - Bevorzugen Sie das Prinzip der geringsten Rechte für Anwendungscode und halten Sie Umgebungs-, Dateisystem-, Netzwerk- und Unterprozesszugriff in Aufgaben und Beispielen offensichtlich.
- Behandeln Sie
--allow-runund--allow-ffials Sandbox-Ausweichmöglichkeiten. Vermeiden Sie--allow-run=deno, es sei denn, volles Vertrauen ist ausdrücklich beabsichtigt. - Verwenden Sie zur Berechtigungsdebugging oder -prüfung
DENO_TRACE_PERMISSIONS=1undDENO_AUDIT_PERMISSIONS=<pfad>.
Fehlerbehebung und Migration
- Greifen Sie zu
deno check,deno check --alloderdeno run --check, wenn Laufzeiterfolg und Typprüfungsverhalten auseinandergehen. - Verwenden Sie
deno info <einstiegspunkt>, um den Modulgraphen zu inspizieren und das Import-, Cache- und Berechtigungsverhalten zu verstehen. - Verwenden Sie
deno lint --fixfür allgemeine Migrationsbereinigung, bevor Sie jedes Lint-Problem manuell bearbeiten. - Verwenden Sie für die Debugger-Einrichtung
--inspect-brk, wenn der Prozess kurzlebig ist,--log-level=debugwenn der Inspektor oder die Modulauflösung verwirrend ist, und--strace-ops, wenn die Laufzeit hängt oder unerwartet langsam ist. - Verwenden Sie CPU-Profiling-Flags wie
--cpu-prof,--cpu-prof-mdoder--cpu-prof-flamegraph, wenn es bei der Fehlerbehebung wirklich um die Leistung geht. - Migrationshinweise sollten die Deno 2-Standardwerte widerspiegeln:
nodeModulesDirverwendet jetzt"none" | "auto" | "manual",deno cachewurde zudeno install --entrypoint,deno vendorwurde zu"vendor": true,Deno.run()sollte zunew Deno.Command()werden undDeno.serveHttp()sollte zuDeno.serve()werden. - Verwenden Sie Import-Attribute wie
with { type: "json" }anstelle von veralteten Import-Assertions.
Fallstricke
- Wenn Deno- und Node-Tools dieselben Dateien beanspruchen, werden Editor-Diagnosen laut und irreführend.
- Wenn
package.jsonexistiert, standardmäßig Deno 2nodeModulesDirauf"manual"; dies zu vergessen ist ein häufiger Grund, warum npm-gestützte Tools halb installiert aussehen. - Wenn die VS Code ESLint-Erweiterung Teil des Workflows ist, wird sie Pakete nicht allein aus dem globalen Deno-Cache auflösen; sie benötigt ein lokales
node_modules-Verzeichnis. deno runüberspringt standardmäßig die Typprüfung, also ist ein erfolgreicher Lauf kein Beweis dafür, dassdeno checkbestanden wird.- Ein
deno task, der zudeno run npm:<package>auslagert, ist eine einmalige Ausführungsabkürzung, keine ordnungsgemäße Abhängigkeitsinstallation. Verwenden Sie es nicht als Standardantwort auf "Installiere und richte diese CLI ein" in einem Deno-eigenen Repo. -Aist für vertrauenswürdige Tools akzeptabel, aber es ist der falsche Standard für gewöhnlichen Anwendungscode.- Einige npm-CLIs, einschließlich Supabase in echten gemischten Laufzeit-Repos, verlassen sich auf Installationszeitverhalten, das durch
deno run npm:...weniger zuverlässig sein kann als durch eine installierte Binärdatei unternode_modules. - Alte URL-Import- und gesamte Arbeitsbereichsaktivierungsmuster sind Übergangshilfen, keine modernen Standardwerte.
Validierung
deno.jsonbesitzt die Deno-Konfiguration und -Aufgaben.- Jede beibehaltene
tsconfig.json- oder ESLint-Eigentumsverhältnisse sind explizit und auf die richtigen Dateien beschränkt. - Das Ersetzen von ESLint oder
tscbewahrt das nützliche Verhalten aus der vorhandenen Konfiguration oder dokumentiert, warum es absichtlich fallen gelassen wurde. - Die Deno- und Node-Teile eines Hybrid-Repos kämpfen nicht um Tooling.
- Abhängigkeitsspezifizierer sind modern und explizit.
- Deno-eigene npm-CLIs werden mit
deno addoderdeno add --devhinzugefügt, im Manifest und der Lockdatei aufgezeichnet und über Aufgaben ausgeführt, die installierte Binärdateinamen aufrufen. nodeModulesDir, Editor-Aktivierung und jedes npm-gestützte Deno-Tooling sind bewusst konfiguriert.- Wenn eine npm-CLI aus Deno-Aufgaben gesteuert wird, konfiguriert das Repository bewusst
nodeModulesDirundallowScripts, anstatt sich auf zufällige Installationsnebenwirkungen zu verlassen. - Berechtigungen sind absichtlich und dokumentiert, wo sie wichtig sind.
- Die Fehlerbehebungsanleitung beginnt mit Deno-nativen Prüfungen, bevor auf generische Node- oder TypeScript-Debugging-Ratschläge zurückgegriffen wird.
Referenzen
- Lesen Sie
./references/adoption-playbook.md, wenn die Aufgabetsconfig.json, ESLint, hybride Deno- oder Node-Migration oder die Fehlerbehebung einer Deno-Grenze betrifft. - Deno LLM Summary: https://docs.deno.com/llms-summary.txt
- Deno Configuration Reference: https://docs.deno.com/runtime/fundamentals/configuration/
- Deno TypeScript Configuration Reference: https://docs.deno.com/runtime/reference/ts_config_migration/
- Deno Security Reference: https://docs.deno.com/runtime/fundamentals/security/
- Lesen Sie
./references/che