This section lists a few common gotchas, and bugs introduced in the past.

Please skim through before opening an issue.

Upgrading to v3 and now assets are failing to resolve

It's likely that you have a nested directory structure under entrypointsDir.

See the Migrating from v2 section for more information.

Assets inside sourceCodeDir are being bundled

This is the default behavior in v3, which simplifies referencing images and icons using tag helpers.

You can opt out by configuring additionalEntrypoints, see Advanced Usage.

Missing executable error

Verify that both vite and vite-plugin-ruby are in devDependencies in your package.json and have been installed by running bin/vite info.

If you are using a non-standard setup, try configuring viteBinPath.

Hot Module Refresh does not work for React

When using @vitejs/plugin-react in non-HTML entrypoints, you must explicitly register the HMR plugin.

A vite_react_refresh_tag helper is provided for your convenience:

  <%= vite_client_tag %>
  <%= vite_react_refresh_tag %>
  <%= vite_javascript_tag 'application' %>

Making HMR work in Docker Compose

Using Vite.js with Docker Compose requires configuring VITE_RUBY_HOST in the services.

In the Rails service, it should match the name of your Vite service, and in the Vite service it should be set to receive external requests (from the browser in the host) in order to perform HMR.

Refer to this Docker example for a working setup.

Build not working in CI or Heroku

Make sure devDependencies are installed when precompiling assets in a CI.

Refer to the Using Heroku section.

Build is triggered when the dev server is running

First, verify that the dev server is reachable by starting a new console session and running:

> ViteRuby.instance.dev_server_running?

If it returns false, try increasing the devServerConnectTimeout, restart the console and retry. In systems with constrained resources the default timeout might not be enough.

If that doesn't work, verify that the host and port configuration is correct.

Requests to vite refuse to connect for ::1

In systems where localhost defaults to ::1 it might be necessary to configure host to explicitly use, since that's what Vite uses by default.

  "development": {
    "host": "",
    "port": 3036,

Requests to vite sporadically return a 404 error response

See above, it could be related to the devServerConnectTimeout.

Requests to vite sporadically return a 500 error response

Check your ulimit -n to make sure the limit of file descriptors is not too low.

This is probably the case if you are seeing errors such as #<Errno::EMFILE: Too many open files along with #<SocketError: Failed to open TCP connection.

Follow this article for information on how to increase the limit of file descriptors in your OS.

Changes are not taken into account, build is skipped

Usually happens when importing code outside the sourceCodeDir.

Add a file path or dir glob in watchAdditionalPaths to ensure changes to those files trigger a new build.

vite and vite-plugin-ruby were not installed

If you have run bundle exec vite install, check the output for errors.

Tailwind CSS is slow to load

A project called Windi CSS addresses this pain point − I've created a documentation website.

A plugin for Vite.js is available, and should allow you to get insanely faster load times in comparison.

Check the Recommended Plugins section for more information.

Windi CSS does not detect changes to server templates

Ensure you're using vite-plugin-windicss@0.9.5 or higher.

Check the Recommended Plugins section for more information.

esbuild: cannot execute binary file

This can happen when using mounted volumes in Docker, and attempting to run Vite from the host, or installing dependencies in the host and then trying to run Vite in the container.

Since esbuild relies on a postinstall script, and the architecture of the host usually does not match the architecture of the image, this means the binaries are not compatible.

Try reinstalling esbuild in the host or container—depending on where you intend to run it—to ensure it's built for the corresponding system architecture.

Contact ✉️

Please visit GitHub Issues to report bugs you find, and GitHub Discussions to make feature requests, or to get help.

Don't hesitate to ⭐️ star the project if you find it useful!

Using it in production? Always love to hear about it! 😃