Wie du ein Paket auf JSR.io veröffentlichts

Ich bin aktuell ziemlich angetan von Deno und dessen Ökosystem. Seit Version 2 vor einigen Tagen erschienen ist, habe ich mich intensiver mit den verschiedenen Aspekten von Deno beschäftigt. Unter anderem habe ich den Package Manager JSR erkundet, der unabhängig arbeitet und nicht auf Deno selbst angewiesen ist, aber dennoch das gesamte Deno-Ökosystem ergänzt. In diesem kurzen Tutorial möchte ich dir einen Überblick geben, wie einfach es ist, eigene JSR-Pakete zu veröffentlichen.

Projekt erstellen

Um zu starten, initialisiere dein Projekt mit folgendem Befehl:

1deno init orakel-otter // Unser beispiel Projektname

Projekt öffnen

Wechsel in das Projektverzeichnis:

1cd orakel-otter

Aufräumen

Für dieses Tutorial können wir die Datei main_test.ts löschen. Es ist jedoch auch in Ordnung, sie zu behalten. Öffne jetzt die main.ts und entferne den boilerplate Code.

Unsere App erstellen

Ich habe hier ein einfaches Programm, das die aktuellen Bitcoin-Preise von einer API abruft. Mir ist nichts Besseres eingefallen, aber es dient dazu, zu veranschaulichen, wie das Veröffentlichen von JSR-Paketen mit Deno 2 funktioniert. Ich habe es 🦦 Orakel Otter 🔮 genannt, warum auch immer :-)

Hier ist unser Programm, das die aktuellen Bitcoin-Preise von einer API abruft:

1type Response = [string, number][];
2
3async function orakelOtter(currency: string = "ALL"): Promise<Response> {
4  try {
5    const response = await fetch("https://mempool.space/api/v1/prices/");
6    const pricesObj = await response.json();
7    const prices = Object.entries(pricesObj);
8
9    if (currency === "ALL") {
10      return prices as Response;
11    }
12
13    const filteredPrice = prices.filter(
14      (price) => price[0] === currency?.toUpperCase()
15    );
16
17    if (filteredPrice.length > 0) {
18      return [...prices[0], filteredPrice[0]] as Response;
19    } else {
20      throw new Error(`Currency ${currency} not found.`);
21    }
22  } catch (error) {
23    console.error(error);
24    return [];
25  }
26}
27
28const getPrice = await orakelOtter();
29console.log(getPrice);

Führe folgenden Befehl aus, um das Programm zu testen:

1deno task dev

Das Terminal wird um Erlaubnis bitten, auf das Netzwerk zuzugreifen. Bestätige dies mit y:

1Watcher File change detected! Restarting!
2┏ ⚠️  Deno requests net access to "mempool.space:443".
3┠─ Requested by `fetch()` API.
4┠─ Learn more at: https://docs.deno.com/go/--allow-net
5┠─ Run again with --allow-net to bypass this prompt.
6┗ Allow? [y/n/A] (y = yes, allow; n = no, deny; A = allow all net permissions) > y

Sobald der Zugriff gewährt ist, solltest du eine Ausgabe wie diese sehen:

1✅ Granted net access to "mempool.space:443".
2[
3  [ "time", 1728830104 ],
4  [ "USD", 62513 ],
5  [ "EUR", 57121 ],
6  [ "GBP", 47771 ],
7  [ "CAD", 86060 ],
8  [ "CHF", 53563 ],
9  [ "AUD", 92464 ],
10  [ "JPY", 9344100 ]
11]

Projekt zur Veröffentlichung auf JSR.IO vorbereiten

Um das Paket auf JSR.IO zu veröffentlichen, benötigst du ein Konto. Nach dem Einloggen gehst du auf dein Profilbild, wählst „+ Ein Paket veröffentlichen“ und erstellst einen Scope. Zum Beispiel kannst du deine Initialen als Scope verwenden. Danach benennst du dein Paket "orakel-otter" (oder wie auch immer du dein Projekt genannt hast) und klickst auf „Create“.

Codeanpassungen

Vor der Veröffentlichung müssen wir uns noch die main.ts anpassen und eine Dokumentation hinzufügen.

In der main.ts nehmen wir folgende Änderungen vor:

1. Entferne die console.log()-Zeile und die Instanzierung.

1const getPrice = await orakelOtter();
2console.log(getPrice);

2. Füge export zur orakelOtter-Funktion hinzu, damit sie als Modul zugänglich ist.
3. Füge eine Dokumentation zur Funktion hinzu, was optional ist, aber für einen besseren JSR-Score empfohlen wird.

1/**
2 * Fetches the current prices for various currencies from the Mempool.space API.
3 *
4 * @param currency - The currency (USD, EUR, GBP, CAD, CHF, AUD, JPY) to filter the prices for. If not provided, returns all available prices.
5 * @returns An array of tuples, where the first element is the currency code and the second element is the current price.
6 * @throws {Error} If the specified currency is not found in the API response.
7 */
8export async function orakelOtter(currency: string = "ALL"): Promise<Response> {
9  // Funktion bleibt unverändert
10}

4. Aktualisiere die deno.json-Datei mit den erforderlichen Feldern: name, version und exports. Inklusive Lizenz (optional):

1{
2  "name": "@gw/orakel-otter",
3  "version": "0.0.1",
4  "license": "MIT",
5  "exports": "./main.ts"
6}

Der Name muss den Scope und den Paketname beinhalten (@gw/orakel-otter), die Version muss dem SemVer-Format folgen.

Paket veröffentlichen

Die Veröffentlichung kann über die CLI oder GitHub Actions erfolgen. Für dieses Tutorial verwenden wir die CLI.

Führe einen Testlauf durch, um sicherzustellen, dass alles korrekt eingerichtet ist:

1deno publish --dry-run

Wenn der Testlauf erfolgreich ist, veröffentliche nun dein Paket in dem du den Befehl ohne --dry-run ausführst:

1deno publish

Nun wirst du Automatisch zu deinem Default Browser weitergeleitet um dich zu authentifizieren, hier jetzt die bestätigen das alles ok ist und dein Paket wird veröffentlicht! Und das wars auch schon, dein erstes JSR Package wurde veröffentlicht :-)

Fazit

Dieses Tutorial deckt nicht alle Details ab, geht aber auf die wichtigsten Punkte ein, um ein Paket auf JSR.io zu veröffentlichen. Beachte, dass JSR Pakete basierend auf verschiedenen Kriterien bewertet, die zum „JSR-Score“ beitragen. Ziel ist es, eine gute Dokumentation und Best Practices einzuhalten, um eine hohe Punktzahl zu erreichen. Ein gut dokumentiertes Paket kann dir wie in meinem Beispiel eine Bewertung von 94 Punkten einbringen!

Weitere Details findest du in den folgenden Dokumentationen

JSR Documentation

Deno Documentation

Ryan Dahl der gründer von Nodejs und Deno über die neue Version Deno 2:

Nützliche Links:

Project on GitHub

Project on jsr.io