Experience migrating from Rails 6.1 webpacker to Rails 7 JS Bundling + esbuild

[abevoelker]

I just wanted to give a small experience report after doing a migration from a Rails 6.1 app using webpacker to Rails 7 with JS Bundling + esbuild and Propshaft. I ran into a couple little issues that are likely my own fault due to inexperience with JS tooling or otherwise missing something somewhere. Regardless I wanted to share some SEO keywords in case I can help another developer out or give food for thought to potentially improve the jsbundling-rails et al DX.

Before that though I have to say I really like the new JS/CSS Bundling and Propshaft simplicity, and I especially love using esbuild over webpack. My app has quite a few React components, and before migrating my webpack builds had creeped to over 20 seconds. So every time I'd do something as simple as change the wording of text I'd have to wait 20 seconds to see the full change... that was a productivity killer. Now with esbuild I'm down to a few hundred milliseconds! 🎉 So major kudos to everyone who worked on all these new Rails components - thank you very much!

That said, one issue I ran into at first was esbuild not building all my JavaScript files due to directory depth.

JS Bundling's current javascript:install:esbuild task adds a build NPM script that looks like this:

esbuild app/javascript/*.* --bundle --sourcemap --outdir=app/assets/builds --public-path=assets

Unfortunately, esbuild doesn't recurse into subdirectories. So, given my starting app/javascript/packs looked like this:

$ tree app/javascript/packs

app/javascript/packs
├── application.js
├── error_boundary.jsx
├── funding_source_form.jsx
├── modules
│   ├── form_helpers.js
│   ├── json_utils.js
│   └── utils.js
├── spinner.jsx
└── views
    ├── donate
    │   └── show.js
    ├── pages
    │   └── welcome.jsx
    └── settings
        ├── accounts
        │   └── edit.js
        ├── bank_accounts
        │   ├── dwolla
        │   │   └── link.jsx
        │   └── edit.jsx
        ├── payment_methods
        │   └── edit.jsx
        └── profile
            └── edit.js

It was only emitting JavaScript to app/assets/builds at the first depth level. I naively tried changing the syntax to this:

esbuild app/javascript/**/*.* ...

But that only added one extra level of depth rather than fully recursing into all subdirectories. After googling, it seems that esbuild doesn't support this natively - and doesn't plan to - and the recommendation is to either do this in JavaScript and call esbuild from there, or shell out to Unix find, so I did the latter and edited the npm script thusly:

esbuild `find app/javascript -type f` --bundle --sourcemap --outdir=app/assets/builds --public-path=assets

(Another possible find command that's explicit about filetypes could look like this: find app/javascript -name '*.js' -o -name '*.jsx' -o -name '*.ts' -o -name '*.tsx')

That solved my missing builds problem.

Another issue was import paths in my React code not working properly. In webpacker, I would have code like this:

// app/javascript/packs/views/settings/bank_accounts/edit.jsx
import React from 'react'
import ErrorBoundary from 'packs/error_boundary'
...

Which, after moving all my JavaScript out of the packs directory and up one level, I was looking forward to writing my imports without packs/ prefixes, but esbuild was not liking it. I could get esbuild to work by using relative paths, but that was unwieldy in deep subdirectories:

// app/javascript/views/settings/bank_accounts/edit.jsx
import React from 'react'
import ErrorBoundary from '../../../error_boundary'
...

The fix was to add a tsconfig.json file with this:

{
  "compilerOptions": {
    "baseUrl": "app/javascript"
  }
}

And change the npm script to use it:

esbuild `find app/javascript -type f` --tsconfig=./tsconfig.json --bundle --sourcemap --outdir=app/assets/builds --public-path=assets

Now I could write all my import statements succinctly:

// app/javascript/views/settings/bank_accounts/edit.jsx
import React from 'react'
import ErrorBoundary from 'error_boundary'
...

I think those were the main issues I ran into. Perhaps jsbundling-rails could be enhanced to help future devs avoid my pitfalls?