Grundler

The no-faff Ruby frontend bundler.

Now that all the evergreen browsers have support for JavaScript module loading, we can finally pretend like node.js never happened! Grundler is the sinecure for everyone who's sick to death of npm, yarn, babel, webpack, parcel, rollup, vite, fartspray, and snowpack. And I only made one of those up.

Add this line to your application's Gemfile:

gem "grundler"

And then execute:

$ bundle install

Or install it yourself as:

$ gem install grundler

Sorry! But Grundler fills one of the most important niches in the Ruby ecosystem: MINE. Specifically, that would be the niche where I sit, precariously perched, cursing the bloat and complexity of node's module ecosystem, longing for the easy and carefree days of dropping a .js file into a "lib" folder and calling it a day. Seriously, we got ourselves into this hellscape just because we didn't think globals were enterprise-grade or whatever?! Like what were people even

You've totally used a package manager before. You'll need to use one to install this one, in fact. So you probably know most of the stuff you need to know. Grundler, as a design goal, tries to 1) leverage the new browser-supported module format and 2) do as little as possible. You won't find any script sections or dev dependencies in its configuration. You can't run commands through it, shrinkwrap, or add prepublish steps. It'll only grab packages for you off npm's repository so you can use them and you should be damn well content with that.

I'm not below that sort of thing but no, it reads your package.json kind of like you'd expect. Grundler only bothers with the important part, the { "dependencies" } section. If you expect it to also run your dev server or test suite or whatever, you will be disappointed. You might be disappointed anyway but I'd honestly prefer you at least be disappointed with the right things?

Grundler goes to everyone's favorite JavaScript repository, npm, to look for the package you wanted to install. If it's found, it'll look up the most recent version, download its tarball, and analyze the JSON metadata to see if it uses the new ES module format. If it does, bingo, we can untar the module file and only the module file to our dependency folder (currently called nodules because come on, it was right there but the node people were too buttoned-up I guess). This is cool because it's reminiscent of the old "go to someone's site and download a JS file" but structured and reproducible.

If the package you're trying to fetch isn't using ES module format though, you're in trouble.

Trouble. Grundler has a thing I've aptly named CrapMode that gets engaged whenever a package is using one of the old bothersome and browser-incompatible module formats (which, unfortunately, is pretty often). It will wrap the library in a simple little shim of sorts, to fool the module into believing it can hook into module.exports but AHA that's a honeypot we put there and then we can export. It's bound to fail in mysterious ways but it turns out there are a lot of packages that work just fine with it.

So you may get lucky. Or you may not. People have really been contorting themselves over the years doing weird shit to get their packages loading across the various formats the Internet has coughed up, and module.exports might not be a thing they use. Either way, if the package is one you really want, the responsible and adult thing to do is to go to their repository and help them out with a PR to convert to the new module format. Node has had support for quite a while, now browsers have it too — we're finally on track towards the compilation-free past/future again. Contribute and be part of it!

You import it, like you would any file you wrote yourself. Look:

$ bundle exec grundle add three
Installing three 0.124.0

That should result in a file called nodules/three.js. That's your package, ready for pickup! Now, in order to import things in the browser, you need to opt in to the browser's module system by using type="module" in your script tag:

<script src="main.js" type="module"></script>

And inside main.js you can do:

import * as THREE from "./nodules/three.js";
console.log(THREE);

And if that thing is an ES module, or the CrapMode shim worked, you're good to go!

I hear you. It's not as pretty as just from "three". People are working on this problem, with something called import maps. But it's not THAT ugly and look: the code is there. It can be loaded, just the way you'd expect if a teammate had written the code. You don't have npm's hundreds of megabytes of dep-tree lurking beneath the depths, ready to kneecap your CI system and bog down your builds. Let's hope we can all get back to the fairytale land of "it's just another file in your project". I'd even check the nodules folder in to your project if I were you — after all, in the end you're responsible for everything you ship, so why do we keep pretending our dependencies are this pristine thing, never to be touched?

Go away! Contemplate your life choices. I will have no truck with your transpiled abomination. The entire point of Grundler is to dramatically shorten the build chain, get back to just writing JS files, doing away with build servers and transpilation once and for all. Plus everyone knows TypeScript is just .NET wearing JavaScript's skin, ready to murder you in your sleep with a rictus grin on its rotting, lying face.

Yes. I'm throwing my hands up here and again saying look, I'm sorry, but browsers don't do the import maps thing yet. And adding version numbers to downloaded libs would be murder on your actual source files: going through every file in your project that has import * from thing-0.10.1.js and replacing it with thing-0.10.2.js every time you bumped versions would absolutely SUCK.

You realistically have three options at this time:

1. Weep and use Webpack
2. Ditch your far-future cache and trust people's browsers to do the right thing
3. Use an import-aware fingerprint tool when building for production

Ha! Pop quiz, hotshot: what has two thumbs and has just written that kind of fingerprinting tool? It trawls a directory full of js files, copies them to md5-stamped files, and rewrites all import statements to use the stamped files. I'll put it up once it's been documented and more thoroughly tested. And once I've made sure it's actually a good idea.

Yes, yes, it's a build step, which makes me a little sad, but fingers crossed we can get rid of it when browsers have robust support for import maps. I bet the Babel crew have said something similar but then it kind of never happened and the tools got entrenched and suddenly everyone's stuck in the labyrinth with no way out and an angry minotaur belching somewhere behind them. But you can trust me! I'm a very honest-looking guy and I totally mean it: ship import maps and this won't be a problem anymore.

Grundler tries its best to not do very much. No spiderweb of metadata or configuration, no weird executable sandbox things, and only four commands:

Run grundle add [list of packages]. If you wanted to install, say, three.js and ky and have installed Grundler from your Gemfile it'd look like this:

bundle exec grundle add three ky

Grundler will go and find the latest version of those packages, install them, and add them to the package.json file.

Once you've added a few packages, you can distribute the package.json and install using that, and Grundler will fetch the version specified. To install from package.json, run:

bundle exec grundle install

Sometimes a package has been updated! To grab all the newest versions, run:

bundle exec grundle update

All your packages will be updated and written to package.json. You currently can't use the update command to update single packages, but Grundler is dumb enough that adding the packages again by running add package1 package2 will do that for you.

Tired of a package? No module export and CrapMode didn't work? Run:

bundle exec grundle remove packagename

It'll be removed from your nodules folder and your package.json file. Grundler will also get rid of any empty directories left after a removal.

There's only one configuration directive at this point and it's called nodulePath. Say you have all your JS source files in a directory called src. Then you might want your dependencies to live in src/nodules. Add the nodulePath directive to your package.json like so:

{
  "dependencies": {},
  "nodulePath": "./src/nodules"
}

That'll make all of Grundler's operations work on that directory instead.

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Testing is done with Minitest and mocking of npm is done with webmock. I initially wanted to use VCR for the JSON stubs but there seemed to be a lot of configuration and nothing worked and so I just put them there by hand and this is all TMI and never mind, there's like 200 lines of tests in a single file, you'll get the hang of it quickly.

Bug reports and pull requests are welcome on GitHub at https://github.com/johanhalse/grundler.

The gem is available as open source under the terms of the MIT License.