DOCSEARCHbyAlgolia
Submit Docs

jsr.io Source Code

repository·main·Indexed 25 days ago

https://github.com/jsr-io/jsr

The source code for jsr.io, a JavaScript registry for publishing and managing JavaScript modules with npm compatibility. The project consists of a Rust-based API for business logic and write operations, a Fresh-based frontend deployed as a Cloudflare Worker, a Cloudflare Worker load balancer, and a PostgreSQL database for metadata storage. It integrates with Cloudflare R2 for artifact storage and Algolia for search indexing.

Tokens
46.5K
Snippets
92
Records
182
Agent score
75%

What's inside jsr

  1. Overview of jsr.io Architecture

    main

    jsr.io is a JavaScript registry composed of four primary components:

    1. API: A Rust-based backend handling all business logic and write operations.
    2. Frontend: A server-rendered web application built with Fresh (Deno + Preact), deployed as a Cloudflare Worker.
    3. Load Balancer: A Cloudflare Worker that acts as the entry point and routes traffic to the appropriate backend.
    4. Database: PostgreSQL used for storing metadata and user data (not for serving registry requests).

    Artifacts such as module source code, generated documentation, and npm compatibility tarballs are stored in Cloudflare R2 (S3-compatible object storage).

  2. Understand JSR core principles and benefits

    main

    JSR is a modern, TypeScript-first, and ESM-only package registry designed to work across all JavaScript runtimes (Node.js, Deno, Bun, Cloudflare Workers, etc.).

    Key features include:

    • Native TypeScript Support: Publish TypeScript source files directly. JSR handles transpilation to JavaScript and distribution of .d.ts files for environments like Node.js that lack native TS support. It also automatically generates reference documentation from your source code.
    • ESM-Only: Built exclusively around the ECMAScript Modules standard.
    • Cross-Runtime Compatibility: Works with runtimes that use node_modules (Node.js, Bun, etc.) and runtimes with native TypeScript support (Deno).
    • npm Interoperability: JSR is a superset of npm; JSR modules can import dependencies from npm, and JSR packages can be used in npm-based projects.
    • Security and Reliability: Uses immutable package uploads, a global CDN for fast delivery, and OIDC-based authentication for CI publishing.

  3. Understand JSR scoring factors

    main

    The JSR score is a quality metric (0-100%) assigned to each package to rank it in search results. The score is computed based on four high-level categories:

    • Documentation: Presence of a README file, module documentation, and documentation for public functions and types.
    • Best practices: Avoiding slow types and publishing with package provenance.
    • Discoverability: Providing a package description to improve searchability.
    • Compatibility: Marking at least one runtime as "compatible" in the "Runtime compatibility" section of the package page. Scoring increases with more compatible runtimes.

    Specific factors and their weights are visible in the "Score" tab on any package's page.

  4. Frontend Component Architecture

    main

    The frontend is a Fresh application using Preact and Tailwind CSS. It utilizes the Islands Architecture, meaning pages are server-rendered by default, and only interactive components ("islands") ship JavaScript to the browser.

    Key Features

    • Server-side rendering: Optimized for fast initial loads and SEO.
    • Search: Global search via Algolia; in-package symbol search runs client-side using Orama.
    • Documentation: Displays HTML docs generated by the API with breadcrumb navigation and symbol search.
    • Deployment: Ships as a Cloudflare Worker. The build process (frontend/build.ts) uses deno bundle to create _fresh/worker.js.

  5. Guidelines for Choosing JSR Scope Names

    main

    JSR organizes packages into scopes (e.g., @deno). When selecting a scope name, follow these guidelines:

    Recommended Scope Types

    • Personal usernames: e.g., @ry
    • Organization names: e.g., @deno
    • Project names: e.g., @fresh or @vite/plugin-node (for packages that are part of a larger project).

    Best Practices

    • Avoid generic names: Names like @ai are considered too generic and are likely to be rejected. If you are unsure if a name is too generic, contact help@jsr.io.
    • No Squatting: Registering names with no intention of use, or to prevent others from using them, is prohibited.
    • No Selling: Registering scope names with the intent to sell them is strictly prohibited and will result in account suspension.
    • Trademark/Copyright: JSR reserves the right to reclaim scope names that violate copyright or trademark laws.

  6. Import JSR packages using the `jsr:` scheme

    main

    In tools with native JSR support (currently only Deno), you can import packages directly using the jsr: scheme. Packages do not need to be explicitly installed; the tool will automatically download and cache them on the first run.

    To import the latest version of a package, use the jsr: prefix followed by the package name. You can also specify version constraints directly in the import specifier.

    // Import the latest version
import { camelCase } from "jsr:@luca/cases";

// Import a specific patch version
import { camelCase } from "jsr:@luca/cases@1.0.0";

// Import the latest version in a major version range
import { camelCase } from "jsr:@luca/cases@1";

// Import the latest version compatible with a specific version (>= 1.2.3 and < 2.0.0)
import { camelCase } from "jsr:@luca/cases@^1.2.3";

// Import the latest version in a minor version range (>= 1.2.3 and < 1.3.0)
import { camelCase } from "jsr:@luca/cases@~1.2.3";

  8. Set up local frontend development

    main

    If you only want to make changes to the frontend, you can run it in development mode while connecting to the production API. This allows you to view the registry at http://jsr.test.

    Prerequisites

    • Clone this repository
    • Install Deno

    Setup

    Run the following command to add the required /etc/hosts entries:

    deno task dev setup frontend

    Running the frontend

    Start the frontend service:

    deno task prod:frontend
    deno task dev setup frontend
deno task prod:frontend

  9. Publish a package to JSR

    main

    To publish your package, run the publish command from the root directory of your package (where jsr.json or deno.json is located). Authentication is handled via your browser.

    Commands by runtime:

    Deno:

    deno publish

    npm:

    npx jsr publish

    yarn:

    yarn dlx jsr publish

    pnpm:

    pnpm dlx jsr publish
    # deno
deno publish
# npm
npx jsr publish
# yarn
yarn dlx jsr publish
# pnpm
pnpm dlx jsr publish

  12. Change, remove, or leave scope membership

    main

    Membership management is handled in the Members tab of the scope:

    • Changing roles: Click the dropdown next to a member and select the new role (admin or member). This takes effect immediately.
    • Removing members: Click the dropdown next to a member and select Remove. The member is removed immediately.
    • Leaving a scope: Click Leave. You will lose all administrative and publishing access immediately.

    Critical Constraints:

    • A scope must always have at least one admin. You cannot demote or remove the last admin without first promoting another member to an admin.
    • If you are the last member of a scope, you cannot leave; you must delete the scope instead.