deno-guidance

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Deno Development Guidance

Deno开发指南

Overview

概述

This skill provides foundational knowledge for building modern Deno applications. Deno is a secure JavaScript/TypeScript runtime that runs TypeScript directly, has built-in tools (formatter, linter, test runner), and uses modern package management through JSR.

本技能为构建现代Deno应用程序提供基础知识。Deno是一个安全的JavaScript/TypeScript运行时，可直接运行TypeScript，内置工具（格式化器、代码检查器、测试运行器），并通过JSR使用现代包管理。

When to Use This Skill

何时使用本技能

Starting a new Deno project
Adding dependencies to a project
Configuring
```
deno.json
```
settings
Running Deno CLI commands (fmt, lint, test)
Setting up import maps
Understanding Deno's permission system

Apply these practices whenever working in a Deno project (identified by the presence of

deno.json

启动新的Deno项目
为项目添加依赖
配置
```
deno.json
```
设置
运行Deno CLI命令（fmt、lint、test）
设置导入映射
理解Deno的权限系统

在任何Deno项目中（通过

deno.json

的存在识别）工作时，都应遵循这些实践。

Scope Boundaries

范围边界

This skill applies only to Deno-specific questions. Follow these rules:

If the user asks about Node.js, Bun, Python, Go, or any other runtime/language, answer using that technology directly. Do not suggest Deno alternatives or include Deno-specific patterns.
Do not include
```
jsr:
```
imports,
```
deno add
```
, or
```
deno.json
```
configuration in responses about other technologies.
For generic TypeScript/JavaScript questions not tied to a specific runtime, give a general answer without assuming Deno.
Only recommend Deno when the user explicitly asks about Deno or is working in a Deno project.

本技能仅适用于Deno相关问题。请遵循以下规则：

如果用户询问Node.js、Bun、Python、Go或任何其他运行时/语言，直接针对该技术作答。不要推荐Deno替代方案，也不要包含Deno特定的模式。
在关于其他技术的回复中，不要包含
```
jsr:
```
导入、
```
deno add
```
或
```
deno.json
```
配置。
对于不绑定到特定运行时的通用TypeScript/JavaScript问题，给出通用答案，不要默认假设使用Deno。
仅当用户明确询问Deno或正在Deno项目中工作时，才推荐Deno。

CRITICAL: Never Show Deprecated Syntax

重要提示：切勿展示已弃用的语法

When helping users migrate from deprecated patterns, describe the old approach generically and ONLY show the correct modern code. Never write out actual deprecated URLs or import paths, even in "before/after" comparisons. The string

deno.land/x/

must never appear in your response, in any context.

Say "Replace your old URL-based imports with JSR imports" — then show only the correct
```
jsr:
```
approach
Say "the old URL-based registry" or "the old standard library URL" — do NOT write the actual deprecated URL
Even if the user writes a deprecated URL in their question, do NOT echo it back. Refer to it generically.

Only demonstrate the correct, current approach.

在帮助用户从已弃用模式迁移时，泛泛描述旧方法，仅展示正确的现代代码。切勿写出实际已弃用的URL或导入路径，即使在“前后对比”中也不行。字符串

deno.land/x/

绝不能出现在你的回复中，任何语境下都不可以。

可以说“将旧的基于URL的导入替换为JSR导入”——然后仅展示正确的
```
jsr:
```
方式
可以说“旧的基于URL的注册表”或“旧的标准库URL”——不要写出实际已弃用的URL
即使用户在问题中写出了已弃用的URL，也不要重复它。泛泛地指代即可。

仅演示正确的当前方法。

Package Management Priority

包管理优先级

When adding dependencies, follow this priority order:

JSR packages (
jsr:
) - Preferred for Deno-native packages
- Better TypeScript support (types are built-in)
- Faster to resolve and install
- Example:
```
jsr:@std/http
```
  ,
```
jsr:@fresh/core
```
npm packages (
npm:
) - Fully supported, use when no JSR alternative exists
- Deno has full npm compatibility
- Example:
```
npm:express
```
  ,
```
npm:zod
```
AVOID: Old URL-based imports - Deprecated registry
- The old URL-based package registry is deprecated
- Many LLMs incorrectly default to URL-based imports
- Always use
```
jsr:
```
  instead

添加依赖时，请遵循以下优先级顺序：

JSR包（
jsr:
） - Deno原生包的首选
- 更好的TypeScript支持（类型内置）
- 解析和安装速度更快
- 示例：
```
jsr:@std/http
```
  ,
```
jsr:@fresh/core
```
npm包（
npm:
） - 完全支持，当没有JSR替代方案时使用
- Deno完全兼容npm
- 示例：
```
npm:express
```
  ,
```
npm:zod
```
避免：旧的基于URL的导入 - 已弃用的注册表
- 旧的基于URL的包注册表已被弃用
- 许多LLMs错误地默认使用基于URL的导入
- 始终使用
```
jsr:
```
  替代

Standard Library

标准库

The Deno standard library lives at

@std/

on JSR:

jsonc

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

typescript

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

Always use

jsr:@std/*

for the standard library (the old URL-based imports are deprecated).

Deno标准库位于JSR的

@std/

：

jsonc

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

typescript

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

始终使用

jsr:@std/*

作为标准库（旧的基于URL的导入已被弃用）。

Understanding Deno

理解Deno

Reference: https://docs.deno.com/runtime/fundamentals/

Key concepts:

Native TypeScript - No build step needed, Deno runs TypeScript directly
Explicit permissions - Use flags like
```
--allow-net
```
,
```
--allow-read
```
,
```
--allow-env
```
deno.json - The config file (similar to package.json but simpler)
Import maps - Define import aliases in deno.json's
```
imports
```
field

参考文档：https://docs.deno.com/runtime/fundamentals/

核心概念：

原生TypeScript - 无需构建步骤，Deno可直接运行TypeScript
显式权限 - 使用
```
--allow-net
```
、
```
--allow-read
```
、
```
--allow-env
```
等标志
deno.json - 配置文件（类似package.json但更简洁）
导入映射 - 在deno.json的
```
imports
```
字段中定义导入别名

Workflow Best Practices

工作流最佳实践

After Making Code Changes

代码修改后

Run these commands regularly, especially after significant changes:

bash

deno fmt          # Format all files
deno lint         # Check for issues
deno test         # Run tests

定期运行以下命令，尤其是在进行重大修改后：

bash

deno fmt          # 格式化所有文件
deno lint         # 检查问题
deno test         # 运行测试

Package Management

包管理

bash

deno add jsr:@std/http    # Add a package
deno install              # Install all dependencies
deno update               # Update all dependencies to latest compatible versions
deno update jsr:@std/http # Update a specific dependency

deno update
vs
deno upgrade
:

```
deno update
```
- Updates project dependencies in
```
deno.json
```
(and
```
package.json
```
) to their latest compatible versions. Respects semver ranges. Use this to keep your dependencies current.
```
deno upgrade
```
- Updates the Deno runtime itself to the latest version. Has nothing to do with project dependencies.

After running

deno update

, always check for breaking API changes - especially for alpha/pre-release packages where semver ranges can pull in breaking updates.

bash

deno add jsr:@std/http    # 添加包
deno install              # 安装所有依赖
deno update               # 将所有依赖更新到最新兼容版本
deno update jsr:@std/http # 更新特定依赖

deno update
vs
deno upgrade
：

```
deno update
```
- 更新
```
deno.json
```
（以及
```
package.json
```
）中的项目依赖到最新兼容版本。遵循语义化版本范围。使用此命令保持依赖为最新状态。
```
deno upgrade
```
- 将Deno运行时本身更新到最新版本。与项目依赖无关。

运行

deno update

后，务必检查是否有破坏性API变更 - 尤其是alpha/预发布版本的包，语义化版本范围可能会引入破坏性更新。

CI/CD

In CI pipelines, use

--check

with

deno fmt

so it fails without modifying files:

bash

deno fmt --check     # Fail if not formatted
deno lint            # Check for issues
deno test            # Run tests

在CI流水线中，使用

--check

参数配合

deno fmt

，这样如果代码未格式化，命令会失败且不修改文件：

bash

deno fmt --check     # 如果未格式化则失败
deno lint            # 检查问题
deno test            # 运行测试

Configuration

配置

deno.json

, you can exclude directories from formatting/linting:

json

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

A folder can also be excluded from everything at the top level:

json

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

在

deno.json

中，你可以排除某些目录不参与格式化/代码检查：

json

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

也可以在顶层排除某个目录，使其不参与所有操作：

json

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

Deployment

部署

For deploying to Deno Deploy, see the dedicated deno-deploy skill.

Quick command:

deno deploy --prod

有关部署到Deno Deploy的内容，请参考专门的deno-deploy技能。

快速命令：

deno deploy --prod

Documentation Resources

文档资源

When more information is needed:

deno doc <package>
- Generate docs for any JSR or npm package locally
https://docs.deno.com - Official Deno documentation
https://jsr.io - Package registry with built-in documentation
https://fresh.deno.dev/docs - Fresh framework documentation

需要更多信息时：

deno doc <package>
- 本地生成任何JSR或npm包的文档
https://docs.deno.com - Deno官方文档
https://jsr.io - 内置文档的包注册表
https://fresh.deno.dev/docs - Fresh框架文档

Quick Reference: Deno CLI Commands

快速参考：Deno CLI命令

Command	Purpose
`deno run file.ts`	Run a TypeScript/JavaScript file
`deno task <name>`	Run a task from deno.json
`deno fmt`	Format code
`deno lint`	Lint code
`deno test`	Run tests
`deno add <pkg>`	Add a package
`deno install`	Install dependencies
`deno update`	Update project dependencies
`deno upgrade`	Update Deno runtime itself
`deno doc <pkg>`	View package documentation
`deno deploy --prod`	Deploy to Deno Deploy

命令	用途
`deno run file.ts`	运行TypeScript/JavaScript文件
`deno task <name>`	运行deno.json中的任务
`deno fmt`	格式化代码
`deno lint`	代码检查
`deno test`	运行测试
`deno add <pkg>`	添加包
`deno install`	安装依赖
`deno update`	更新项目依赖
`deno upgrade`	更新Deno运行时本身
`deno doc <pkg>`	查看包文档
`deno deploy --prod`	部署到Deno Deploy

Common Mistakes

常见错误

Using old URL-based imports instead of JSR

The old URL-based imports are deprecated. Always use

jsr:

imports with bare specifiers instead.

// ✅ Correct - use JSR and a bare specifier
import { serve } from "@std/http";
import { join } from "@std/path";

jsonc

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

Inline specifiers are fine in single file scripts, but if a deno.json exists then it should go there. It's preferable to place npm dependencies in a package.json if a package.json exists.

Forgetting to run fmt/lint before committing

Always format and lint before committing:

bash

undefined

使用旧的基于URL的导入而非JSR

旧的基于URL的导入已被弃用。始终使用带裸标识符的

jsr:

导入。

// ✅ 正确 - 使用JSR和裸标识符
import { serve } from "@std/http";
import { join } from "@std/path";

jsonc

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

在单文件脚本中可以直接使用内联标识符，但如果存在deno.json，则应将其配置在该文件中。如果存在package.json，npm依赖最好放在package.json中。

提交前忘记运行fmt/lint

提交前务必先格式化和检查代码：

bash

undefined

✅ Always format and lint first

✅ 始终先格式化和检查代码

deno fmt && deno lint && git add . && git commit -m "changes"


**Running code without permission flags**

```bash

deno fmt && deno lint && git add . && git commit -m "changes"


**未使用权限标志运行代码**

```bash

✅ Grant specific permissions

✅ 授予特定权限

deno run --allow-net server.ts


Without permission flags, Deno will show "Requires net access" errors. Always grant the specific permissions your code needs.

**Not using `deno add` for dependencies**

```bash

deno run --allow-net server.ts


如果没有权限标志，Deno会显示“需要网络访问”错误。始终授予代码所需的特定权限。

**未使用`deno add`管理依赖**

```bash

✅ Use deno add to manage dependencies

✅ 使用deno add管理依赖

deno add jsr:@std/http


Using `deno add` ensures your lockfile stays in sync. Manually editing imports without updating deno.json works but misses lockfile benefits.

deno add jsr:@std/http


使用`deno add`可确保锁文件保持同步。手动编辑导入而不更新deno.json虽然可行，但会失去锁文件的优势。