Using packages from JSR with esbuild#

JSR is a brand new package repository for “modern JavaScript and TypeScript”, launched on March 1st by the Deno team as a new alternative to npm

My JavaScript ecosystem fluency isn’t great, so it took me a bit of work to figure out how to use packages from JSR in my browser.

Installing yassify with npx jsr add#

@kwhinnery/yassify is the demo package created as part of that introductory blog post. The code itself is a tiny snippet of TypeScript:

1
/**
2
 * Yassify a string of text by appending emoji
3
 *
4
 * @param str The string of text to yassify.
5
 * @returns a string of text with emoji appended
6
 */
7
export function yassify(str: string): string {
8
  return `${str} 💅✨👑`;
9
}

It’s published to JSR here. That page includes npm instructions for using it that look like this:

1
npx jsr add @kwhinnery/yassify

1
import * as mod from "@kwhinnery/yassify";

For someone with limited JavaScript ecosystem fluency like myself, that is not enough information! I want to run this code in a browser.

Part of the problem is that there are a bewildering array of build tool options. I wanted the thing with the least number of steps - eventually I found this pattern using esbuild that seems to work.

I already had npm and npx installed.

First I created myself a directory for my experiment:

1
mkdir /tmp/site
2
cd /tmp/site

I used the npx jsr add command from the JSR documentation:

1
npx jsr add @kwhinnery/yassify

Output:

1
Setting up .npmrc...ok
2
Installing @kwhinnery/yassify...
3
$ npm install @kwhinnery/yassify@npm:@jsr/kwhinnery__yassify
4

5
added 1 package in 711ms
6

7
Completed in 824ms

This created a bunch of files. Running find . reveals the following:

1
./node_modules
2
./node_modules/@kwhinnery
3
./node_modules/@kwhinnery/yassify
4
./node_modules/@kwhinnery/yassify/mod.d.ts
5
./node_modules/@kwhinnery/yassify/package.json
6
./node_modules/@kwhinnery/yassify/mod.js
7
./node_modules/.package-lock.json
8
./.npmrc
9
./package-lock.json
10
./package.json

The package.json file contains:

1
{
2
  "dependencies": {
3
    "@kwhinnery/yassify": "npm:@jsr/kwhinnery__yassify@^1.0.1"
4
  }
5
}

.npmrc has the following, which is described in the JSR documentation about npm compatibility:

1
@jsr:registry=https://npm.jsr.io

The actual yassify code lives in that ./node_modules/@kwhinnery/yassify/mod.js file.

OK - so we’ve run a command and got ourselves a node_modules directory with the yassify code in it. How do we use that in a browser?

Building an index.js file with esbuild#

Here’s a tiny JavaScript file that uses yassify:

1
import { yassify } from "@kwhinnery/yassify";
2
const h1 = document.querySelector("h1");
3
h1.innerText = yassify(h1.innerText);

And the incantation to have esbuild resolve that import and bundle all of the code together into a single file:

1
npx esbuild index.js --bundle

That outputs directly to standard out:

1
(() => {
2
  // node_modules/@kwhinnery/yassify/mod.js
3
  function yassify(str) {
4
    return `${str} \u{1F485}\u2728\u{1F451}\u{1F984}`;
5
  }
6

7
  // index.js
8
  var h1 = document.querySelector("h1");
9
  h1.innerText = yassify(h1.innerText);
10
})();

Or you can add --outfile=bundle.js to write it to a file:

1
npx esbuild index.js --bundle --outfile=bundle.js

Now here’s an index.html file that makes use of this bundle:

1
<!DOCTYPE html>
2
<html lang="en">
3
<head>
4
  <meta charset="UTF-8">
5
  <title>Yassify</title>
6
</head>
7
<body>
8
<h1>Yassify</h1>
9
<script src="bundle.js"></script>
10
</body>
11
</html>

And that works! You can open index.html directly in a browser and it loads and executes the bundled code.

Trying that with my own package - and failing to get it to work#

I have just one package on NPM at the moment: datasette-table, an experimental Web Component for rendering tables from Datasette on a page.

The source code for that is in simonw/datasette-table on GitHub.

I followed the JSR intro post and published it to GitHub.

I signed into JSR using my GitHub account and created a scope called @datasette - all packages on JSR are published within a scope.

I added a jsr.json file te the root of the repository:

1
{
2
  "name": "@datasette/table",
3
  "version": "0.1.0",
4
  "exports": "./datasette-table.js"
5
}

Then I ran this command:

1
npx jsr publish

This opened my browser to authenticate and pushed the package to JSR: jsr.io/@datasette/table. Pretty smooth!

Let’s try using that package via the esbuild method described above:

1
mkdir /tmp/datasette-demo
2
cd /tmp/datasette-demo
3
npx jsr add @datasette/table
4
echo 'import * as mod from "jsr:@datasette/table";' > index.js
5
npx esbuild index.js --bundle --outfile=bundle.js

And I got this error:

1
✘ [ERROR] Could not resolve "npm:lit@^2.2.7"
2

3
    node_modules/@datasette/table/datasette-table.js:1:36:
4
      1 │ import {LitElement, html, css} from 'npm:lit@^2.2.7';
5
        ╵                                     ~~~~~~~~~~~~~~~~
6

7
  You can mark the path "npm:lit@^2.2.7" as external to exclude it from the bundle, which will
8
  remove this error and leave the unresolved path in the bundle.
9

10
1 error

lit is the only dependency of my component. I checked node_modules and it had all of the lit files in it, so they had been installed correctly - but something wasn’t working.

I tried adding --external:npm:lit to the esbuild command, but that didn’t help.

This failed too:

1
npx esbuild index.js --bundle --outfile=bundle.js --external:lit

So I started from scratch:

1
mkdir /tmp/datasette-demo2
2
cd /tmp/datasette-demo2

This time I used a mechanism I found in the advanced setup section of the npm compatibility documentation:

1
echo '@jsr:registry=https://npm.jsr.io' > .npmrc
2
npm install @jsr/datasette__table

find . showed me that it had installed the Lit packages, but I also noticed this:

1
find . | grep datasette

1
./node_modules/@jsr/datasette__table
2
./node_modules/@jsr/datasette__table/datasette-table.js
3
./node_modules/@jsr/datasette__table/package.json

So the JSR @datasette/table package is in a slightly different shape.

Now I tried the esbuild command again:

1
echo 'import * as mod from "@jsr/datasette__table";' > index.js
2
npx esbuild index.js --bundle --outfile=bundle.js

But I got the same error again:

1
✘ [ERROR] Could not resolve "npm:lit@^2.2.7"
2

3
    node_modules/@jsr/datasette__table/datasette-table.js:1:36:
4
      1 │ import {LitElement, html, css} from 'npm:lit@^2.2.7';
5
        ╵                                     ~~~~~~~~~~~~~~~~
6

7
  You can mark the path "npm:lit@^2.2.7" as external to exclude it from the bundle, which will
8
  remove this error and leave the unresolved path in the bundle.
9

10
1 error

And at this point… I gave up. I’m still seeking a solution - progress so far:

I asked about this on the JSR Discord and they suggested it might be a bug, so I filed Something rewrote my import to from ‘npm@^2.2.7’; and now I can’t build with esbuild
I started a discussion on Mastodon and Bill Mill found a workaround for the problem using the esbuild_deno_loader plugin and Deno to build the bundle.

And now it works!#

Update 5th March 2024: the JSR team shipped this fix and now the following recipe works exactly as I want it to:

1
mkdir /tmp/datasette-demo3
2
cd /tmp/datasette-demo3
3
echo '@jsr:registry=https://npm.jsr.io' > .npmrc
4
npm install @jsr/datasette__table
5
echo 'import * as mod from "@jsr/datasette__table";' > index.js
6
npx esbuild index.js --bundle --outfile=bundle.js
7
echo '<!DOCTYPE html>
8
<html lang="en">
9
<head>
10
  <meta charset="UTF-8">
11
  <title>Datasette News</title>
12
</head>
13
<body>
14
  <datasette-table
15
  url="https://datasette.io/content/news.json"
16
></datasette-table>
17
<script src="bundle.js"></script>
18
</body>
19
</html>' > index.html

Now open index.html in a browser and:

Screenshot of a page with a table of recent news articles on it, rendered by my Web Component