JSR Publishing Audit

Comprehensive audit guide for JSR (JavaScript Registry) compliance and scoring optimization.

Understanding the JSR Score

JSR assigns packages a quality score from 0-100%, displayed with color coding:

• Red: Below 60%
• Orange: 60-90%
• Green: 90%+ (target this)

The score directly influences search ranking. View any package's breakdown at

jsr.io/@scope/package/score

The 9 Scoring Factors

Key insight: Documentation carries the heaviest weight. Comprehensive JSDoc + README +

@module

Audit Checklist

deno.json

name

version

exports

name

@scope/package-name

description

exports

deno publish --dry-run

deno publish --dry-run

module.exports

require()

@module

@param

@returns

@example

Audit Process

Step 1: Check Required Metadata

Read

deno.json

jsr.json

{
  "name": "@scope/package-name",
  "version": "1.0.0",
  "description": "Concise package description under 250 characters",
  "exports": "./mod.ts"
}

Package name rules:

• Must start with

  @scope/

• Lowercase letters, numbers, hyphens only
• 2-40 characters (excluding scope)

Config file choice:

• Deno projects: Use

  deno.json

• Node/Bun/other: Use

  jsr.json

• Never split config between both files

Step 2: Verify Exports

Check all entry points exist:

{
  "exports": {
    ".": "./mod.ts",
    "./utils": "./src/utils/mod.ts"
  }
}

For each entry point, confirm:

• File exists at specified path
• Exports are properly defined
• Type annotations are explicit (no slow types)
• Has

  @module

  JSDoc tag

Step 3: Audit Documentation Quality

Module-level documentation (top of entry points):

/**
 * A module providing string utilities for common transformations.
 *
 * @example
 * ```ts
 * import { camelCase } from "@scope/cases";
 * camelCase("hello world"); // "helloWorld"
 * ```
 *
 * @module
 */

Symbol documentation:

/**
 * Converts a string to camelCase format.
 *
 * @param input - The string to convert
 * @returns The camelCase formatted string
 *
 * @example
 * ```ts
 * camelCase("hello world"); // "helloWorld"
 * camelCase("foo-bar-baz"); // "fooBarBaz"
 * ```
 */
export function camelCase(input: string): string {
  // ...
}

JSDoc tags reference:

• @param name - description

  - Document parameters

• @returns description

  - Document return value

• @example

  - Runnable code examples (use triple backticks)

• @deprecated message

  - Mark deprecated APIs

• @see SymbolName

  - Cross-reference related symbols

• @throws ErrorType

  - Document thrown errors

• {@link SymbolName}

  - Inline links

• {@linkcode SymbolName}

  - Inline links with monospace

Step 4: Run Dry-Run Verification

deno publish --dry-run --allow-dirty

This reveals:

• Slow types: Exports without explicit type annotations
• File list: Everything that would be published
• Metadata errors: Invalid name, version, etc.

Step 5: Audit the File List

Review dry-run output for files that should NOT be published:

Common offenders:

• .claude/

  ,

  .zed/

  ,

  .vscode/

  - IDE settings

• .github/

  ,

  .gitlab/

  - CI/CD configs

• .mise.toml

  ,

  .tool-versions

  - Local tooling

• coverage/

  - Test coverage data

• docs/

  ,

  *.md

  (except LICENSE/README) - Documentation

• deno.lock

  - Lock files

• *.test.ts

  ,

  **/test_utils/**

  - Test files

• sonar-project.properties

  ,

  *.config.js

  - Build configs

• .env

  ,

  *.local.*

  - Local configuration

Step 6: Configure Publish Filtering

Use

include

exclude

{
  "publish": {
    "include": [
      "LICENSE",
      "README.md",
      "deno.json",
      "mod.ts",
      "src/**/*.ts"
    ],
    "exclude": [
      "**/*.test.ts",
      "**/test_utils/**"
    ]
  }
}

Why both?

• include

  whitelists only intended files

• exclude

  filters test files from

  src/**/*.ts

  glob

• exclude

  takes precedence when both match

Step 7: Verify Clean Output

Run dry-run again. Only these should appear:

• LICENSE

• README.md

• deno.json

• Entry point files (

  mod.ts

  , etc.)
• Source code (

  src/**/*.ts

  minus tests)

Fixing Slow Types

Slow types are exports without explicit type annotations. They prevent JSR from generating

.d.ts

Function Return Types

// SLOW - inferred return type
export function greet(name: string) {
  return "Hello, " + name + "!";
}

// FIXED - explicit return type
export function greet(name: string): string {
  return "Hello, " + name + "!";
}

Constants

// SLOW - inferred type
export const GLOBAL_ID = crypto.randomUUID();

// FIXED - explicit annotation
export const GLOBAL_ID: string = crypto.randomUUID();

Class Properties

// SLOW - inferred property type
export class Config {
  timeout = 5000;
}

// FIXED - explicit property type
export class Config {
  timeout: number = 5000;
}

Detection Commands

# Catch slow types before publishing
deno publish --dry-run

# Validate documentation generation
deno doc --lint

Note: TypeScript 5.5's

isolatedDeclarations

Prohibited Patterns

JSR enforces ESM-only architecture:

require()

import

module.exports

export

declare global

declare module

jsr:

npm:

node:

Multiple Entry Points

For packages with multiple exports:

{
  "exports": {
    ".": "./mod.ts",
    "./providers": "./providers.ts",
    "./utils": "./src/utils/mod.ts"
  }
}

Users import as:

import { main } from "@scope/pkg";
import { OpenAI } from "@scope/pkg/providers";
import { helper } from "@scope/pkg/utils";

Each entry point should have its own

@module

Dependencies

Declare in

imports

{
  "imports": {
    "@std/assert": "jsr:@std/assert@^1.0.0",
    "zod": "npm:zod@^3.22.0"
  }
}

Supported specifiers:

• jsr:@scope/pkg@version

  - JSR packages

• npm:package@version

  - npm packages

• node:module

  - Node.js built-ins

CI Publishing with Provenance

GitHub Actions OIDC enables tokenless publishing with automatic SLSA provenance:

name: Publish to JSR
on:
  push:
    tags: ['v*']

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write  # Required for OIDC and provenance

    steps:
      - uses: actions/checkout@v5
      - uses: denoland/setup-deno@v2
        with:
          deno-version: v2.x
      - run: deno publish

Requirements for provenance:

1. Link package to GitHub repo in JSR settings
2. Include

   id-token: write

   permission
3. Provenance generated automatically

No API tokens needed - JSR uses GitHub OIDC authentication.

Audit Report Template

After completing the audit:

## JSR Publishing Audit Results

| Check | Status |
|-------|--------|
| Required metadata | ✓ / ✗ |
| Scoped package name | ✓ / ✗ |
| Package description | ✓ / ✗ |
| Valid exports | ✓ / ✗ |
| No slow types | ✓ / ✗ |
| Clean file list | ✓ / ✗ |
| ESM only | ✓ / ✗ |
| Module documentation | ✓ / ✗ |
| Symbol documentation | ✓ / ✗ |

### Estimated Score Impact
- Documentation: X/4 factors
- Best Practices: X/2 factors
- Discoverability: X/1 factors
- Compatibility: X/2 factors

### Files Published
[List from dry-run]

### Issues Found
[List any problems]

### Recommendations
[Suggested fixes prioritized by score impact]

Quick Commands

# Full audit dry-run
deno publish --dry-run --allow-dirty

# Validate documentation
deno doc --lint

# Type check
deno check **/*.ts

# Lint
deno lint

# Format
deno fmt

# Publish (when ready)
deno publish

Known Limitations (2024-2025)

• Private packages: Not yet available (most requested feature)
• JSX publishing: Not supported
• HTTP imports: Prohibited
• Complex inference: Libraries like Zod/ArkType may require

  --allow-slow-types