Javascript setup with jsbundling-rails and esbuild

[olivier-thatch]

Hello,

We are using jsbundling-rails and esbuild to bundle the JS code in our app, and I am having a hard time figuring out how to enable Pagy's Javascript features with our setup.

I've read the docs at https://ddnexus.github.io/pagy/docs/api/javascript/setup/ and understand that not providing a npm package is a deliberate decision, but this poses a bit of a problem for us.

AFAICT, the only way to integrate the Pagy JS helpers in our app would be to bypass esbuild and set up Sprockets to process the Pagy JS file, as described in this StackOverflow answer. If we do this, the event handling initialization code also has to be set up in a custom file processed by Sprockets: it can't be done via Stimulus, because Stimulus code is handled by esbuild, which has no knowledge of Pagy in this setup.

As much as I'd like to use Pagy's JS, the above is not a viable solution for us.

Am I missing something obvious?

If not, would the maintainers reconsider shipping Pagy's JS code as an npm package? This is after all what Turbo itself does, as well as some other Ruby gems like ahoy.

[ddnexus]

@olivier-thatch Sorry, Javascript handling is a Babel of different possible/impossible setups, and I am very far to remember them all, so here are a few concepts that should help.

First of all: the reason why pagy is not a npm package is because the JS code is strictly coupled with, and depending from the ruby code for each specific version. In other words, with a npm package for pagy... you would have to update the npm package with the same identical version of the pagy gem each time you do a bundle update. Having to remember that would not only be very annoying, but utterly error prone, and frankly quite unnecessary, since the JS for pagy is a short module in a single file.

Now, the general concept to make JS work with pagy in a bundled environment is quite simple: you have to instruct your bundle system to bundle the pagy-module.js file provided by the gem and init it when you use it. The documentation tries to cover the most popular tools, but there are so many possible combinations of tools that it will never be really complete, however here are the relevant concepts.

You can consider (configure and use) the pagy module almost exactly as one of your own JS module written in your app. The only difference is that the pagy module is not in a path of your app, but it's in Pagy.root.join('javascripts'). The trick it's simply knowing how to configure your specific builder to look into that pagy path at building time. Again I don't remember what your own bundle system requires in order to do so, but I am pretty sure it's quite straightforward, although it might require some digging.

After you "convince" your builder about looking into the pagy path, and/or bundling the pagy-module.js, you will just have to remember to initialize it with Pagy.init() after the page loads, so the pagy helpers will work.

Please, research how to configure your specific bundle system and let us know (for the benefit of other users), or feel free to ask more questions/details.

[ddnexus]

@olivier-thatch There's a documentation file that was meant to be in the doc, but it's not currently linked nor fully integrated (thanks to @benkoshy to point it out to me).

That file specifically describes also how to use esbuild.

Sorry, in my previous answer I overlooked "esbuild" and just assumed your builder was not one of the builders included in the (supposedly linked) doc. 🤦

[ddnexus]

Fixed in 1605b22. The Javascript Setup doc should be complete now.

[benkoshy]

Perhaps this demo app may help: https://github.com/benkoshy/pagy-esbuild

Especially look at how it is built:
benkoshy/pagy-esbuild@f4234b6

look at the package.json file: https://github.com/benkoshy/pagy-esbuild/blob/f4234b664caf0d9ccf08963da522a2be253bbbd4/package.json#L10

I admit, in light of newer information, it may not be the canonical approach.

[olivier-thatch]

Thanks for the quick reply and docs update!

Unfortunately it doesn't quite work for us, because we're also using TypeScript for our Stimulus controllers and while esbuild supports NODE_PATH, TypeScript doesn't :(

I tried using path mapping, but:

1. it's not obvious how one would invoke bundle show 'pagy' in that context (TypeScript reads its config from a .tsconfig.json file, though I think the mapping for Pagy could be passed as a CLI argument with --paths), and
2. even when I hardcoded the correct path for my development environment, I still couldn't get it to work

Anyway, I understand that this is getting way too specific and not something that can (or ought to) be covered by the docs. I might take another stab at this when I have the time, and if I do manage to get it to work, I'll post the results here.

Feel free to close the discussion for now. Really appreciate the help you've provided!

[ddnexus]

I am sure there's a more proper way for your setup, however there are a couple of ways that would make it work: create a symlink (as indicated in the tab "Generic" in the doc), or even make a copy of the file in an app compiled source dir, from the pagy initializer in development.

That would ensure that you always have the right (i.e. in sync even after an update) local copy of the file, compilable like any other app files.