deno-project-templates

Deno 项目模板

此技能提供用于创建新 Deno 项目的模板，并采用现代最佳实践。

何时使用此技能

• 从头开始创建新的 Deno 项目
• 为不同类型的应用设置项目结构
• 搭建 Fresh Web 应用、CLI 工具、库或 API 服务的项目脚手架

适用范围

此技能仅适用于用户要求创建 Deno 项目的情况。请遵循以下规则：

• 如果用户要求创建 Node.js、Python、Go、Rust 或其他非 Deno 项目，请直接使用相应技术搭建项目。不要推荐 Deno 模板。
• 仅当用户明确要求创建 Deno 项目，或正在 Deno 环境中工作时，才使用这些模板。
• 提及已弃用的模式时，请进行概括描述。不要写出已弃用的 URL 或导入语法，只展示正确的现代做法。

项目类型

根据要构建的项目选择合适的模板：

类型	用途	关键文件
Fresh Web 应用	使用 Fresh 框架构建全栈 Web 应用	main.ts、routes/、islands/
CLI 工具	命令行应用	main.ts 和参数解析
库	可发布到 JSR 的可复用包	mod.ts、mod_test.ts
API 服务	不含前端的后端 API	main.ts 和 HTTP 处理程序

Fresh Web 应用

对于全栈 Web 应用，请使用 Fresh 初始化程序：

deno run -Ar jsr:@fresh/init my-project
cd my-project

这会创建：

• deno.json - 项目配置和依赖项
• main.ts - 服务入口点
• client.ts - 客户端入口点（CSS 导入）
• vite.config.ts - Vite 构建配置
• routes/ - 页面和 API 路由（基于文件的路由）
• islands/ - 可在客户端运行 JavaScript 的交互式组件
• components/ - 仅在服务端运行的组件（不会发送 JavaScript）
• static/ - 图像、CSS 等静态资源

**开发：**Fresh 使用 Vite。开发服务运行在 http://localhost:5173（而非端口 8000）。

deno task dev

CLI 工具

创建带有参数解析功能的命令行应用。

**模板文件：**请参阅 assets/cli-tool/ 目录。

deno.json

{
  "name": "my-cli",
  "version": "0.1.0",
  "exports": "./main.ts",
  "tasks": {
    "dev": "deno run --allow-all main.ts",
    "compile": "deno compile --allow-all -o my-cli main.ts"
  },
  "imports": {
    "@std/cli": "jsr:@std/cli@^1",
    "@std/fmt": "jsr:@std/fmt@^1"
  }
}

main.ts

import { parseArgs } from "@std/cli/parse-args";
import { bold, green } from "@std/fmt/colors";

const args = parseArgs(Deno.args, {
  boolean: ["help", "version"],
  alias: { h: "help", v: "version" },
});

if (args.help) {
  console.log(`
${bold("my-cli")} - A Deno CLI tool

${bold("USAGE:")}
  my-cli [OPTIONS]

${bold("OPTIONS:")}
  -h, --help     Show this help message
  -v, --version  Show version
`);
  Deno.exit(0);
}

if (args.version) {
  console.log("my-cli v0.1.0");
  Deno.exit(0);
}

console.log(green("Hello from my-cli"));

库

创建可发布到 JSR 的可复用包。

**模板文件：**请参阅 assets/library/ 目录。

deno.json

{
  "name": "@username/my-library",
  "version": "0.1.0",
  "exports": "./mod.ts",
  "tasks": {
    "test": "deno test",
    "check": "deno check mod.ts",
    "publish": "deno publish"
  }
}

mod.ts

/**
 * my-library - A Deno library
 *
 * @module
 */

/**
 * Example function - replace with your library's functionality
 *
 * @param name The name to greet
 * @returns A greeting message
 *
 * @example
 * ```ts
 * import { greet } from "@username/my-library";
 * console.log(greet("World")); // "Hello, World"
 * ```
 */
export function greet(name: string): string {
  return `Hello, ${name}`;
}

mod_test.ts

import { assertEquals } from "jsr:@std/assert";
import { greet } from "./mod.ts";

Deno.test("greet returns correct message", () => {
  assertEquals(greet("World"), "Hello, World");
});

**请记住：**发布前，请将 @username 替换为你的 JSR 用户名。

API 服务

创建不含前端的后端 API。

**模板文件：**请参阅 assets/api-server/ 目录。

deno.json

{
  "tasks": {
    "dev": "deno run --watch --allow-net main.ts",
    "start": "deno run --allow-net main.ts"
  },
  "imports": {
    "@std/http": "jsr:@std/http@^1"
  }
}

main.ts

import { serve } from "@std/http";

const handler = (request: Request): Response => {
  const url = new URL(request.url);

  if (url.pathname === "/") {
    return new Response("Welcome to the API", {
      headers: { "Content-Type": "text/plain" },
    });
  }

  if (url.pathname === "/api/hello") {
    return Response.json({ message: "Hello from Deno" });
  }

  return new Response("Not Found", { status: 404 });
};

console.log("Server running at http://localhost:8000");
serve(handler, { port: 8000 });

设置后的步骤

创建项目文件后：

cd my-project
deno install          # Install dependencies
deno fmt              # Format the code
deno lint             # Check for issues

不同项目类型的开发命令

项目类型	启动开发	构建/编译
Fresh	deno task dev（端口 5173）	deno task build
CLI	deno task dev	deno task compile
库	deno test	不适用
API	deno task dev	不适用

部署

准备好部署时：

• Fresh：deno task build && deno deploy --prod
• CLI：deno task compile（创建独立二进制文件）
• 库：deno publish（发布到 JSR）
• API：deno deploy --prod

最佳实践

• 始终使用 jsr: 导入 Deno 包（基于旧 URL 的导入方式已弃用）
• 定期运行 deno fmt 和 deno lint
• 项目已配置为兼容 Deno Deploy