DEV Community

Cover image for How to migrate from webpacker to jsbundling-rails (esbuild)

Posted on • Updated on

How to migrate from webpacker to jsbundling-rails (esbuild)

  1. Install jsbundling-rails
  2. Swap pack_tag for include_tag
  3. Import stimulus controllers
  4. Migrate JS entrypoint
  5. Remove webpack
  6. Github Actions
  7. Heroku

1. Install jsbundling-rails

Add to gemfile:

gem 'jsbundling-rails'
Enter fullscreen mode Exit fullscreen mode

In the terminal, run:

bundle install
rails javascript:install:esbuild
Enter fullscreen mode Exit fullscreen mode

2. Swap pack_tag for include_tag

The jsbundling:install command inserts a javascript_include_tag tag above the tag in your application.html.erb file. This tag wil include the new javascript entrypoint javascript/application.js for your build script to be included in your application.

Remove webpack's legacy stylesheet_pack_tag:

# old
<%= javascript_pack_tag 'application', 'data-turbo-track': 'reload' %>

# new
<%= javascript_include_tag "application", "data-turbo-track": "reload", defer: true %>
Enter fullscreen mode Exit fullscreen mode

If your app render multiple layouts, be sure to remove any javascript_pack_tag there too.

3. Import stimulus controllers

Even when you already installed stimulus, run the install command again in your terminal and overwrite any confliction changes. This will import all your existing stimulus controller correctly.

rails stimulus:install
Enter fullscreen mode Exit fullscreen mode

Now, after adding or removing a new stimulus controller you can use a command which will auto-generate the controllers/index.js file.

rails stimulus:manifest:update
Enter fullscreen mode Exit fullscreen mode

4. Migrate JS entrypoint

Move the content from javascript/packs/application.js to
javascript/application.js. After migrating the file, delete the javascript/packs folder which was used by Webpacker.

Make sure to import directories in the javascript folder with a relative path.

// old

import "./channels"
import "./controllers"
Enter fullscreen mode Exit fullscreen mode

5. Remove webpack

Webpack and its tentacles can finally be removed from the application.

A. Remove webpacker gem

gem 'webpacker', '~> 5.4'
Enter fullscreen mode Exit fullscreen mode

B. Remove webpack packages

Webpack packages and plugins that accumulated over time can be removed too. For me, this included:

  • @rails/webpacker
  • webpack
  • webpack-cli
  • webpack-cli/serve
  • webpack-dev-server
  • clean-webpack-plugin
  • @hotwired/stimulus-webpack-helpers

C. Remove webpack files

Finally, remove all config and start-up files:

  • bin/webpack
  • bin/webpack-dev-server
  • config/webpacker.yml
  • config/webpack (directory)

6. Github Actions

If you use Github Actions as a CI/CD make sure to add in an additional build step to run yarn build. Yarn build will trigger the build step defined in your package.json file: "build": "esbuild app/javascript/*.* --bundle --outdir=app/assets/builds". All javascript files need to be bundled before running the tests in your workflow file.

- name: Build Esbuild
  run: yarn build
Enter fullscreen mode Exit fullscreen mode

7. Heroku

UPDATE this is step is redundant now as mentioned by @jrochkind in the comments. See

If you use heroku to deploy your application, Heroku will NOT automatically install yarn as it does for Webpack!**

Therefore, we need to explicitly set a node buildpack before ruby. You can do this in the terminal or the Heroku Dashboard.

  • Terminal
heroku buildpacks:clear
heroku buildpacks:set heroku/nodejs
heroku buildpacks:add heroku/ruby
Enter fullscreen mode Exit fullscreen mode
  • Dashboard Heroku Dashboard


Top comments (4)

blarsamio profile image

Hi! After migrating my project from webpacker to jsbundling through esbuild I keep getting this error on my console : Uncaught DOMException: Failed to execute 'define' on 'CustomElementRegistry': the name "turbo-frame" has already been used with this registry... I believe Turbo is loading twice. Any clues on how to fix this?

jrochkind profile image
Jonathan Rochkind

Heroku seems to have solved this problem, no longer necessary or recommended to add the nodejs buildpack.

thomasvanholder profile image

Great, thanks for informing. I'll update it in the article.

notapatch profile image
not-a-patch • Edited

Ignore this comment: I'm trying to understand when/if it updates package.json