Migrating from Webpacker to Vite - some recipes

[zealot128]

We just successfully migrated a medium sized frontend app to Vite and removed a bunch of Webpack(er) dependencies.

git diff --shortstat origin/master -- app package.json config
 212 files changed, 1461 insertions(+), 1130 deletions(-)

I've written about all the errors that occurred and how we handled it., namely:

• How to handle module import without prefix, loading: import FooComponent from "admin/dashboard/Component.vue" instead of prefixing everything with @/ (by using alias)
• const foo = require("foo") -> import foo from "foo"
• require.context - just use @ElMassimo's helper repo 😛
• suffix needed for non-js/non-ts imports (e.g., vue: import Foo from "Foo" -> import Foo from "Foo.vue", the same is true for async imports: import("./components/Component.vue")
• .. and a couple more special cases that are maybe not so common (GraphQL loader, vuelidate/Vue2 import issues in production/test, bootswatch/sass imports)

In total, it took about 2 days, and a loooot of it is debugging the Vuelidate import problem, rerunning/adjusting system-specs, as we also went from Apparition to Cuprite test runner. Hopefully, the next person running into this post will have a nicer experience.
I am confident that will amortize in the future with much faster startup times and functioning HMR, but getting rid of 6000 LOCs of yarn.lock seems to be already a great prospect for happiness...

Also, big thanks to @ElMassimo for running the whole vite-ruby ecosystem!

[ElMassimo]

Thanks for sharing Stefan! 😃

I think it will be nice adding this article to a Related Articles footer in the Migration section of the docs.

Let me know if you are ok with that, and I can add it (or a PR is also welcome).

[zealot128]

Ah that's a great section! Maybe even we can add one or two aspects directly. Even mentioning your Stimulus helper repo for the require.context stuff, if necessary.

I am not sure, how many other people have the style of importing the own modules without prefix: import Foo from "foo/Component.vue", instead of the "@/" or "~/" style. So maybe if we add the recipe from my post to the doc directly, would be a great help.

Maybe I can write something for https://github.com/ElMassimo/vite_ruby/blob/main/docs/src/guide/migration.md in the next day or so, and let you know about a doc-PR then!

[brendon]

One of the biggest confusion factors I faced was how Vite uses esbuild in development and @rollup/plugin-commonjs for the production build. I managed to get a running build in development only to struggle for hours firstly figuring out how to simulate a production build in development (turns out it was as simple as not running the dev server at all and allowing Rails to build the assets when a request came in), and secondly trying to understand why a bunch of jquery modules wouldn't load properly.

Turns out you can now use esbuild in production builds too with Vite 3: https://vitejs.dev/guide/migration.html#experimental

It worked well for me and I'd highly recommend it. I found that the esbuild build seems to behave more like a webpack build. @rails/ujs is one bizarre example where the esbuild import requires one to call Rails.start() like normal, but the @rollup/plugin-commonjs build somehow executed the code and caused @rails/ujs to self-start.

One other little tip in my case is because I was adding jQuery from a CDN and not in my build, I was able to cleanly make it available to anything requiring jQuery with the following config:

import { defineConfig } from 'vite'
import RubyPlugin from 'vite-plugin-ruby'
import { globalExternals } from '@fal-works/esbuild-plugin-global-externals'

export default defineConfig({
  plugins: [
    RubyPlugin()
  ],
  optimizeDeps: {
    esbuildOptions: {
      plugins: [globalExternals({ jquery: { type: "cjs", varName: "jQuery" } })]
    }
  }
})

Hope that helps someone :)

[brendon]

Hi @krsyoung, yes it's quite an unusual system having two build environments be so different from one another. I think it only runs smoothly for greenfield development. So many jQuery dependencies just wouldn't build properly with rollup/commonjs. I managed to change the universal module definition for one dependency to get it to work but others failed and in the end I rightly gave up.

You don't need to run anything special to get a production build in development. First run vite clobber to delete any existing builds, then just don't run vite at all and restart your rails server (puma-dev --stop? if you use puma-dev). Rails will then just kick off a vite production build in the background. You'll find those files under /public/vite-dev. If you use my config you should be getting an esbuild config and should also in that way not have any build errors if it's building find in development mode:

import { defineConfig } from 'vite'
import RubyPlugin from 'vite-plugin-ruby'
import { globalExternals } from '@fal-works/esbuild-plugin-global-externals'

export default defineConfig({
  plugins: [
    RubyPlugin()
  ],
  server: {
    hmr: {
      host: 'vitedevserver.test',
      clientPort: 443
    }
  },
  optimizeDeps: {
    disabled: false,
    esbuildOptions: {
      plugins: [globalExternals({ jquery: { type: "cjs", varName: "jQuery" } })]
    }
  },
  build: {
    commonjsOptions: { include: [] },
    sourcemap: true
  }
})

You can ignore my dev environment config. The key bits are optimizeDeps: { disabled: false } and build: { commonjsOptions: { include: [] } }. This stops the commonjs build, and will be the default in Vite 4 anyway so there's every reason to just do it now :D

I ended up including jQuery straight from a CDN:

javascript_include_tag 'https://cdnjs.cloudflare.com/ajax/libs/jquery/3.6.0/jquery.min.js',
  integrity: "sha512-894YE6QWD5I59HgZOGReFYm4dnWc1Qt5NtvYSaNcOP+u1T9qYdvdihz0PPSiiqn/+/3e7Jo4EaG7TubfWGUrMQ==",
  crossorigin: "anonymous", referrerpolicy: "no-referrer"

So that's what the other config is about. It replaces any mention of jQuery with a little module that just imports an export default of window.jQuery instead of inlining jQuery. It means other non-module scripts in the head of your page will have jQuery available at page load.

[krsyoung]

Hey @brendon I ended up doing the same for bootstrap-daterangepicker after many hours of trying to do it the "right" way, just converted to ESM (I barely understand what I'm doing, but works great now!).

Huge thanks for the tips. I'm going to keep grinding. Believe it or not, after messaging you I ran a production esbuild and "it worked". Granted iQuery went missing in the actual browser console but progress! The secret was to restart my docker container 😕 I have a feeling my vite container is being overly helpful with the main app container.

I'm going through some JavaScript hoisting activities at the moment to see if I can get that to work. We unfortunately can't use CDNs, but it is a great reference for others and future projects.

At this point I really wonder if it wouldn't have been more productive to just remove the legacy dependencies and pick those with native ESM support! Ok back to it ... 🤞

[brendon]

Nice to hear that @krsyoung! :) I had to replace a date range picker and found https://easepick.com

It works really well and no dependencies either :)

An alternative to CDN jQuery would be to just import jQuery itself via something like jquery-rails. If you don't need jQuery outside of your module space then importing it where needed can work too :)

[krsyoung]

Great suggestion on easepick @brendon. We'll need to start moving over to more ESM friendly packages going forward. The project looks great!

Also, big thanks for the help and the idea & confidence to move with esbuild-only. Friday started with despair and ended with a win thanks to this thread. ❤️

We successfully deployed to production last night and everything went beautifully! I need to come back on our lessons learned (there were many!) as I know I'll forget most of it by the end of the week. We made it the last mile by getting our JavaScript hoisting in order.

I also blew it by somewhere reading that the Rails.start() was no longer needed for @rails/ujs when using import. It was not the case and made it very clear that we use data: remote a lot! (whoops)

🚀 Happy Weekend 🚀

[brendon]

Oh yea! The Rails.start() thing wasn't required (actually didn't work) when using the rollup/common-js approach. Actually, before webpack was in use it also used to 'auto-boot'. The way webpack wrapped things meant that that code path wasn't triggered anymore so had to be called manually. We were making some modifications to rails-ujs before booting it, so that was convenient. In my efforts to try and get rollup to work I ended up removing all our modifications, then I forgot to add back Rails.start() when reverting to esbuild. Wondered why all the confirmations weren't working! :D

Glad you got there in the end. Definitely share your learnings here, there's relatively little out there for a complicated conversion!

[brendon]

If you use capistrano and have yarn installed, Rails will run yarn install for every deploy anyway, so you can prevent the Vite-ruby gem from also running yarn install again by adding this file to /lib/tasks/vite.rake:

namespace :vite do
  task(:install_dependencies).clear
end

I also had to add public/vite to :linked_dirs in deploy.rb so that the assets aren't obliterated on each deploy since new assets won't be generated if your source files haven't changed. If you set :keep_assets the vite-ruby gem will also clean up older versions of assets as part of this hook which is cool.

[jrochkind]

Weirdly, the stuff you document around "@" did not seem to be necessary to me...

With

app
   frontend
      application.js
      javascript
         foo.js

application.js was able to do an import 'javascript/foo.js' and it just worked. With that relative path like that. No need for @/, and no need for defining aliases like suggested in the accompanying article. It just worked.

Why is this working for me if it "shouldn't"? Have vite or vite-ruby changed since this was written? Or am I doing something "fragile" in any way?

[krsyoung]

@jrochkind If it is fragile, then I'm in the same boat. I didn't include any special @ references for my imports / uplifting (all 300 of them!) when doing something similar to you.

[krsyoung]

Scratch that, I lied. I've been using all relative paths. Does seem like it could collide with node_modules.

console.log('Vite ⚡️ Rails')

import '../hoist/jquery'
import '../hoist/rails'
import '../hoist/turbolinks'
...

[brendon]

Hehe :)

[brendon]

That's pretty interesting. I've been using ~/. I guess it potential collisions with node_modules?