자바스크립트 레지스트리 JSR을 소개합니다

by Philip21at 2024년 4월 7일

원본 출처: https://deno.com/blog/jsr_open_beta

JSR을 소개합니다 - 매우 짧은 버전

우리가 왜 JSR을 만들게 되었는지에 대한 자세한 글은 아래에서 확인해주세요.

JSR(the Javascript Registry)은 현재 베타 버전으로 공개되어 있습니다. 지금 가입 하세요! JSR은 타입스크립트에 최적화 되어있고, ES Module만을 지원하며, Deno 뿐만 아니라 npm 기반의 프로젝트들 (Node, Bun, Cloudflare, Workers... 등등)과도 호환됩니다. 그리고 무료이며 오픈소스로 공개되어 있습니다.

여러분은 아래와 같은 방법으로 JSR 패키지를 설치할 수 있어요.

# deno
deno add @luca/flag

# npm (또는 npm과 같은 시스템)
npx jsr add @luca/flag

여러분은 다른 ES Module과 동일하게 패키지를 import 할 수 있어요.

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

printProgress();

또한 타입스크립트나 자바스크립트 모듈을 아래 명령어로 쉽게 배포 할 수도 있습니다.

# 설치된 deno로 배포하기 (https://docs.deno.com/runtime/manual)
deno publish

# npm과 같은 시스템으로 배포하기
npx jsr publish

모듈은 타입스크립트 소스코드 형태로 JSR에 배포됩니다. API 문서 생성, Node와 같은 환경을 위한 타입 선언, 트랜스파일 모두 JSR에서 처리해줍니다. 모듈을 만드는 개발자는 타입스크립트 코드를 작성하는 것에만 집중할 수 있습니다.

우리가 JSR을 구축한 방법과 이유, 여러분이 JSR을 사용하는 방법, 그리고 JSR 프로젝트에 어떻게 참여할수 있는지에 대해 궁금하시다면 아래의 자세한 내용을 더 읽어보세요!

JSR을 소개합니다 - 약간 더 긴 버전

자바스크립트는 전세계에서 가장 보편적인 프로그래밍 언어가 되었습니다. 브라우저나 모바일 기기, 로봇, 그리고 서버까지 그 위에서 자바스크립트를 실행하여 거의 모든 것을 프로그래밍 할 수 있습니다.

Node는 지난 15년 동안 이런 변화의 주역이었지만, npm의 놀라운 성공을 함께 언급하지 않고서는 Node의 성공을 이야기 할 수 없습니다. 지난 30일 동안에만 250만개가 넘는 패키지가 등록되고 함께 2,500억 건의 다운로드 횟수를 달성하면서 npm은 틀림없이 전 세계에서 가장 성공적인 패키지 레지스트리로 자리매김했습니다.

자바스크립트 커뮤니티가 함께 구축한 이 엄청난 생태계가 아니었다면 자바스크립트는 오늘날과 같은 위치를 누리지 못했을지도 모릅니다. npm에 모듈을 작성한 개발자들은 모두 충분히 자부심을 가져도 됩니다.

2009년부터 2024년까지

npm이 출시된 이래로 자바스크립트 세계는 정말 많은 변화가 있었습니다.

ECMA스크립트 모듈은 재사용 가능한 자바스크립트 코드를 위해 CommonJS를 대체하는 웹 표준으로 출시 되었습니다.
타입스크립트는 컴파일 타임에 타입 체크를 해서 자바스크립트로 작성할 수 있는 하나의 방법으로 등장했고, 그뿐 아니라 TC39에 소개된 최신 자바스크립트 언어 기능들의 테스트베드로도 사용 되었습니다.
Node는 더 이상 브라우저 밖에서 동작하는 유일한 자바스크립트 런타임 환경이 아닙니다. Deno, workered(Cloudflare Workers), Bun, 그리고 더 많은 런타임 환경들이 DX에서 혁신을 이루고, 웹 표준을 더 면밀하게 준수하며, 엣지 서버에서 빠르게 시작하기 위한 디자인 절충안을 만들고 있습니다.

반면 npm은 오늘날의 웹 개발의 기본적인 구성 요소로 남아있지만, 이런 새로운 현실을 염두에 두고 설계되지 않았습니다. 우리는 2024년이 이 패키지 레지스트리가 어떻게 동작해야 하는지 재구상 해야할 때 라고 생각합니다.

자바스크립트 모듈의 웹 표준으로 ESM을 수용해야 합니다.
타입스크립트의 기본 원리에 충실하게 설계되어야 합니다.
간단하고, 빠르고, 뛰어난 개발자 경험을 제공해야 합니다.
무료 오픈소스여야하고 자바스크립트가 동작하는 곳이면 어디서나 동작해야 합니다.
fork가 아닌, npm의 성공을 기반으로 만들어야 합니다.

이러한 설계 목표를 추구하기 위해, 자바스크립트 레지스트리 JSR을 공유하게 되어 매우 기쁩니다. 오늘부터 공개 베타 버전에 무료로 접근하실 수 있습니다. 가입하셔서 사용해 보시기 바랍니다!

JSR 모듈 사용하기

JSR 홈페이지에서 여러분들은 이름으로 모듈을 찾고, 패키지 설명을 기반으로 검색할 수 있습니다. 아래 이미지를 보면 'http server' 검색어를 입력하여, 이미 JSR에 게시되어 있는 deno.land/x의 인기 있는 HTTP 미들웨어 중 하나인 oak를 찾은 것을 확인할 수 있습니다.

이름이나 설명으로 패키지 검색

각각의 패키지에는 패키지에 대한 품질 점수가 있습니다. 점수는 문서의 완성도, 빠른 타입 검사를 위한 최적의 타입 선언, 다양한 런타임 환경과의 호환성 등 여러 요인들을 고려하여 산정됩니다.

품질 평가점수에 사용되는 몇가지 요인들

적합한 모듈을 찾았다면, 모듈의 자동 생성된 API 참조문서의 모든 페이지 상단에서 설치 및 사용 지침을 확인할 수 있습니다.

npm을 사용한 oak의 설치 와 사용 가이드

이제 한번 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 = `
  <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은 여러분의 삶을 꽤 편하게 만들어줄 것입니다. 여러분은 타입스크립트로 패키지를 작성하고 빌드 단계 없이 타입스크립트 소스코드를 바로 JSR로 배포할 수 있습니다.

이것이 어떻게 작동하는지(그리고 JSR은 뒤에서 얼마나 많은 일들을 하는지) 확인해보기 위해서, 한번 yassify라는 타입스크립트 모듈(텍스트 문자열에 💅✨👸 이모지를 붙여줌)을 만들고 배포 해보겠습니다. 그리고나서 Astro 프로젝트에서 yassify 모듈에 대한 타입스크립트 인터페이스를 사용하고 Node를 통해 실행할 것입니다.

Deno는 타입스크립트를 기본으로 지원하고 있기 때문에, Deno를 사용해서 이 모듈을 빌드하는 것이 가장 빠릅니다. 원한다면 다른 런타임을 사용해서 타입스크립트를 작성할 수도 있습니다.

`yassify` 패키지 빌드하기

터미널에서 yassify라는 폴더를 만들고 안에 3가지 파일을 만듭니다.

jsr.json - 패키지의 메타정보를 담은 파일
mod.ts - 모듈의 구현체 (이 파일은 어떤 것에도 호출될 수 있음)
README.md - 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는 텍스트 문자열에 이모지를 붙여줍니다.
 * 
 * @param str yassify 할 텍스트 문자열
 * @returns 이모지가 붙은 텍스트 문자열
*/
export function yassify(str: string): string {
  return `${str} 💅✨👸`;
}

위에서 생성한 3개의 파일이 있으면, 여러분은 모듈을 아래 명령어로 배포하실 수 있습니다. (Node 기반의 환경을 사용 중이시라면 npx jsr publish도 사용 가능합니다.)

deno publish

만약 이 모듈에 대한 첫 배포였다면, 여러분은 패키지 스코프와 패키지 이름을 생성하라는 메세지를 마주할 것입니다.

CLI에서 열린 패키지 생성 브라우저 UI

"Create" 버튼을 클릭하면 권한 확인을 위한 최종 메세지가 표시됩니다.

패키지를 생성하기 위해 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.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 파일이 패키지의 홈 화면 역할을 하고 있는 것을 볼 수 있습니다. 그리고 타입스크립트 API 문서도 자동으로 생성된 것을 확인하실 수 있습니다.

yassify 패키지의 새로운 JSR 홈 화면

패키지에서 export 한 함수나 심볼은 여러분이 작성한 소스코드와 주석을 기반으로 문서가 생성됩니다.

패키지에 대해 자동 생성된 API 문서

여러분의 패키지가 어떤 런타임 환경에서 사용할 수 있는지, 사용자의 이해를 돕도록 Settings 탭에서 설정할 수 있습니다. 검색결과에 보여질 모듈에 대한 설명을 여기서 설정하실 수 있습니다.

패키지 설명과 런타임 지원 구성

이런 업데이트를 하는데 시간을 투자하면 패키지의 전반적인 품질점수를 높일 수 있습니다. yassify는 많이 무언가를 하지 않았지만, 잘 문서화되어 있습니다!

지원 런타임 환경, 설명과 함께 yassify 패키지를 Yassify 하기

패키지 배포자로서 해야할 일은 지금 이게 전부입니다. 이제 패키지의 사용자로서 경험을 한번 살펴보겠습니다.

Astro 프로젝트에서 새로운 모듈 사용하기

이제 Astro를 사용해 빌드된 웹앱을 yassify할 시간이 되었습니다. Node를 사용하는 아래 명령어를 실행하여 Astro 프로젝트를 만들어보겠습니다.

npm create astro@latest

타입스크립트로 개발하기 위한 옵션을 포함한 모든 기본 옵션을 수락합니다. Astro가 모든 npm 종속성을 설치하도록 허용할 수도 있습니다.

일단 Astro 프로젝트가 생성되면, 아래 명령어로 방금 만든 yassify 모듈을 설치할 수 있습니다. (필요하다면 여러분의 스코프로 사용하세요)

npx jsr add @kwhinnery/yassify

패키지가 설치되면, 우리의 에디터로 Astro 프로젝트를 엽니다. 만약 Visual Studio Code를 사용 중이시라면, 앞으로 보여드릴 몇가지 멋진 기능을 사용하실 수 있습니다.

Astro 기본 예제코드에서 src/components/Card.astro를 열어봅니다. Astro 컴포넌트들은 컴포넌트 스크립트 영역에서 타입스크립트 코드를 사용할 수 있습니다. 최상단에서 yassify를 아래처럼 import 해줍시다.

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

만약 VS Code를 사용 중이면, yassify import 구문에 마우스를 올려보세요 - 에디터에서 인라인 문서를 이용 가능함을 알 수 있습니다.

에디터에서 인라인 문서를 무료로 사용하세요!

이게 가능한 이유는 JSR이 모듈의 타입스크립트 코드를 자동으로 트랜스파일 하고, 에디터에게 모듈이 어떻게 동작하는지 힌트를 줄 수 있도록 .d.ts 파일을 포함했기 때문입니다. yassify 함수를 Command+클릭 하면, Astro 프로젝트의 node_modules 폴더 안에 있는 .d.ts 파일을 확인하실 수 있습니다.

.d.ts 파일이 JSR에 의해 생성되고 패키지에 포함되었습니다. 타입스크립트 소스코드도 Node.js용 자바스크립트로 변환됩니다

마침내, 우리는 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 화면을 마주하실 수 있을 것입니다. 엄청나네요!

Astro가 yassify 되어 보여집니다

GitHub로부터 배포하기

CLI를 이용해서 배포하는 것도 훌륭하고 시험해 보기도 좋지만, 여러분은 아마도 CI 환경에서 패키지를 배포하고 싶으실 것입니다. JSR에서 이렇게 배포 하기 가장 쉬운 방법은 GitHub 저장소를 연결하는 방법입니다. JSR 패키지 Settings UI에서 패키지 소스코드가 있는 Github 사용자 이름과 저장소 이름을 설정하세요. 만약 Git이나 Github을 처음 사용하신다면, 여기서 GitHub 저장소를 설정하는 법을 배워보세요.

패키지에 대한 GitHub 저장소를 연결하기

여러분의 저장소를 연결한 후, .github/workflows/publish.yml에 다음과 같은 설정을 추가해 주세요.

name: Publish

on:
push:
  branches:
    - main

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write # JSR 인증에 사용되는 OIDC ID 토큰
    steps:
      - uses: actions/checkout@v4
      - run: npx jsr publish

이 파일을 GitHub 저장소에 push 한 후, main 브랜치에 대한 추가 커밋이(새로운 버전을 포함할 때)이 자동으로 JSR에 배포될 것입니다.

성공적인 GitHub Actions의 배포 실행

이런 방식으로 배포를 하게되면, 사용자들이 프로젝트에 포함시킨 결과물이 CI로 업로드 되었다는 로그를 투명하게 볼 수 있고, 사용자들을 안심시킬 수 있습니다.

마지막 업로드 된 빌드에 대한 출처가 GitHub Actions를 가리키고 있습니다

자바스크립트 생태계의 수준을 높이기 위해 도와주세요

지금까지는 Deno 팀이 JSR을 위해 많은 기여를 했습니다. 하지만 우리는 JSR이 전체 자바스크립트 생태계의 이익을 위한 공공의 유용한 도구가 되기를 원합니다. 그것이 우리가 JSR을 MIT 라이선스를 가진 무료 오픈소스로 만든 이유입니다. 우리는 JSR을 호스팅 하려는 모든 사람들을 위해서 저렴하고 상대적으로 쉽게 호스팅할 수 있도록 설계했습니다.

또한, 우리는 JSR이 커뮤니티 공간으로서 유지되기를 바랍니다. JSR 프로젝트를 운영하는 방법에 대해서는 아직 연구하고 있지만, 먼저 Deno 팀을 도울 커뮤니티 운영자를 초대하고 싶습니다. 운영자님을 통해 보호 범위를 할당하고, 분쟁을 조절하고, 일상적인 작업을 지시하는 일들에 대해 도움 받고 싶습니다. 만약 JSR 커뮤니티 운영자가 되는 것에 관심이 있으시다면, 여기로 알려주세요.

그리고 우리는 피드백이 필요합니다 - JSR이 매우 안정적인 소프트웨어라고 믿지만, 아직 해야 할 일들이 많이 남아있으며, 앞으로 몇주 몇달 동안 커뮤니티로부터 많은 것들을 배울 수 있을 거라 기대합니다.

만약 JSR에서 문제를 발견한다면, GitHub 이슈로 보고해주세요.
만약 JSR에 대한 피드백이 있거나 커뮤니티에 도움을 주고 싶으시다면, Discord 채널에서 #jsr 그리고 #jsr-feedback 채널에 입장해주세요.

마지막으로, X/트위터에서 @jsr_io를 팔로우하여 JSR 팀의 뉴스와 업데이트 내용을 확인하세요.

자바스크립트와 웹 플랫폼은 앞으로도 몇 년 동안 지배적인 프로그래밍 환경으로 남아있을 것입니다. JSR이 자바스크립트 커뮤니티의 향후 15년간의 혁신을 촉진하고, 코드가 어디에서 실행되든 타입스크립트 및 자바스크립트 개발자들의 생산성을 높이는 데 도움이 되기를 바랍니다.