Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 37 ยท Deploy and Interop

Publishing Packages to JSR

Share a TypeScript library on JSR, the JavaScript Registry. Prepare deno.json, exports, JSDoc and types, follow semver, run deno publish with dry runs and automate releases from GitHub Actions.

Sooner or later you write code that others (or your other projects) should reuse. In Deno's world the natural home for it is JSR, the JavaScript Registry. JSR is an open registry made for modern JavaScript and TypeScript: it accepts TypeScript source directly, generates documentation from your comments, scores package quality, and serves the package to Deno, Node.js, Bun and browsers.

This lesson walks through preparing a package, checking it, publishing it, and releasing new versions safely. You already know most of the pieces: deno.json, tests and deno doc.

Publishing needs a JSR account and internet access, which this site cannot provide, so commands are read-only. Two runnable stand-ins show the logic that matters: how semver ranges decide which version a user gets, and what a publish pre-check looks at.

What JSR gives you

  • TypeScript-first: you publish .ts files. JSR makes the JavaScript and .d.ts files for consumers.
  • Scopes: every package is @scope/name, for example @std/path or @me/slugify. Scopes are owned by a user or an organization, which prevents name squatting.
  • Immutable versions: a published version cannot be changed or replaced, only yanked.
  • Automatic docs and scoring: JSR builds API docs and gives a score based on documentation, types and metadata.
  • Provenance: publishing from GitHub Actions can attach a signed statement of where the package was built.

Use it in Deno with jsr:@me/slugify@^1, and in Node-based projects with npx jsr add @me/slugify.

Step 1: describe the package

Create a scope and a package on the JSR website, then add three fields to deno.json in the package folder:

JSON
{
  "name": "@me/slugify",
  "version": "0.1.0",
  "exports": "./mod.ts",
  "license": "MIT"
}
  • name is @scope/package.
  • version follows semver: MAJOR.MINOR.PATCH.
  • exports is the public entry point (a string) or a map of subpaths:
JSON
{
  "exports": {
    ".": "./mod.ts",
    "./cli": "./cli.ts",
    "./unicode": "./unicode.ts"
  }
}

Users then import jsr:@me/slugify or jsr:@me/slugify/unicode. Only files you list (and what they import) are public.

Step 2: write for consumers

Write a clear module with explicit types and JSDoc:

TypeScript
// mod.ts

/** Options for {@linkcode slugify}. */
export interface SlugifyOptions {
  /** Separator between words. Defaults to `"-"`. */
  separator?: string;
  /** Maximum length of the result. Defaults to no limit. */
  maxLength?: number;
}

/**
 * Turns a title into a URL-safe slug.
 *
 * @example
 * ```ts
 * import { slugify } from "@me/slugify";
 * import { assertEquals } from "@std/assert";
 *
 * assertEquals(slugify("Hello, Deno World!"), "hello-deno-world");
 * ```
 *
 * @param text The text to convert.
 * @param options Optional settings.
 * @returns The slug.
 */
export function slugify(text: string, options: SlugifyOptions = {}): string {
  const sep = options.separator ?? "-";
  const slug = text
    .normalize("NFKD")
    .replace(/[ฬ€-อฏ]/g, "")
    .toLowerCase()
    .replace(/[^a-z0-9]+/g, sep)
    .replace(new RegExp(`^${sep}+|${sep}+$`, "g"), "");
  return options.maxLength ? slug.slice(0, options.maxLength) : slug;
}

The rule that surprises newcomers is "no slow types". JSR generates type declarations quickly by reading your exported signatures without running the type checker. So every exported function, class member and variable needs an explicit type annotation where the type cannot be read from the syntax:

TypeScript
export const DEFAULT_LIMIT = 10;              // fine: a literal
export function makeId() { return crypto.randomUUID(); }   // slow type: no return type
export function makeId(): string { return crypto.randomUUID(); }  // good

deno lint reports this as no-slow-types and deno publish refuses to publish packages that violate it. Also give every export JSDoc, and add runnable @example blocks, which deno test --doc can execute.

Step 3: check before you ship

Terminal
deno fmt --check
deno lint
deno check mod.ts
deno test --doc
deno doc --lint mod.ts          # missing docs or types in the public API
deno publish --dry-run          # everything except the upload

--dry-run lists which files would be published and reports problems such as slow types, missing license or invalid exports. Add a README.md (shown on the package page) and a LICENSE file, and use publish.include / publish.exclude in deno.json to keep tests and fixtures out of the package.

The pre-check below imitates part of what deno publish --dry-run verifies, so you can see the kind of rules involved.

Node.js A publish pre-check (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Step 4: publish

Terminal
deno publish

The first time, Deno opens a browser page so you can authorize publishing for your scope. The package then appears at https://jsr.io/@me/slugify with docs, a score and a version list. For repeatable releases, automate it from GitHub:

YAML
# .github/workflows/publish.yml
name: publish
on:
  push:
    tags: ["v*"]
jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write          # lets JSR verify the build and sign provenance
    steps:
      - uses: actions/checkout@v4
      - uses: denoland/setup-deno@v2
      - run: deno publish

Link the GitHub repository to the package in the JSR settings, and releases need no passwords or tokens.

Versioning rules

Consumers write ranges such as ^1.2.0; semver tells them what to expect from each number:

Change Bump Example
Bug fix, no API change PATCH 1.2.0 to 1.2.1
New feature, backward compatible MINOR 1.2.1 to 1.3.0
Breaking change MAJOR 1.3.0 to 2.0.0

Before 1.0.0 (0.x), the caret is stricter: ^0.2.0 allows only 0.2.x. Because versions are immutable, a mistake means publishing a new patch and, if needed, yanking the bad one so it is no longer picked by default.

Node.js Which version does ^ pick? (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the exports field in deno.json define for a JSR package?

    exports names the module (or map of subpaths) that make up the public API.
  2. 2. Why does JSR require explicit types on exported functions (no slow types)?

    Explicit signatures let JSR read the public API directly from the syntax.
  3. 3. You published 1.2.0 with a bug. What should you do?

    Published versions are immutable. You release a new version and, if needed, yank the broken one.
  4. 4. Which command checks everything about a publish except uploading it?

    --dry-run runs the same validation as a real publish and lists the files, but sends nothing.

Summary

  • JSR hosts TypeScript-first packages named @scope/name; versions are immutable.
  • deno.json needs name, version and exports (and a license).
  • Annotate exported types explicitly, document every export and add runnable @example blocks.
  • Check with fmt, lint, check, test --doc, doc --lint and publish --dry-run.
  • Publish with deno publish, ideally from GitHub Actions with provenance.
  • Follow semver: patch for fixes, minor for features, major for breaking changes.

Next: Workers, FFI and WebAssembly