介绍 JSR – JavaScript 注册中心

原文:deno.com/blog/jsr_op…

作者:Ryan Dahl、Luca Casonato、Kevin Whinnery 2024年3月1日

介绍 JSR - JavaScript 注册中心


介绍 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.com/runtime/manual)
deno publish

# with npm-like systems
npx jsr publish

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

继续阅读以了解我们为何以及如何构建 JSR,如何今天开始使用它,以及如何参与项目!

介绍 JSR – 稍长版本

JavaScript 已经成为世界上的默认编程语言。在浏览器、移动设备、机器人和服务器上运行,您可以使用 JavaScript 来编程几乎任何东西。

Node 在过去的 15 年中是这种变革的重要组成部分,但是谈到 Node 的成功时,不得不提到同样令人难以置信的 npm 的成功。仅在过去 30 天内,npm 已经有超过 2.5 百万个包的下载量,约 2500 亿次下载,可以说是世界上最成功的包注册表。

如果没有 JavaScript 社区共同建立的这个不可思议的生态系统,JavaScript 可能不会享有今天的地位。对于 npm 上的每个模块作者来说,这应该是一种自豪。

从 2009 年到 2024 年

自 npm 首次发布以来,JavaScript 的世界发生了很多变化。

  • ECMAScript 模块作为编写可重用 JavaScript 代码的 Web 标准已经到来,取代了 CommonJS。
  • TypeScript 不仅成为使用编译时类型检查编写 JavaScript 的一种方式,还成为来自 TC39 的最新 JavaScript 语言特性的测试平台。
  • Node 不再是浏览器之外唯一相关的 JavaScript 运行时。像 Denoworkerd (Cloudflare Workers)Bun 等运行时正在创新 DX,更紧密地遵循 Web 标准,并/或做出设计取舍以在边缘服务器上快速启动。

虽然 npm 仍然是当今 Web 开发的基础组件之一,但它并未考虑到这些新的现实。我们认为现在是时候重新想象 2024 年应该如何工作的包注册表了。

  • 它应该将 ESM 视为 JavaScript 模块的 Web 标准
  • 它应该从第一原则上为 TypeScript 设计
  • 它应该简单、快速,并提供出色的开发人员体验
  • 它应该是免费和开源的,并且在 JavaScript 可以运行的任何地方都可以工作
  • 它应该建立在 npm 的成功基础上,而不是分叉它

为了实现这些设计目标,我们非常兴奋地分享 JSR – JavaScript 注册中心。从今天开始,它在公开测试中免费提供。我们希望您注册并尝试一下!

使用 JSR 的模块

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

介绍 JSR - JavaScript 注册中心

请注意,每个包都有与之相关的 质量分数。分数由越来越多的因素决定,如文档的完整性、用于快速类型检查的最佳类型声明和与多个运行时的兼容性。
介绍 JSR - JavaScript 注册中心

一旦找到了合适的模块,安装和使用说明可以在每个页面的模块自动生成的 API 参考文档的顶部找到。
介绍 JSR - JavaScript 注册中心

让我们在一个 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 运行此应用程序,然后访问 http://localhost:8080 查看您的 “hello, world” oak 应用程序。

发布到 JSR

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

要了解这是如何工作的(并了解 JSR 在幕后为您做了多少工作),让我们创建和发布一个名为 yassify 的 TypeScript 模块,它将一串文本用一些 emoji 💅✨👸 发光。然后,我们将使用该模块的 TypeScript 接口在 Astro 项目中运行它,我们将使用 Node 运行该项目。

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

构建 yassify

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

  • jsr.json – 有关您的包的元数据文件
  • mod.ts – 我们模块的实现(此文件可以是任何名称)
  • README.md – 用作您的模块在 jsr.io 上概述的 Markdown 文件

jsr.json 中,包含有关您的包的以下元数据:

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

此元数据包括:

  • name 属性,将您的包的作用域名称组合在一起
  • 您的包的 version – 使用语义化版本 安装和去重 JSR 包
  • exports 字段,指定 您的包的哪些模块可供消费者使用。

README.md 中,包含一些高级别的使用说明和示例。目前,使用以下内容应该足够:

# yassify

使用 `yassify` 对任何文本字符串应用高级美化过滤器。

## License

MIT

mod.ts 中,包含 yassify 函数的实现:

export function yassify(str: string): string {
  return `${str} 💅✨👑`;
}

创建了您的三个文件后,您可以使用以下命令(或者如果您使用基于 Node 的环境,则使用 npx jsr publish)从命令行发布您的模块:

deno publish

如果这是您第一次发布此模块,您可能会被提示为其创建范围和包名称。
介绍 JSR - JavaScript 注册中心

点击“创建”按钮将会提示进行最后的授权检查:
介绍 JSR - JavaScript 注册中心

在几秒钟内,您的包应该已发布到 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.io/auth?code=x to authorize publishing of @kwhinnery/yassify
Waiting...
Authorization successful. Authenticated as Kevin Whinnery
Publishing @kwhinnery/yassify@1.0.0 ...
Successfully published @kwhinnery/yassify@1.0.0
Visit https://jsr.io/@kwhinnery/yassify@1.0.0 for details

如果您访问您的包页面,如 CLI 输出的最后一行所示,您将注意到您创建的 README 文件正作为您的包的主页。您还会注意到 TypeScript API 文档已自动生成您的包。

介绍 JSR - JavaScript 注册中心

对于您的包导出的函数和符号,从您的源代码和注释生成文档:
介绍 JSR - JavaScript 注册中心

您还可以帮助潜在用户了解哪些运行时支持您的模块,以及在“设置”选项卡中配置您的模块描述,该描述将显示在搜索结果中。

介绍 JSR - JavaScript 注册中心

花时间更新这些内容也会提高您的包的总体质量分数。 yassify 可能做得不多,但文档写得很好!

介绍 JSR - JavaScript 注册中心

这应该是我们作为包发布者现在需要做的所有事情 – 让我们看看作为消费者使用我们的包的体验如何。

在 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 导入上 —— 请注意,编辑器中已经提供了内联文档!
介绍 JSR - JavaScript 注册中心

这是因为 JSR 自动转译了您模块中的 TypeScript 代码,并包含了 .d.ts 文件,该文件使您的编辑器了解您的模块的工作方式。单击 yassify 函数,您将看到您的 Astro 项目的 node_modules 文件夹中的 .d.ts 文件:

介绍 JSR - JavaScript 注册中心

最后,您可以在 Astro 项目中实际使用 yassify 函数!在 Card.astro 文件中,如下所示对组件的 title 属性进行 yassify 处理:

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

如果还没有,请使用以下命令启动您的本地 Astro 开发服务器:

npm start

访问 http://localhost:4321 应该会显示一个新的 Astro 占位页面,其中所有 Card 标题都被适当转换为 yassify。太棒了!

介绍 JSR - JavaScript 注册中心

从 GitHub 发布

虽然从命令行发布东西很好,但您可能想要从 CI 发布您的包。在 JSR 上设置这样做的最简单方法是链接一个 GitHub 存储库。在 JSR 包 Settings UI 中,配置您的包源代码存储的 GitHub 用户名和存储库名称。如果您是 git 和 GitHub 的新手,请在此处了解如何设置 GitHub 存储库

介绍 JSR - JavaScript 注册中心

链接您的存储库后,请将以下配置添加到 .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。

介绍 JSR - JavaScript 注册中心

以这种方式发布还可以让您的用户放心,因为他们包含的工件确实是通过 CI 上传的,并且可以查看透明性记录

介绍 JSR - JavaScript 注册中心

帮助我们提升 JavaScript 生态系统

虽然Deno团队已经为JSR投入了大量工作,但我们希望JSR成为整个JavaScript生态系统的公共工具。这就是为什么我们将JSR免费并且在MIT许可下开源。我们设计JSR为便宜且相对容易托管,任何决定这样做的人都可以轻松实现。

我们还希望将JSR保持为一个社区空间。我们仍在努力解决如何管理项目的细节,但作为第一步,我们希望邀请社区管理员协助Deno团队分配受保护的范围,处理纠纷,并一般指导JSR的日常流量。如果您有兴趣成为JSR社区管理员,请在此处告诉我们。

我们还需要您的反馈——虽然我们相信JSR是非常稳定的软件,但还有很多工作要做,我们期待在未来几周和几个月内从社区中学到很多东西。

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

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

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

原文链接:https://juejin.cn/post/7342403951365095476 作者:纪轻昀

(0)
上一篇 2024年3月5日 上午10:00
下一篇 2024年3月5日 上午10:12

相关推荐

发表评论

登录后才能评论