跳到主要内容
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 可以运行在浏览器和移动设备、机器人和服务器上，您可以使用 JavaScript 对几乎任何事物进行编程。

Node 在过去 15 年中是这一转变的主要组成部分，但谈论 Node 的成功，就不能不提及 npm 同样令人难以置信的成功。npm 拥有超过 250 万个软件包，仅在过去 30 天内就有约 2500 亿次的下载量，可以说是世界上最成功的包注册中心。

如果没有 JavaScript 社区共同构建的这个令人难以置信的生态系统，JavaScript 可能无法享有今天的地位。这应该是 npm 上每位模块作者的骄傲。

从 2009 年到 2024 年

自 npm 最初发布以来，JavaScript 世界发生了很大变化。

  • ECMAScript 模块已作为 Web 标准出现，用于编写可重用的 JavaScript 代码，取代了 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 的说明

让我们在带有 npm 的 Node.js 项目中使用 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
一个用于创建您的作用域和包的 UI 将从 CLI 在浏览器中打开

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

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 文档

您还可以帮助潜在用户了解您的模块在 Settings 选项卡下支持哪些运行时。您可能还想在此处配置模块的描述，该描述将显示在搜索结果中。

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

花时间进行这些更新还将提高您包的整体质量评分。yassify 可能做不了太多事情，但它的文档很完善！

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

作为包发布者，我们现在应该做的就是这些 - 让我们看看作为使用者使用我们的包的体验如何。

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

现在是时候美化使用 Astro 构建的 Web 应用了。要创建一个使用 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 代码，并包含了 .d.ts 文件，这些文件为您的编辑器提供了关于您的模块如何工作的提示。命令点击 yassify 函数，您将看到 Astro 项目的 node_modules 文件夹内的 .d.ts 文件

generated .d.ts file
JSR 为您生成了一个 .d.ts 文件，并包含在您的包中。您的 TypeScript 源代码也被转译为用于 Node 的 JavaScript。

最后，您实际上可以在您的 Astro 项目中使用 yassify 函数！在 Card.astro 文件中，美化组件的 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 占位符页面，其中所有 Card 标题都已得到适当的转换。太棒了！

astro demo page
Astro 已被正式美化

从 GitHub 发布

虽然从命令行发布对于尝试各种操作来说很好，但您可能更希望从 CI 发布您的包。在 JSR 上设置此操作的最简单方法是链接一个 GitHub 仓库。在 JSR 包的 Settings 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 issue
  • 如果您对 JSR 有反馈或需要社区的帮助，请加入我们在 Discord 上的 #jsr 和 #jsr-feedback 频道。

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

JavaScript 和 Web 平台可能会在未来几年内继续保持其主导编程环境的地位。我们希望 JSR 将推动 JavaScript 社区未来 15 年的创新，并帮助 TypeScript 和 JavaScript 开发者无论其代码在何处运行都能更加高效。