Home Changelog
Page Index

An Otter Wiki

Blame

a6ede2 Thai Pangsakulyanont 2026-03-01 07:29:55 1 
---
2
name: jsr
3
description: Create and maintain JSR (JavaScript Registry) packages. Use this whenever the user wants to publish a package to JSR, set up a new JSR project, configure exports, write documentation, or troubleshoot JSR publishing.
4
---
5
6
[JSR](https://jsr.io/) is a modern package registry for JavaScript and TypeScript. This skill covers creating, configuring, documenting, and publishing ESR packages with minimal overhead.
7
8
To create a package:
9
10
1. **Write code** in TypeScript as ESM (using `import`/`export`)
11
2. **Create config** - `jsr.json` (or add JSR properties to `deno.json`):
12
```json
13
{
14
"name": "@scope/package-name",
15
"version": "1.0.0",
16
"exports": "./mod.ts"
17
}
18
```
19
3. **Publish** - `npx jsr publish` or `deno publish`
20
21
Key Differences from npm:
22
23
- **ESM-only**: No CommonJS. All modules must use `import`/`export`.
24
- **Direct specifiers in code**: Use `npm:lodash@4` or `jsr:@std/encoding@1` directly in imports without package.json entries.
25
- **TypeScript source preferred**: Publish `.ts` files directly, not compiled `.js` + `.d.ts`. JSR handles compilation and auto-generates docs.
26
- **Auto-generated docs**: JSDoc comments on functions, interfaces, classes become your package documentation. No need for separate docs.
27
28
## Publishing
29
30
```bash
31
# Validate before publishing
32
npx jsr publish --dry-run # Shows files to publish, validates rules, doesn't publish
33
34
# Publish from local machine
35
npx jsr publish # Opens browser for auth, publishes when approved
36
37
# (or use GitHub Actions, see below)
38
```
39
40
### GitHub Actions (OIDC)
41
1. Link repo to package in JSR settings (jsr.io → package → settings → GitHub repo)
42
2. Create `.github/workflows/publish.yml`:
43
```yaml
44
name: Publish
45
on:
46
push:
47
branches: [main]
48
jobs:
49
publish:
50
runs-on: ubuntu-latest
51
permissions:
52
contents: read
53
id-token: write
54
steps:
55
- uses: actions/checkout@v6
56
- run: npx jsr publish
57
```
58
No secrets needed.
59
60
## Configuration (`jsr.json` or `deno.json`)
61
d23b60 Thai Pangsakulyanont 2026-03-01 07:37:58 62
**Minimal:** (preferred for new packages as it is the most simple)
a6ede2 Thai Pangsakulyanont 2026-03-01 07:29:55 63
```json
64
{
65
"name": "@scope/pkg",
66
"version": "1.0.0",
67
"exports": "./mod.ts"
68
}
69
```
70
71
**Equivalent to:**
72
```json
73
{
74
"name": "@scope/pkg",
75
"version": "1.0.0",
76
"exports": {
77
".": "./mod.ts"
78
}
79
}
80
```
81
82
**With file filtering:**
83
```json
84
{
85
"name": "@scope/pkg",
86
"version": "1.0.0",
87
"exports": "./mod.ts",
88
"publish": {
89
"include": ["LICENSE", "README.md", "src/**/*.ts"],
90
"exclude": ["src/**/*.test.ts"]
91
}
92
}
93
```
94
95
**Un-gitignoring files** (e.g., publish `dist/` even if in `.gitignore`):
96
```json
97
{
98
"publish": {
99
"exclude": ["!dist"]
100
}
101
}
102
```
103
104
## Documentation (JSDoc)
105
106
All JSDoc comments in exported symbols generate package docs visible on jsr.io and in editor completions.
107
108
**Module documentation** (top of file):
109
```ts
110
/**
111
* Utilities for searching the database.
112
*
113
* @example
114
* ```ts
115
* import { search } from "@scope/db";
116
* search("query")
117
* ```
118
*
119
* @module
120
*/
121
```
122
123
**Function documentation:**
124
```ts
125
/**
126
* Search the database.
127
* @param query Search string (max 50 chars for performance)
128
* @param limit Number of results. Defaults to 20.
129
* @returns Array of matched items
130
*/
131
export function search(query: string, limit?: number): string[]
132
```
133
134
**Interfaces & Classes:**
135
```ts
136
/** Options for search behavior */
137
export interface SearchOptions {
138
/** Max results to return */
139
limit?: number;
140
/** Skip first N results (pagination) */
141
skip?: number;
142
}
143
144
export class Database {
145
/** The database name */
146
name: string;
147
constructor(name: string) { this.name = name }
148
/** Close the connection */
149
close(): void { }
150
}
151
```
152
153
Use `{@link symbol}` to link between documented symbols.
154
155
## Full Documentation
156
157
- Publishing: https://jsr.io/docs/publishing-packages
158
- Writing docs: https://jsr.io/docs/writing-docs
159
- Package configuration: https://jsr.io/docs/package-configuration (jsr.json file)
160
- JSDoc tags: https://docs.deno.com/runtime/reference/cli/doc/#supported-jsdoc-tags
161
- Why JSR: https://jsr.io/docs/why
162
- Troubleshooting: https://jsr.io/docs/troubleshooting
163
- npm compatibility: https://jsr.io/docs/npm-compatibility
164
- About slow types: https://jsr.io/docs/about-slow-types