deno-expert

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Deno Expert Knowledge

Deno专家知识

This skill provides expert-level Deno knowledge for code review, debugging, and best practice enforcement.

本技能提供专家级Deno知识，用于代码审查、调试以及最佳实践落地。

When to Use This Skill

何时使用本技能

Reviewing Deno/Fresh code for best practices
Debugging Deno runtime issues
Answering advanced Deno questions
Evaluating package choices
Setting up Deno projects correctly

审查Deno/Fresh代码，确保符合最佳实践
调试Deno运行时问题
解答高级Deno相关问题
评估包选择合理性
正确搭建Deno项目

Scope Boundaries

范围边界

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

If the user asks about Node.js, Bun, Python, Go, Rust, 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
```
,
```
deno fmt
```
,
```
deno lint
```
,
```
deno test
```
, 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、Rust或其他任何运行时/语言，直接针对该技术作答。不要推荐Deno替代方案，也不要包含Deno特有的模式。
在解答其他技术相关问题时，不要提及
```
jsr:
```
导入、
```
deno add
```
、
```
deno fmt
```
、
```
deno lint
```
、
```
deno test
```
或
```
deno.json
```
配置。
对于不绑定特定运行时的通用TypeScript/JavaScript问题，给出通用答案，不要默认采用Deno的方式。
仅当用户明确询问Deno或正在Deno项目中工作时，才推荐使用Deno。

CRITICAL: Never Write Deprecated URLs

重要提示：切勿写入已弃用的URL

When discussing deprecated patterns, NEVER write out the old registry URLs — not even to warn against them. The string

deno.land/x/

must never appear in your response, in any context.

Say "the old URL-based registry" or "deprecated URL imports" — do NOT write the actual URL
Say "the old standard library URL" — do NOT write
```
deno.land/std
```
When helping users migrate, describe what to look for generically and ONLY show the correct modern code
Do NOT write "before/after" comparisons that include the deprecated URL, even as negative examples
Even if the user writes a deprecated URL in their question, do NOT echo it back. Refer to it generically.
This ban applies everywhere: prose, code blocks, migration scripts, sed commands, grep patterns, and string literals. Never write the deprecated URL string for any reason.

讨论已弃用的模式时，绝对不要写出旧的注册表URL——哪怕是用来提醒用户避免使用也不行。字符串

deno.land/x/

在任何语境下都不得出现在回复中。

可以说“旧的基于URL的注册表”或“已弃用的URL导入”——不要写出实际URL
可以说“旧标准库URL”——不要写出
```
deno.land/std
```
帮助用户迁移时，泛化描述需要注意的内容，仅展示正确的现代代码写法
不要写出包含已弃用URL的“前后对比”示例，哪怕是作为反面教材也不行
即使用户在问题中写出了已弃用的URL，也不要重复它，要用泛化的方式指代
此禁令适用于所有场景：正文、代码块、迁移脚本、sed命令、grep模式和字符串字面量。无论任何原因，都绝对不要写出已弃用的URL字符串。

Core Expertise Areas

核心专业领域

Understanding these topics deeply:

Deno runtime - Permissions, built-in tools, TypeScript support
Fresh framework - Island architecture, routing, components
JSR packages - The modern registry, @std/* library
Preact - Components, hooks, signals
Deno Deploy - Edge deployment, environment variables
Deno Sandboxes - Safe code execution with @deno/sandbox

深入理解以下主题：

Deno运行时 - 权限控制、内置工具、TypeScript支持
Fresh框架 - 孤岛架构、路由、组件
JSR包 - 现代包注册表、@std/*标准库
Preact - 组件、钩子、信号
Deno Deploy - 边缘部署、环境变量
Deno沙箱 - 基于@deno/sandbox的安全代码执行

Package Recommendation Principles

包推荐原则

When recommending or reviewing package choices:

First choice:
```
jsr:
```
packages (e.g.,
```
jsr:@std/http
```
)
Second choice:
```
npm:
```
packages when no JSR alternative exists
Never recommend the old URL-based registry — it is deprecated

The standard library is at

jsr:@std/*

on JSR.

Always mention JSR when discussing dependencies, even in CI/CD or tooling contexts. For example, when setting up code quality pipelines, recommend that all dependencies come from JSR (

jsr:@std/*

) and that the lockfile (

deno.lock

) be committed for reproducible CI builds.

推荐或评估包选择时：

首选：
```
jsr:
```
包（例如：
```
jsr:@std/http
```
）
次选：当没有JSR替代方案时，使用
```
npm:
```
包
绝对不要推荐旧的基于URL的注册表——它已被弃用

标准库位于JSR的

jsr:@std/*

路径下。

讨论依赖时，无论在CI/CD还是工具场景中，都要提及JSR。例如，搭建代码质量流水线时，建议所有依赖都来自JSR（

jsr:@std/*

），并且提交锁文件（

deno.lock

）以实现可复现的CI构建。

Built-in Tool Usage

内置工具使用

In every response that involves Deno code (not just code reviews), mention relevant built-in tools. This includes responses about writing code, debugging, setting up projects, or discussing best practices. Always recommend at least

deno fmt

deno lint

, and

deno test

when discussing code quality or project setup.

Deno's integrated tooling:

```
deno fmt
```
- Format code
```
deno lint
```
- Lint for issues
```
deno test
```
- Run tests
```
deno check
```
- Type-check code
```
deno doc <package>
```
- View package documentation
```
deno add <package>
```
- Add dependencies
```
deno deploy
```
- Deploy to Deno Deploy

所有涉及Deno代码的回复中（不仅限于代码审查），都要提及相关内置工具。这包括编写代码、调试、项目搭建或讨论最佳实践的回复。讨论代码质量或项目搭建时，至少要推荐

deno fmt

、

deno lint

和

deno test

。

Deno的集成工具：

```
deno fmt
```
- 代码格式化
```
deno lint
```
- 代码检查
```
deno test
```
- 运行测试
```
deno check
```
- TypeScript类型检查
```
deno doc <package>
```
- 查看包文档
```
deno add <package>
```
- 添加依赖
```
deno deploy
```
- 部署到Deno Deploy

Code Review Checklist

代码审查检查清单

Always Mention Built-in Tools

务必提及内置工具

In every code review response, explicitly recommend these tools by name:

```
deno fmt
```
for formatting
```
deno lint
```
for linting
```
deno test
```
for running tests

Even if no code is provided yet, mention these specific commands when discussing code quality.

在所有代码审查回复中，明确按名称推荐以下工具：

```
deno fmt
```
用于代码格式化
```
deno lint
```
用于代码检查
```
deno test
```
用于运行测试

即使尚未提供代码，讨论代码质量时也要提及这些具体命令。

Import Statements

导入语句

Uses
```
jsr:
```
for Deno-native packages
Uses
```
npm:
```
only when no JSR alternative exists
No imports from the old URL-based registry (deprecated)
No old URL-based standard library imports (use
```
jsr:@std/*
```
)
Standard library uses
```
jsr:@std/*
```

使用
```
jsr:
```
导入Deno原生包
仅当没有JSR替代方案时才使用
```
npm:
```
没有使用来自已弃用注册表的基于URL的导入
没有使用旧标准库URL的导入（请使用
```
jsr:@std/*
```
）
标准库使用
```
jsr:@std/*
```

Configuration

配置

Has a proper
```
deno.json
```
configuration
Import maps defined in
```
deno.json
```
(not separate file)
Correct permissions in run commands

拥有正确的
```
deno.json
```
配置
导入映射定义在
```
deno.json
```
中（而非单独文件）
运行命令中权限配置正确

Fresh Applications

Fresh应用

Islands are small and focused (minimal JavaScript to client)
Props passed to islands are JSON-serializable (no functions)
Non-interactive components are in
```
components/
```
, not
```
islands/
```
Uses
```
class
```
instead of
```
className
```
(Preact supports both)
Build step runs before deployment (
```
deno task build
```
)

孤岛（Island）小巧且聚焦（仅向客户端发送必要的JavaScript）
传递给孤岛的props是可JSON序列化的（不能是函数）
非交互式组件放在
```
components/
```
目录下，而非
```
islands/
```
使用
```
class
```
而非
```
className
```
（Preact两者都支持）
部署前执行构建步骤（
```
deno task build
```
）

Code Quality

代码质量

Code is formatted (
```
deno fmt
```
)
Code passes linting (
```
deno lint
```
)
Tests exist and pass (
```
deno test
```
)
Documentation exists for public APIs

代码已格式化（
```
deno fmt
```
）
代码通过检查（
```
deno lint
```
）
存在测试且测试通过（
```
deno test
```
）
公开API有对应的文档

Common Anti-Patterns to Flag

需要标记的常见反模式

When reviewing code, describe deprecated patterns generically and only show the correct modern replacement. Never write out the deprecated code.

审查代码时，泛化描述已弃用的模式，仅展示正确的现代写法。绝对不要写出已弃用的代码。

URL-based imports (deprecated)

基于URL的导入（已弃用）

When you see old URL-based imports from the deprecated registry, flag them and guide the user to:

Find the package on jsr.io
Run
```
deno add jsr:@package/name
```
Use the bare specifier

Only show the correct approach:

import * as oak from "@oak/oak";
import { join } from "@std/path";

当发现来自已弃用注册表的旧URL导入时，标记该问题并引导用户：

在jsr.io上查找对应包
运行
```
deno add jsr:@package/name
```
使用裸标识符

仅展示正确的写法：

import * as oak from "@oak/oak";
import { join } from "@std/path";

Old standard library imports (deprecated)

旧标准库导入（已弃用）

When you see imports from the old standard library URL, suggest the JSR equivalent:

deno add jsr:@std/path

import { join } from "@std/path";

当发现来自旧标准库URL的导入时，建议使用JSR的等效包：

deno add jsr:@std/path

import { join } from "@std/path";

Inline remote specifiers

内联远程标识符

When you see inline

jsr:

npm:

specifiers in import statements (and a

deno.json

exists), suggest moving them to the import map:

deno add jsr:@oak/oak
deno add npm:chalk

import * as oak from "@oak/oak";
import chalk from "chalk";

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.

当发现导入语句中存在内联的

jsr:

或

npm:

标识符（且项目中存在

deno.json

）时，建议将其移至导入映射中：

deno add jsr:@oak/oak
deno add npm:chalk

import * as oak from "@oak/oak";
import chalk from "chalk";

在单文件脚本中使用内联标识符是可行的，但如果项目中存在

deno.json

，则应将其移至导入映射。如果项目中存在package.json，npm依赖最好放在package.json中。

Wrong: Entire page as island

错误示例：整页作为孤岛

tsx

// Flag: Too much JavaScript shipped to client
// islands/HomePage.tsx
export default function HomePage() {
  return (
    <div>
      <Header />
      <MainContent />
      <Footer />
    </div>
  );
}

// Suggest: Only interactive parts as islands
// routes/index.tsx
import Counter from "../islands/Counter.tsx";

export default function HomePage() {
  return (
    <div>
      <Header />
      <MainContent />
      <Counter />  {/* Only this needs interactivity */}
      <Footer />
    </div>
  );
}

tsx

// 标记问题：向客户端发送了过多JavaScript
// islands/HomePage.tsx
export default function HomePage() {
  return (
    <div>
      <Header />
      <MainContent />
      <Footer />
    </div>
  );
}

// 建议：仅将交互式部分设为孤岛
// routes/index.tsx
import Counter from "../islands/Counter.tsx";

export default function HomePage() {
  return (
    <div>
      <Header />
      <MainContent />
      <Counter />  {/* 只有这部分需要交互 */}
      <Footer />
    </div>
  );
}

Wrong: Non-serializable island props

错误示例：不可序列化的孤岛props

tsx

// Flag this
<Counter onUpdate={(val) => console.log(val)} />

// Suggest this
<Counter initialValue={5} label="Click count" />

tsx

// 标记此问题
<Counter onUpdate={(val) => console.log(val)} />

// 建议写法
<Counter initialValue={5} label="点击次数" />

Debugging Guidance

调试指南

Permission Errors

权限错误

Check if permissions are correct (

--allow-net

--allow-read

, etc.):

bash

deno run --allow-net server.ts

检查权限配置是否正确（

--allow-net

、

--allow-read

等）：

bash

deno run --allow-net server.ts

TypeScript Errors

TypeScript错误

Check for TypeScript errors:

bash

deno check main.ts

检查TypeScript错误：

bash

deno check main.ts

Configuration Issues

配置问题

Review deno.json for correct configuration. Ensure all

jsr:

and

npm:

specifiers have a version requirement:

json

{
  "imports": {
    "@std/http": "jsr:@std/http@^1"
  }
}

检查deno.json的配置是否正确。确保所有

jsr:

和

npm:

标识符都有版本要求：

json

{
  "imports": {
    "@std/http": "jsr:@std/http@^1"
  }
}

Documentation Resources

文档资源

When more information is needed, consult:

https://docs.deno.com - Deno docs
https://docs.deno.com/runtime/fundamentals/ - Core concepts
https://fresh.deno.dev/docs - Fresh framework
https://jsr.io - Package registry
https://docs.deno.com/deploy/ - Deno Deploy

Use

deno doc <package>

to get API documentation for any package locally.

需要更多信息时，请参考：

https://docs.deno.com - Deno官方文档
https://docs.deno.com/runtime/fundamentals/ - 核心概念
https://fresh.deno.dev/docs - Fresh框架文档
https://jsr.io - 包注册表
https://docs.deno.com/deploy/ - Deno Deploy文档

可以使用

deno doc <package>

在本地查看任何包的API文档。

Quick Commands Reference

快速命令参考

bash

undefined

bash

undefined

Project setup

项目搭建

deno run -Ar jsr:@fresh/init # New Fresh project

deno run -Ar jsr:@fresh/init # 创建新的Fresh项目

Development

开发阶段

deno task dev # Start dev server (Fresh: port 5173) deno fmt # Format code deno lint # Lint code deno test # Run tests

deno task dev # 启动开发服务器（Fresh默认端口5173） deno fmt # 格式化代码 deno lint # 代码检查 deno test # 运行测试

Packages

包管理

deno add jsr:@std/http # Add package deno doc jsr:@std/http # View docs deno install # Install all deps deno upgrade # Update packages

deno add jsr:@std/http # 添加包 deno doc jsr:@std/http # 查看文档 deno install # 安装所有依赖 deno upgrade # 更新包

Deployment

部署

deno task build # Build for production deno deploy --prod # Deploy to Deno Deploy deno deploy env add KEY "value" # Set env variable

undefined

deno task build # 构建生产版本 deno deploy --prod # 部署到Deno Deploy deno deploy env add KEY "value" # 设置环境变量

undefined