General

JSR - The cross-platform package manager for ESM

Published Apr 12, 2024

Updated Apr 12, 2024

6 min read

JSR - The cross-platform package manager for ESM

Move over NPM, there’s a new package manager in town. JSR is a new open-source package registry for JavaScript and TypeScript. This particular release has caught my attention, and I’m excited to explore if and where JSR fits into our overflowing ecosystem.

Setting the stage

The JSR website has a page called Why JSR? I want to explore the why a little bit further. I think that the why points to JSR potentially being the future of the JavaScript ecosystem.

NPM and JavaScript modules

If you’ve found yourself confused about publishing and consuming packages and modules in the modern ESM era, you’re not alone. When NodeJS was created, there was no standard for JS modules. Node introduced CommonJS modules, and NPM provided a way to publish and consume these modules in our applications. It’s been years now since ES Modules became a standard and we are still in a weird module purgatory with no clear end in sight. JSR represents a fresh start, free from the baggage of the Node and NPM ecosystems.

JavaScript runtimes and interoperability

New JavaScript runtimes are popping up every year. WinterCG (Web-interoperable Runtimes Community Group) was started to improve interoperability for the various runtimes with some standard APIs. Node has made steps towards this goal, but it might never get all the way there and NPM is coupled pretty tightly to that ecosystem. JSR supports several runtimes (depending on the package). This is a huge opportunity for it to become the package manager for the ecosystem at large. See cross-runtime support section for more details.

NPM Compatibility

JSR doesn’t end up being a complete departure from NPM since it includes an NPM compatibility layer. The docs highlight some limitations and provide deeper technical details on how this piece works. The simple overview is that you can install and use packages from JSR to a Node/NPM based project. The packages will get added to your package.json and node_modules directory. About the same as any package installed from NPM.

JSR Overview

At a high level, JSR is very similar to NPM. You can search for packages on the website. You can publish packages to their registry, and you can download packages from it as well. We touched on the two major features that set it apart from NPM: It only supports ESModules, and it has cross-runtime support. In the rest of the article we’ll explore the essentials (package management) and also some other really great features that feel like are bringing the JS package management ecosystem up to speed with our modern workflows.

Native TypeScript

I have to say I’m not surprised by this feature, considering JSR was developed by the same people behind Deno (a runtime that supports TS natively). It’s a great feature. If you haven’t figured it out yet TypeScript is a big deal and doesn’t seem to be fading away anytime soon. So what exactly does TS support look like in a package manager, though? If your runtime supports TypeScript natively (like Deno) - it can consume the TS files in your package directly. For environments that don’t, it will automatically compile your code to JavaScript and package it with type declaration files (.d.ts). Pretty, stinking, cool. The docs include a page called “about slow types”. It is probably worth a read on its own ,but the TLDR is that JSR will analyze your TS code and penalize you in certain ways if you have some type code that it considers to be slow. On the page, it outlines exactly what these penalties are, as well as what it considers slow types to be. Slow types will also come into play when we get into package scoring later in the article.

Packages

The docs have a page dedicated to packages. It covers some important stuff like deleting packages, versioning, documentation, and publishing. We’ll touch on some of it with an emphasis on the things that are done differently or better than with NPM.

`jsr.json` file

jsr.json is a configuration file that specifies a name, version, and exports of a package. It doesn’t include a list of dependencies like you would have in a package.json file. This is a configuration file for a package to be published to JSR. JSR dependencies are defined in an import map file or a package.json file, depending on the runtime.

Adding packages to a project

Adding packages to your project will vary depending on your target runtime. Here’s an example of installing it for Deno and NPM using various package managers. For Deno, an import map entry is created. For NPM, it gets installed as an NPM package using the JSR NPM compatibility layer.

# deno
deno add @luca/cases

# npm (one of the below, depending on your package manager)
npx jsr add @luca/cases
yarn dlx jsr add @luca/cases
pnpm dlx jsr add @luca/cases
bunx jsr add @luca/cases

If the runtime has native JSR support, you don’t need to explicitly install packages. You can important them using the jsr: scheme.

// Import a specific patch version
import { camelCase } from "jsr:@luca/cases@1.0.0";

// Import the latest version in a major version range
import { camelCase } from "jsr:@luca/cases@1";

// Import the latest version compatible with a specific version (>= 1.2.3 and < 2.0.0)
import { camelCase } from "jsr:@luca/cases@^1.2.3";

As you can see semantic versioning is supported and works similarly to NPM.

Publishing packages

If you want to publish a package to JSR, there are many important rules you need to be aware of. I recommend reading “Publishing packages” before moving forward with this. The main things to note are: ESModules only, npm packages are supported, JSR packages are supported, and node APIs are supported. So there aren’t many constraints. You just need to understand how exactly to do these things. IE: how do I use NPM dependencies, how do the imports work, etc? Once you’ve got all that down, you will be ready to publish your first package to JSR 😃

Documentation

JSR emphasizes quality package documentation. It’s one of the factors in their package scoring algorithm, which we will discuss shortly. The important parts of a package’s documentation include:

a README.md file
symbol documentation - functions, interfaces, classes, etc
module documentation - docs for each exported module in a package The symbol and module documentation are written using JSDoc. The JSR website generates some nice documentation based on these 3 pieces on your package page. This means you can understand a package's entire public API without ever leaving jsr.io.

Browser support

The cross-runtime support is amazing, but I was curious where the original JavaScript runtime fit (the browser). According to the documentation: “You can use JSR with any tool that supports ES modules, and either has native support for JSR or supports npm packages using node_modules.” Since modern web browsers support ES modules, I will count this as JSR support. From what I can tell, though, there is one caveat. To include a module on a web page, we need a URL to download it from. Can we publish our package to JSR and use it to load a module via a script tag? According to the JSR usage policy, no. The “Unacceptable use” section states: “It is not acceptable to use JSR as a CDN for serving assets directly to web applications in a browser, except for development purposes.” So, it seems that this is a no-go for now. We will probably need to wait a bit for CDN services like jsdelivr to pull packages from the JSR registry, similar to what they do with NPM currently.

Other notable features

We’ve covered the most important bits about package management, TS support, NPM compatibility, etc. But there are still a few unique features that add an extra bit of sparkle to JSR.

Scoring

We mentioned earlier that documentation plays a part in a scoring algorithm. JSR analyzes all of the packages published to its registry and assigns them a score based on certain criteria: documentation, best practices, discoverability, and compatibility. This score is shown with every package listed on the website. You can also add a shiny badge to your README if you’re particularly proud of something. It’s still early on, so it’s likely this will evolve as time goes on. It’s an interesting gimmick, at the very least!

Summary

I am excited to have a new cross-platform compatible package manager that only supports ESM. As useful as NPM has been all these years, it carries a lot of baggage from “the olden days”. JSR’s native TypeScript support and reliance on modern standards is a breath of fresh air. It feels like I can publish a simple package without much ceremony. I’m excited to release my first package to JSR soon :)

This Dot is a consultancy dedicated to guiding companies through their modernization and digital transformation journeys. Specializing in replatforming, modernizing, and launching new initiatives, we stand out by taking true ownership of your engineering projects.

We love helping teams with projects that have missed their deadlines or helping keep your strategic digital initiatives on course. Check out our case studies and our clients that trust us with their engineering.

About the author(s)

Dane Grant
JavaScript developer building things on web, native, and server environments. Free time filled with reading, cooking, dog, sports, comedy, and music.
@danecando @danecando

The Journey To Making A New Framework: TanStack Start with Tanner Linsley

Danny Thompson, Director of Technology at This Dot Labs, talks with Tanner Linsley, Creator of TanStack, about his latest project, TanStack Start. They discuss the challenges of existing frameworks like Next.js and Remix, the development of TanStack Router, and the future of React Server Components. Tanner also explains how caching strategies and fine-grained invalidation can transform the user experience. Chapters - - Introduction & Tanner’s Background (00:00) - Going Full-Time on TanStack (01:00) - The Birth of TanStack Router (02:21) - Why Build Another Framework? (04:00) - React Server Components: Potential & Limitations (07:05) - Fine-Grained Cache Invalidation & UX (09:02) - Parallel Data Fetching in Routing (13:39) - TanStack Start: Alpha & Future Plans (16:41) - Where to Learn More About TanStack (18:48) Find Tanner Linsley on Social Media Twitter: https://x.com/tannerlinsley Linkedin: https://www.linkedin.com/in/tannerlinsley/ Github: https://github.com/tannerlinsley TanStack: https://tanstack.com/ Sponsored by Wix Studio...

Oct 9, 2024

1 min

TanStack QueryJavaScriptReact

Fly.io for Easier Cloud Deployment with Annie Sexton

Annie Sexton, Developer Advocate at Fly.io, to discuss Fly.io’s approach to simplifying cloud deployment. Annie shares Fly.io's unique position as a public cloud that offers the flexibility of infrastructure control with a streamlined developer experience. They explore Fly.io’s private networking and distributed app capabilities, allowing developers to deploy applications close to users worldwide with ease. Annie also addresses common challenges in distributed systems, including latency, data replication, and the balance between global reach and simple, single-region projects. Chapters: - 00:00 - 01:32 Introduction to the Modern Web Podcast and Guests - 01:33 - 04:00 Overview of Fly.io and Annie’s Role as Developer Advocate - 04:01 - 06:35 What Makes Fly.io Stand Out Among Cloud Platforms - 06:36 - 08:57 Distributed Applications: Benefits and Use Cases - 08:58 - 11:28 Understanding Distributed Web Servers and Private Networking - 11:29 - 13:49 Challenges in Distributed Data and Replication Techniques - 13:50 - 16:12 Fly.io’s Unique Solutions for Data Consistency - 16:13 - 18:34 When to Consider a Distributed Setup for Your Application - 18:35 - 20:35 Tools and Tips for Evaluating Geographical Distribution Needs - 20:36 - 22:22 Simplifying Global Deployment with Fly.io’s Command Features - 22:23 - 24:18 Considerations for Latency and Performance Optimization - 24:19 - 26:45 Balancing Simplicity with Advanced Control for Developers - 26:46 - 29:04 Easy Deployment for Hobbyists and Smaller Projects - 29:05 - 31:27 Getting Started on Fly.io with Fly Launch - 31:28 - 33:48 Developer Advocacy and Meeting Diverse Needs in the Cloud - 33:49 - 36:15 Catering to Beginners and Experienced Developers Alike - 36:16 - End Closing Remarks and Where to Find Fly.io and the Hosts Follow Annie Sexton on Social Media Linkedin: ⁠https://www.linkedin.com/in/annie-sexton-11472a46/⁠ Github: ⁠https://github.com/anniebabannie⁠ Sponsored by This Dot: thisdot.co...

Nov 6, 2024

2 mins

Software EngineerJavaScript

The CSS / Utility hybrid approach with Tailwind v4

Just recently, the progress on the next major version of Tailwind CSS was open-sourced, along with a preview post. This is very exciting news to me, and I love the direction they’ve taken with this release. Tailwind can be a pretty polarizing topic among developers, but I believe that we can find some common ground and live in harmony. In this post, we’ll look at how the CSS + Tailwind hybrid approach is getting an upgrade in v4 and some of the patterns that we can take advantage of to provide a stellar styling experience on our websites. The hybrid approach It doesn’t matter what your personal take on Tailwind is, the fact is utility classes are an incredibly useful pattern for styling websites with CSS. I’m not sold on the hard-line, all-or-nothing approach that Tailwind has always recommended. Having a class string that extends way off the screen on an ultra-wide monitor is not pretty. Combining traditional CSS classes with utility classes helps cut down on the styling noise in your markup and provides some advantages when applied correctly. This post will cover some useful patterns and best practices for using CSS and Tailwind in harmony Tailwind going “CSS-native” In the v4 introduction post, they state A major goal of Tailwind CSS v4.0 is making the framework feel CSS-native, and less like a JavaScript library. I love that they are heading in this direction, and I’m imagining Tailwind as the toolkit for styling websites with CSS. It is going to replace the plethora of tools from the past and provide support for all the modern niceties like: * Importing CSS files with @import * Vendor prefixing _(no more autoprefixr)_ * Improved browser support for modern features like CSS nesting and media query ranges. This means less worry for us as developers. We can write our code and build our sites using the modern features that the platform provides without sweating all the other details and edge cases. The talented folks at Tailwind and the open-source community have our backs. Tailwind v4 CSS configuration The biggest step in the “CSS-native” direction and the feature that I’m most excited about is the CSS configuration. This is great for embracing CSS and Tailwind as one instead of two factions at battle. If you’ve been using Tailwind exclusively for a long time like I have, you might be out of touch with all the great features and tools that CSS provides out of the box now. This is a great opportunity to get back to learning and using the platform. In Tailwind v4 we do our configuration and theming with CSS variables. To get an idea of what this looks like check out the default theme on GitHub. In our configuration we can override any values from the default theme or extend it with new values. ` All the values from the theme are exposed as CSS variables. We can reference them in our CSS files or directly in our utility classes. ` ` Best practices for combining CSS with utility classes I can understand why Tailwind recommends using strictly utility classes. It’s easy to shoot yourself in the foot and run into the issues that utility classes set out to solve in the first place. I believe if you follow some general guidelines you can safely have the best of both worlds. Create focused/specialized classes CSS tends to get messy when we use classes that are overly specific with styles that apply to just one or a small number of use cases. Take a calendar where the days are custom checkboxes. You might have some pretty specialized styles for this bit of UI. ` Notice that we just add some specific styles that apply to this use case. This gives us the flexibility to keep composing our styles with utility classes. Some things are better left to utilities The best way to avoid wandering too far off the path of enlightenment is to stick with utility classes for certain (most?) things. Spacing and layouting are examples of things that are probably best left to utility classes. These typically vary all across a page, and encoding them in a class will make it a lot less flexible. A code smell to look out for: If you have abstracted something to a class and you end up overriding certain aspects of its styles in different places. Those styles should probably be utility classes. Classes as components Tailwind has always recommended using a component system for your UI components so that your utility classes are all defined in a single place. You don’t want to have to edit 50 different files to make a change to the style of your buttons across your website. I’ve found that defining things that might be simple “components” like buttons, badges, links, etc as classes works just as well in most cases. You can use Tailwind CSS with the @apply directive or traditional class definitions for this: ` You can even bring the BEM naming convention back to compose variants on top of base component styles. (or name them however you’d like!) ` Now we can easily define badges in our markup: ` Modern CSS and other interesting utility hybrid patterns I think a lot of us are realizing that modern CSS is pretty great. There are a ton of awesome new features gaining support across major browsers, like CSS nesting, container queries, and more! More and more people are also coming around to the utility of utility classes. If you want to dive deeper and see other interesting approaches and patterns when combining modern CSS with utility classes, check out the post: Modern CSS patterns in Campfire. Summary I’m looking forward to the Tailwind CSS configuration and other awesome updates coming in v4. Using Tailwind doesn’t have to be a one-size-fits-all approach. If you want to write some CSS, I say go for it! Hopefully, some of the points in this post will lead to success if you decide to do so....

May 10, 2024

4 mins

Tailwind CSSCSS

Introduction to Zod for Data Validation

As web developers, we're often working with data from external sources like APIs we don't control or user inputs submitted to our backends. We can't always rely on this data to take the form we expect, and we can encounter unexpected errors when it deviates from expectations. But with the Zod library, we can define what our data ought to look like and parse the incoming data against those defined schemas. This lets us work with that data confidently, or to quickly throw an error when it isn't correct. Why use Zod? TypeScript is great for letting us define the shape of our data in our code. It helps us write more correct code the first time around by warning us if we are doing something we shouldn't. But TypeScript can't do everything for us. For example, we can define a variable as a string or a number, but we can't say "a string that starts with user_id_ and is 20 characters long" or "an integer between 1 and 5". There are limits to how much TypeScript can narrow down our data for us. Also, TypeScript is a tool for us developers. When we compile our code, our types are not available to the vanilla JavaScript. JavaScript can't validate that the data we actually use in our code matches what we thought we'd get when we wrote our TypeScript types unless you're willing to manually write code to perform those checks. This is where we can reach for a tool like Zod. With Zod, we can write data schemas. These schemas, in the simplest scenarios, look very much like TypeScript types. But we can do more with Zod than we can with TypeScript alone. Zod schemas let us create additional rules for data parsing and validation. A 20-character string that starts with user_id_? It's z.string().startsWith('user_id_').length(20). An integer between 1 and 5 inclusive? It's z.number().int().gte(1).lte(5). Zod's primitives give us many extra functions to be more specific about *exactly* what data we expect. Unlike TypeScript, Zod schemas aren't removed on compilation to JavaScript—we still have access to them! If our app receives some data, we can verify that it matches the expected shape by passing it to your Zod schema's parse function. You'll either get back your data in exactly the shape you defined in your schema, or Zod will give you an error to tell you what was wrong. Zod schemas aren't a replacement for TypeScript; rather, they are an excellent complement. Once we've defined our Zod schema, it's simple to derive a TypeScript type from it and to use that type as we normally would. But when we really need to be sure our data conforms to the schema, we can always parse the data with our schema for that extra confidence. Defining Data Schemas Zod schemas are the variables that define our expectations for the shape of our data, validate those expectations, and transform the data if necessary to match our desired shape. It's easy to start with simple schemas, and to add complexity as required. Zod provides different functions that represent data structures and related validation options, which can be combined to create larger schemas. In many cases, you'll probably be building a schema for a data object with properties of some primitive type. For example, here's a schema that would validate a JavaScript object representing an order for a pizza: ` Zod provides a number of primitives for defining schemas that line up with JavaScript primitives: string, number, bigint, boolean, date, symbol, undefined, and null. It also includes primitives void, any, unknown, and never for additional typing information. In addition to basic primitives, Zod can define object, array, and other native data structure schemas, as well as schemas for data structures not natively part of JavaScript like tuple and enum. The documentation contains considerable detail on the available data structures and how to use them. Parsing and Validating Data with Schemas With Zod schemas, you're not only telling your program what data should look like; you're also creating the tools to easily verify that the incoming data matches the schema definitions. This is where Zod really shines, as it greatly simplifies the process of validating data like user inputs or third party API responses. Let's say you're writing a website form to register new users. At a minimum, you'll need to make sure the new user's email address is a valid email address. For a password, we'll ask for something at least 8 characters long and including one letter, one number, and one special character. (Yes, this is not really the best way to write strong passwords; but for the sake of showing off how Zod works, we're going with it.) We'll also ask the user to confirm their password by typing it twice. First, let's create a Zod schema to model these inputs: ` So far, this schema is pretty basic. It's only making sure that whatever the user types as an email is an email, and it's checking that the password is at least 8 characters long. But it is *not* checking if password and confirmPassword match, nor checking for the complexity requirements. Let's enhance our schema to fix that! ` By adding refine with a custom validation function, we have been able to verify that the passwords match. If they don't, parsing will give us an error to let us know that the data was invalid. We can also chain refine functions to add checks for our password complexity rules: ` Here we've chained multiple refine functions. You could alternatively use superRefine, which gives you even more fine grained control. Now that we've built out our schema and added refinements for extra validation, we can parse some user inputs. Let's see two test cases: one that's bound to fail, and one that will succeed. ` There are two main ways we can use our schema to validate our data: parse and safeParse. The main difference is that parse will throw an error if validation fails, while safeParse will return an object with a success property of either true or false, and either a data property with your parsed data or an error property with the details of a ZodError explaining why the parsing failed. In the case of our example data, userInput2 will parse just fine and return the data for you to use. But userInput1 will create a ZodError listing all of the ways it has failed validation. ` ` We can use these error messages to communicate to the user how they need to fix their form inputs if validation fails. Each error in the list describes the validation failure and gives us a human readable message to go with it. You'll notice that the validation errors for checking for a valid email and for checking password length have a lot of details, but we've got three items at the end of the error list that don't really tell us anything useful: just a custom error of Invalid input. The first is from our refine checking if the passwords match, and the second two are from our refine functions checking for password complexity (numbers and special characters). Let's modify our refine functions so that these errors are useful! We'll add our own error parameters to customize the message we get back and the path to the data that failed validation. ` Now, our error messages from failures in refine are informative! You can figure out which form fields aren't validating from the path, and then display the messages next to form fields to let the user know how to remedy the error. ` By giving our refine checks a custom path and message, we can make better use of the returned errors. In this case, we can highlight specific problem form fields for the user and give them the message about what is wrong. Integrating with TypeScript Integrating Zod with TypeScript is very easy. Using z.infer<typeof YourSchema> will allow you to avoid writing extra TypeScript types that merely reflect the intent of your Zod schemas. You can create a type from any Zod schema like so: ` Using a TypeScript type derived from a Zod schema does *not* give you any extra level of data validation at the type level beyond what TypeScript is capable of. If you create a type from z.string.min(3).max(20), the TypeScript type will still just be string. And when compiled to JavaScript, even that will be gone! That's why you still need to use parse/safeParse on incoming data to validate it before proceeding as if it really does match your requirements. A common pattern with inferring types from Zod schemas is to use the same name for both. Because the schema is a variable, there's no name conflict if the type uses the same name. However, I find that this can lead to confusing situations when trying to import one or the other—my personal preference is to name the Zod schema with Schema at the end to make it clear which is which. Conclusion Zod is an excellent tool for easily and confidently asserting that the data you're working with is exactly the sort of data you were expecting. It gives us the ability to assert at runtime that we've got what we wanted, and allows us to then craft strategies to handle what happens if that data is wrong. Combined with the ability to infer TypeScript types from Zod schemas, it lets us write and run more reliable code with greater confidence....

Nov 15, 2024

7 mins

JavaScriptZod

Let's innovate together!

We're ready to be your trusted technical partners in your digital innovation journey.

Whether it's modernization or custom software solutions, our team of experts can guide you through best practices and how to build scalable, performant software that lasts.

JSR - The cross-platform package manager for ESM

JSR - The cross-platform package manager for ESM

Setting the stage

NPM and JavaScript modules

JavaScript runtimes and interoperability

NPM Compatibility

JSR Overview

Native TypeScript

Packages

`jsr.json` file

Adding packages to a project

Publishing packages

Documentation

Browser support

Other notable features

Scoring

Summary

Dane Grant

You might also like

The Journey To Making A New Framework: TanStack Start with Tanner Linsley

Fly.io for Easier Cloud Deployment with Annie Sexton

The CSS / Utility hybrid approach with Tailwind v4

Introduction to Zod for Data Validation

Let's innovate together!

You might also like

The Journey To Making A New Framework: TanStack Start with Tanner Linsley

Fly.io for Easier Cloud Deployment with Annie Sexton

The CSS / Utility hybrid approach with Tailwind v4

Introduction to Zod for Data Validation

JSR - The cross-platform package manager for ESM

Setting the stage

NPM and JavaScript modules

JavaScript runtimes and interoperability

NPM Compatibility

JSR Overview

Native TypeScript

Packages

jsr.json file

Adding packages to a project

Publishing packages

Documentation

Browser support

Other notable features

Scoring

Summary

Dane Grant

The Journey To Making A New Framework: TanStack Start with Tanner Linsley

Fly.io for Easier Cloud Deployment with Annie Sexton

The CSS / Utility hybrid approach with Tailwind v4

Introduction to Zod for Data Validation

Let's innovate together!

The Journey To Making A New Framework: TanStack Start with Tanner Linsley

Fly.io for Easier Cloud Deployment with Annie Sexton

The CSS / Utility hybrid approach with Tailwind v4

Introduction to Zod for Data Validation

`jsr.json` file