跳至主要内容
Deno 2 终于来了 🎉️
了解更多
The JSR logo on an abstract square background

JSR 简介 - JavaScript 注册中心

JSR 简介 - 极简版本

查看更详细的版本，了解我们构建 JSR 的方法和原因！

JSR - JavaScript 注册中心 现已进入 公开测试阶段 - 立即注册！JSR 针对 TypeScript 进行了优化，仅支持 ES 模块。它适用于 Deno 和基于 npm 的项目（Node、Bun、Cloudflare Workers 等），并且是 免费开源的。

您可以像这样 安装包

# deno
deno add @luca/flag

# npm (and npm-like systems)
npx jsr add @luca/flag

您可以像使用任何其他 ES 模块一样导入包

import { printProgress } from "@luca/flag";

printProgress();

轻松发布 您自己的 TypeScript 和 JavaScript 模块，直接从命令行进行操作

# with deno installed (https://docs.deno.org.cn/runtime/manual)
deno publish

# with npm-like systems
npx jsr publish

模块以 TypeScript 源代码的形式发布到 JSR。API 文档生成、针对类 Node 环境的类型声明以及转译都由 JSR 处理。模块作者可以专注于编写 TypeScript 代码。

继续阅读，了解我们构建 JSR 的方法和原因，以及如何立即使用它，以及如何参与项目！

JSR 简介 - 更详细的版本

JavaScript 已成为全球默认的编程语言。在浏览器和移动设备、机器人以及服务器上运行，您可以使用 JavaScript 来编写几乎任何程序。

Node 在过去 15 年中推动了这一转型，但谈论 Node 的成功，就不得不提及同样令人难以置信的 npm 的成功。拥有超过 250 万个包，仅过去 30 天就下载了大约 2500 亿次，它可以说是世界上最成功的包注册中心。

如果没有 JavaScript 社区共同构建的这个令人难以置信的生态系统，JavaScript 可能不会享有今天的盛况。对于 npm 上的每个模块作者来说，这都应该成为一种自豪感。

从 2009 年到 2024 年

自 npm 首次发布以来，JavaScript 世界发生了翻天覆地的变化。

  • ECMAScript 模块 已成为编写可重用 JavaScript 代码的 Web 标准，取代了 CommonJS。
  • TypeScript 已成为不仅可以编写带编译时类型检查的 JavaScript，而且还成为 TC39 发布的最新 JavaScript 语言特性的测试平台。
  • Node 不再是浏览器之外唯一相关的 JavaScript 运行时。像 Deno、workerd（Cloudflare Workers）、Bun 和 更多即将推出的运行时 在 DX 上进行创新，更严格地遵守 Web 标准，或者做出设计权衡以在边缘服务器上快速启动。

虽然 npm 今天仍然是 Web 开发的基础部分，但它并非设计用于应对这些新的现实情况。我们认为现在是重新思考包注册中心在 2024 年如何工作的时机。

  • 它应该将 ESM 作为 JavaScript 模块的 Web 标准。
  • 它应该从一开始就为 TypeScript 而设计。
  • 它应该简单、快速，并提供卓越的开发人员体验。
  • 它应该是免费开源的，并且可以在任何使用 JavaScript 的地方使用。
  • 它应该建立在 npm 的成功基础之上，而不是对其进行分叉。

为了实现这些 设计目标，我们非常高兴地宣布推出 JSR - JavaScript 注册中心。从今天起，它将 在公开测试阶段免费提供。我们希望您能注册并试用一下！

使用 JSR 中的模块

在 JSR 主页 上，您可以按名称搜索模块，或根据其包描述进行搜索。下面，我们搜索 HTTP 服务器包，并找到了 oak，它是 deno.land/x 中更受欢迎的 HTTP 中间件框架之一，已发布在 JSR 上。

search results for http server
按名称或描述搜索包

请注意，每个包都关联着一个 质量评分。该评分由不断增加的因素决定，例如文档完整性、用于快速类型检查的最佳类型声明以及与多个运行时的兼容性。

oak quality score
构成质量评分的一些因素

找到合适的模块后，安装和使用说明可以在每个页面顶部的模块自动生成的 API 参考文档中找到。

oak usage instructions
使用 npm 安装和使用 oak 的说明

让我们在 Node.js 项目中使用 npm 来使用 oak。在终端中，初始化一个新的 Node 项目，并使用以下命令安装 oak

npm init --yes
npx jsr i @oak/oak

在同一个目录中，创建一个名为 index.mjs 的文件，并添加以下代码，它使用您最近安装的 oak 模块

import { Application, Router } from "@oak/oak";

const router = new Router();
router.get("/", (ctx) => {
  ctx.response.body = `<!DOCTYPE html>
    <html>
      <head><title>Hello oak!</title><head>
      <body>
        <h1>Hello oak!</h1>
      </body>
    </html>
  `;
});

const app = new Application();
app.use(router.routes());
app.use(router.allowedMethods());

app.listen({ port: 8080 });

您可以使用 node index.mjs 运行此应用程序，然后在 https://127.0.0.1:8080 访问您的“hello, world” oak 应用程序。

发布到 JSR

作为包创建者，JSR 让您的生活变得更加轻松。您可以使用 TypeScript 编写包，并将 TypeScript 源代码直接发布到 JSR，无需构建步骤。

要了解它是如何工作的（以及了解 JSR 在幕后为您完成的工作），让我们 创建和发布 一个名为 yassify 的 TypeScript 模块，它将使用一些表情符号 💅✨👸 将文本字符串美化。然后，我们将在一个 Astro 项目中使用此模块的 TypeScript 接口，并使用 Node 运行该项目。

由于 Deno 本机支持 TypeScript，因此使用 Deno 构建此模块将是最快的。但是，您可以使用任何您喜欢的运行时编写 TypeScript。

构建 yassify 包

在终端中，创建一个名为 yassify 的新文件夹，并在其中创建三个文件

  • jsr.json - 包的元数据文件
  • mod.ts - 模块的实现（此文件可以命名为任何名称）
  • README.md - 一个 Markdown 文件，将在 jsr.io 上用作模块的概述

在 jsr.json 中，包含有关包的以下元数据

{
  "name": "@kwhinnery/yassify",
  "version": "1.0.0",
  "exports": "./mod.ts"
}

此元数据包含

  • name 属性，它结合了 范围 和 包 的名称。
  • 包的 version - JSR 包使用 语义版本控制 进行安装和去重。
  • exports 字段，它 指定 包中的哪些模块可供使用者使用。

在 README.md 中，包含一些关于包的高级使用说明和示例。现在，使用以下内容就足够了

# yassify

Use `yassify` to apply advanced beauty filters to any string of text.

## License

MIT

在 mod.ts 中，包含 yassify 函数的实现

/**
 * Yassify a string of text by appending emoji
 *
 * @param str The string of text to yassify.
 * @returns a string of text with emoji appended
 */
export function yassify(str: string): string {
  return `${str} 💅✨👑`;
}

创建了三个文件后，您可以使用以下命令从命令行发布模块（如果您使用的是基于 Node 的环境，则可以使用 npx jsr publish）

deno publish

如果这是您第一次发布此模块，您可能会被提示为其创建范围和包名称。

create scope and package on jsr
从 CLI 打开一个浏览器，你将看到一个创建范围和包的 UI。

点击“创建”按钮将提示最终的授权检查。

authorize package creation
授权 CLI 为你创建一个包。

几分钟后，你的包应该会发布到 JSR 上！

kevin@kevin-deno yassify % deno publish
Check file:///Users/kevin/dev/kwhinnery/yassify/mod.ts
Checking for slow types in the public API...
Check file:///Users/kevin/dev/kwhinnery/yassify/mod.ts
'@kwhinnery/yassify' doesn't exist yet. Visit xxx to create the package
Waiting...
Package @kwhinnery/yassify created
Visit https://jsr.deno.org.cn/auth?code=x to authorize publishing of @kwhinnery/yassify
Waiting...
Authorization successful. Authenticated as Kevin Whinnery
Publishing @kwhinnery/[email protected] ...
Successfully published @kwhinnery/[email protected]
Visit https://jsr.deno.org.cn/@kwhinnery/[email protected] for details

如果你访问你的包页面（如 CLI 输出的最后一行所示），你会注意到你创建的 README 文件充当包的主页。你还会注意到 TypeScript API 文档已经为你包自动生成。

package home page
yassify 包在 JSR 上的新家

对于包导出的函数和符号，文档会根据你的源代码和注释生成。

package docs
为我们的包自动生成的 API 文档

你也可以在“设置”选项卡下帮助潜在用户了解哪些运行时支持你的模块。你可能还想在这里配置你的模块描述，它将显示在搜索结果中。

package settings
配置支持的运行时和包描述

花时间进行这些更新也会提高你包的整体质量得分。yassify 可能功能不多，但它有很好的文档！

package score
使用支持的运行时和描述来“yassify” yassify 包

作为包发布者，我们现在应该做完所有需要做的事情了 - 让我们看看将我们的包用作消费者是什么样的体验。

在 Astro 项目中使用你的新模块

现在是时候使用 Astro 构建的 Web 应用程序进行“yassify”了。要创建一个使用 Node 的 Astro 项目，请执行以下命令

npm create astro@latest

接受所有默认选项，包括使用 TypeScript 开发的选项。你还可以允许 Astro 安装所有 npm 依赖项。

创建 Astro 项目后，你可以使用以下命令安装刚刚创建的 yassify 模块（根据需要替换你自己的范围名称）

npx jsr add @kwhinnery/yassify

安装完包后，在你的常用编辑器中打开你的 Astro 项目。如果你使用 Visual Studio Code，你会获得一些不错的功能，我会在介绍时指出。

在默认的 Astro 示例代码中，打开 src/components/Card.astro。Astro 组件可以在文件的 组件脚本 部分使用 TypeScript 代码。在文件顶部，添加对 yassify 的导入，如下所示

import { yassify } from "@kwhinnery/yassify";

如果你使用的是 VS Code，将鼠标悬停在 yassify 导入上 - 注意，编辑器中已经提供了内联文档！

inline docs
编辑器中的内联文档，免费！

这是因为 JSR 已经自动将你模块中的 TypeScript 代码转换为 JavaScript，并包含了 .d.ts 文件，这些文件为你的编辑器提供有关你的模块工作方式的提示。在 yassify 函数上执行“命令 + 点击”，你将在 Astro 项目的 node_modules 文件夹中看到 .d.ts 文件。

generated .d.ts file
JSR 为你生成了一个 .d.ts 文件，并将其包含在你的包中。你的 TypeScript 源代码也被转换为 Node 的 JavaScript。

最后，你实际上可以使用 Astro 项目中的 yassify 函数！在 Card.astro 文件中，像所示的那样“yassify”组件的 title 属性

<li class="link-card">
  <a href="{href}">
    <h2>
      {yassify(title)}
      <span>&rarr;</span>
    </h2>
    <p>
      {body}
    </p>
  </a>
</li>

如果你还没有，你应该现在使用以下命令启动你的本地 Astro 开发服务器

npm start

访问 https://127.0.0.1:4321 应该会显示一个新的 Astro 占位符页面，其中所有卡片标题都已正确转换。太棒了！

astro demo page
Astro 已经正式“yassify”了

从 GitHub 发布

虽然从命令行发布对于尝试事物来说非常有用，但你可能想要 从 CI 发布你的包。在 JSR 上设置此操作的最简单方法是链接一个 GitHub 仓库。在 JSR 包的“设置”UI 中，配置你的包源代码存储的 GitHub 用户名和仓库名称。如果你不熟悉 git 和 GitHub，请在此处了解如何设置 GitHub 仓库。

package settings page
为你的包链接一个 GitHub 仓库

链接仓库后，将以下配置添加到 .github/workflows/publish.yml 下的一个文件中

name: Publish

on:
  push:
    branches:
      - main

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write # The OIDC ID token is used for authentication with JSR.
    steps:
      - uses: actions/checkout@v4
      - run: npx jsr publish

将此文件推送到你的 GitHub 仓库后，对 main 分支的进一步提交（当它们包含新版本时）将自动发布到 JSR。

successful GH actions run
成功的 GitHub Actions 发布运行

以这种方式发布还可以让你的用户放心，他们在项目中包含的工件确实是从 CI 上传的，并提供了一个可供查看的 来源透明性日志。

provenance stamp
一个来源戳，指示最后一个上传的构建来自 GitHub Actions

帮助我们提升 JavaScript 生态系统

虽然 Deno 团队在 JSR 上投入了大量工作，但我们希望 JSR 成为整个 JavaScript 生态系统的公共工具。这就是我们使 JSR 在 MIT 许可下免费和开源 的原因。我们设计 JSR 旨在对任何决定这样做的用户来说，都能够廉价且相对容易地托管。

我们还想将 JSR 作为社区空间维护。我们仍在研究如何管理项目，但作为第一步，我们想邀请社区版主来帮助 Deno 团队分配受保护的范围，处理争议，以及总体上指导 JSR 的日常流量。如果你有兴趣成为 JSR 社区版主，请点击此处告知我们。

我们也需要你的反馈 - 虽然我们认为 JSR 是非常稳定的软件，但还有很多工作要做，我们预计将在未来几周和几个月内从社区中学到很多东西。

  • 如果你发现 JSR 存在问题，请将其作为 GitHub 问题 报告。
  • 如果你对 JSR 有反馈，或者需要社区的帮助，请加入我们，在 Discord 上的 #jsr 和 #jsr-feedback 频道中。

最后，请在 X/Twitter 上关注 @jsr_io，以获取 JSR 团队的新闻和更新。

JavaScript 和 Web 平台很可能在未来几年内仍然是主要的编程环境。我们希望 JSR 能推动 JavaScript 社区未来 15 年的创新，并帮助 TypeScript 和 JavaScript 开发人员无论其代码运行在何处，都能提高效率。