A Local JSR Development Experience Report

[wistrand]

I recently set up a local JSR instance to test publishing and consuming packages with a real application (melker).
I am slightly paranoid, and I thus never want to publish a real version unless I can preview/understand the exact results.

TL;DR It works fine running locally (linux, deno 2.6+), but is a bit tricky.

Below is a summary of the issues encountered and some suggestions for improvement. Sorry if I missed
something already documented or just misread the docs. If so, just ignore those suggestions. Also, thanks,
for the great work on JSR!

Some prerequisites not documented

• Git LFS is required to fetch the binary tools (minio, fake-gcs-server) but isn't listed as a prerequisite. Without it, the binaries are just LFS pointers and fail with Exec format error.
• Port 80 binding requires elevated privileges on Linux. The load balancer hardcodes const PORT = 80 in lb/local.ts with no env override. Workaround: sudo setcap 'cap_net_bind_service=+ep' $(which deno).

Likely bug: docs bucket not created in MinIO

lb/local.ts (lines 59-64) creates the modules, docs, and npm buckets in fake-GCS, and only publishing in MinIO. However, the API (api/src/main.rs:192) creates docs_bucket as an s3::Bucket — meaning it writes documentation to MinIO, not GCS. The docs bucket is never created in the right storage backend, causing all publishes to fail with:

s3 upload error: client error when communicating with S3: 404 Not Found

The fix was quick: add createMinioBucket("docs") alongside createMinioBucket("publishing") in lb/local.ts.

Publishing @std requires multiple manual workarounds

The README suggests publishing deno_std to populate the registry. This is needed for core publishing tasks.
In practice this requires:

1. Making yourself a staff user via psql
2. Assigning the std scope via the admin panel
3. Increasing new_package_per_week_limit from its default of 20 - @std has 42 packages. This can be done through the admin UI once you have access, but requires the staff bootstrapping problem to be solved first.
4. Pre-creating all 42 packages via the API, because the Deno CLI opens a browser prompt for each package that doesn't yet exist on the registry. There's no headless/batch mode for package creation during publish — this is a Deno CLI behavior, but a local seed script on the JSR side could work around it.
5. Copying the root LICENSE file into each package subdirectory. The Deno CLI's workspace publish doesn't inherit the root LICENSE into sub-packages, and deno_std doesn't ship individual LICENSE files per package. This is a Deno CLI limitation, but it's a friction point when following the README's instructions.
6. Clearing stuck publishing_tasks from the database after the docs bucket failure described above.

No way to mirror packages from production

If your application depends on third-party JSR packages (in my case, it was luckily exactly one, @zaubrik/djwt), there's no import/mirror functionality. Each package must be manually:

• Scope created and assigned
• Package entry created via API
• Git repo cloned
• deno.json modified to add JSR config (name, version, exports)
• Imports and or dependencies rewritten if needed
• Published with --no-check if there are type errors with newer Deno versions

This makes testing real-world applications with dependency trees impractical.

Suggestions

Quick wins:

• Add git-lfs to the prerequisites in the README
• Make the LB port configurable via env var (or use a non-privileged port like 8080)
• Fix the docs bucket creation in lb/local.ts - add createMinioBucket("docs") alongside createMinioBucket("publishing")
• Add a deno task bootstrap script that creates a staff user, bumps scope limits, and sets up common scopes
• Add a troubleshooting section to the README

Medium-term improvements:

• Add a seed script that publishes @std end-to-end (handles scope creation, limit bumps, package pre-creation, and publish)

Longer-term ideas:

• jsr mirror @scope/package@version - fetch a published package from production JSR and republish it locally, including transitive dependencies. I realize this could be complex.
• deno task bootstrap - a one-command setup that bootstraps the DB, creates a staff user, publishes @std, and verifies the full stack is working
• Dockerize all services (fake-gcs, minio, LB) instead of relying on checked-in binaries via Git LFS

[crowlKats]

hey, thanks for this report. we currently are actively changing the infrastructure regarding buckets and other parts, which is why minio and fake-gcs-server are currently both being used. i wont update the readme until these infrastructure migrations are complete, as they are not fully concrete yet (and honestly not aware anyone self-hosting JSR yet 😅 ).

in #1309 the running & initial setup of JSR will be easier.
#1265 is a pre-requisite for easier self-hosting. once this lands, mirroring can be implemented, and i will land a full docker-compose file. i also plan to add better management utilities around the instance.
I plan to also add a "bot account" to jsr, which acts similarly to github's ghost account, and would be created with a pre-set password. this is necessary for easier initial editing of limits etc.

See #150 & primarily #203

[wistrand]

thanks for the update and the links! I am happy to test new versions. I have been building docker-based tooling for dev envs for quite some time and recognize the many pitfalls :)