module author feedback

[panva]

So I gave jsr.io some time to cook since its initial release and now gave it a fair shot. Here's feedback as to the experience I had and some issues I'm seeing.

I come from a place where I will not abandon established registries and distribution means for jsr.io, jsr.io is a complementary distribution for a module.

I've published https://github.com/panva/oauth4webapi -> https://jsr.io/@panva/oauth4webapi

The publishing

I went straight to a GHA workflow. Setting everything up was straight forward and publishing came through on a first try.

In the "How to publish" page on jsr.io I was told that "You will need to run deno publish in your action." but then all the steps told me to use npx jsr publish instead. This confused me. I don't understand the difference between the two and nor do I want to.

Screenshot

The registry

I only have questions here

• Is there a way to deprecate a version to hide it from the UI?
• Is there a way to deprecate a whole module?
• Is there a way to unpublish a version?
• Is there a way to unpublish a whole module? Under what conditions?
• Can I maintain multiple semver major releases at once? If so, will the latest publish be the front page or the latest by semver?

The package Web UI - Score

I don't know if Has docs for most symbols is looking for all symbols or just the exported ones. I assume the latter but a simple wording change would suffice to resolve this.

+ At least 80% of the packages' exported symbols should have [symbol documentation](https://jsr.io/docs/writing-docs#symbol-documentation). Currently 58% of symbols are documented.
- At least 80% of the packages' symbols should have [symbol documentation](https://jsr.io/docs/writing-docs#symbol-documentation). Currently 58% of symbols are documented.

I'd like the score checks to be included in the CLI so that I can check them before publishing.

The package Web UI - docs

The optional and readonly property tags are sorted random, why?

Screenshot

The JSDoc @see and @group tags are not used in the UI at all.

The package Web UI - "Use with"

1. This straight up doesn't work in Node.js (you get the dreaded ERR_PACKAGE_PATH_NOT_EXPORTED error) because the trailing "/" in the import is a subpath export (./) which obviously isn't in the package.json file (. is, ./ isn't). FWIW, another question - how would I even define subpath exports for Node.js users in the jsr.json config file?
2. "mod" - let me choose the string that will be used, I doubt users appreciate pasting multiple module imports and having all of them named "mod".

The package Web UI - README - biggest offender

Absolutely horrible, all relative links on npmjs.org are resolved using the package's homepage (or repository?). On jsr.io relative links lead to a 404 because the files are not in the published package (intentionally), why would i publish example typescript files?. I don't want to maintain two README files so the registry needs to be smart enough to point to the repository for relative links in the README file it renders.

[panva]

The last two points need to be resolved before I add jsr.io as a distribution channel for jose¹²³

Footnotes

1. https://www.npmjs.com/package/jose ↩

2. https://github.com/panva/jose ↩

3. https://deno.land/x/jose ↩

[lucacasonato]

@panva Thank you for the feedback. I have opened a PR to address a couple of the issues you had: #726

On your questions:

Is there a way to deprecate a version to hide it from the UI?

Yes, you can "yank" it from the versions page. https://jsr.io/docs/packages#yanking-versions

Is there a way to deprecate a whole module?

Not yet, but it is on the roadmap. #250

This straight up doesn't work in Node.js .
No, yank it instead.

Is there a way to unpublish a whole module? Under what conditions?

No, see https://jsr.io/docs/immutability. We may consider adding a way to unpublish a module within a couple of hours of release, taking into account download stats. But this feature does not exist yet.

Can I maintain multiple semver major releases at once? If so, will the latest publish be the front page or the latest by semver?

Latest by semver, excluding pre-releases.

I'd like the score checks to be included in the CLI so that I can check them before publishing.

#199

The optional and readonly property tags are sorted random, why?

This looks like a bug. I opened #724.

The JSDoc @see and @group tags are not used in the UI at all.

What would you expect these to do? I am thinking the following:

• @see renders a link at the bottom of the docs saying "See ..." (so this is equivalent to the equivalent markdown in the JSDoc)
• @group shows a "grouping" label with the relevant group in the overview and on the package page.

What are some examples of groups you'd like to show?

This straight up doesn't work in Node.js ...

That is now fixed. It was a bug!

"mod" - let me choose the string that will be used

#725

The package Web UI

Right now we do indeed link all paths to the relevant files on JSR. Always linking them to GitHub does not work for us - users do not have to link a JSR package to GitHub.

We could do a fallback mechanism though: either we link to JSR source if the file exists, or to GitHub if that is specified, or it is a dead link.

However, there is relatively little reason for you not to publish examples and docs to JSR. Consumers using native JSR imports only pull in files that are (transitively) linked to from their code. If you have a package with 1 code file, and 300 examples, then any user of this package in (for example) Deno, would only pull in the 1 code file. The 300 examples never make it onto their machine.

[panva]

@lucacasonato thank you for taking the time to respond and taking care of splitting things up for you internally.

The JSDoc @see and @group tags are not used in the UI at all.

What would you expect these to do? I am thinking the following:

• @see renders a link at the bottom of the docs saying "See ..." (so this is equivalent to the equivalent markdown in the JSDoc)

Yup, like it is done here.

• @group shows a "grouping" label with the relevant group in the overview and on the package page.

What are some examples of groups you'd like to show?

This very page shows how groups are used to transform JSDoc @group into a relatable groups in the API reference index file.

This straight up doesn't work in Node.js ...

That is now fixed. It was a bug!

Cheers.

"mod" - let me choose the string that will be used

#725

Great.

The package Web UI

Right now we do indeed link all paths to the relevant files on JSR. Always linking them to GitHub does not work for us - users do not have to link a JSR package to GitHub.

We could do a fallback mechanism though: either we link to JSR source if the file exists, or to GitHub if that is specified, or it is a dead link.

Thank you, a fallback to github, even if by opt-in in the deno.json conf file would work.

However, there is relatively little reason for you not to publish examples and docs to JSR. Consumers using native JSR imports only pull in files that are (transitively) linked to from their code. If you have a package with 1 code file, and 300 examples, then any user of this package in (for example) Deno, would only pull in the 1 code file. The 300 examples never make it onto their machine.

Except that I will have to maintain the extra fluff to conform to JSRs publishing rules, lint rules, score evaluations etc.