Troubleshooting #

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

Please skim through before opening an issue.

Installation Problems #

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.

Your bin/bundle was not generated by Bundler #

It's likely that your bin/bundle was generated by an older version of bundler than the one you are running now (and was used to generate bin/vite).

Running bundle binstubs bundler --force might not be desirable. If it works, great! If not, you will want to run bundle config --delete bin afterwards to avoid binstubs from being generated for all gems with executables.

As an alternative, try removing the check for the message in bin/vite, or run bundle exec vite instead.

Double installation on deployment #

Package managers like npm, pnpm, and yarn will quickly skip installation when packages have already been installed, so double installation would only happen in scenarios like:

npm ci
# later
NPM_CONFIG_INCLUDE="dev" npm ci

If you see a double installation in the deployment logs, check that you have configured your deployment to avoid pruning any development dependencies before compiling assets.

Common Problems #

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.

No Vite Ruby output in tests even though it's building #

Vite Ruby uses the Rails logger when available, which in the test environment usually outputs to a log/test.log file instead of $stdout as in development.

To see the output when running integration tests, you can manually assign a logger in spec_helper.rb or a similar file that is only loaded in the test environment.

Can't reference style.css when using cssCodeSplit: false #

As covered in the tag helpers section:

All helpers resolve names to the entrypointsDir unless the path includes a directory

Use the ~/ alias to the sourceCodeDir to disambiguate the reference:

<%= vite_stylesheet_tag '~/style.css' unless ViteRuby.instance.dev_server_running? %>

The CJS build of Vite's Node API is deprecated #

Please refer to Vite's troubleshooting guide.

You might need to add "type": "module" to your package.json, or rename vite.config.ts to vite.config.mts.

HMR Issues #

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 with puma-dev in HTTPS apps #

When running the Ruby server in HTTPS mode, you'll want the Vite HMR client to also connect via HTTPS to avoid Mixed content errors.

You can configure puma-dev to run in HTTPS mode while keeping Vite running in plain HTTP mode. See this discussion for configuration steps.

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, or read this article for a full walkthrough.

Network Issues #

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 127.0.0.1, since that's what Vite uses by default.

  "development": {
    "host": "127.0.0.1",
    "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.

Safari does not reflect CSS and JS changes in development #

Safari ignores the Cache-Control: no-cache header for preloaded CSS and JS files, which is inconvenient in development as HMR does not work as expected, requiring the cache to be cleared manually in order to see changes.

By default, Rails javascript and stylesheet tag helpers cause a Link: ... rel=preload header to be emitted, which triggers the Safari bug. As a workaround, you can disable the preload behavior in development as follows:

# config/environments/development.rb

Rails.application.configure do
  # Disable `Link: ... rel=preload` header to workaround Safari caching bug
  # https://bugs.webkit.org/show_bug.cgi?id=193533
  config.action_view.preload_links_header = false
end

With preloading disabled, Safari will properly refresh changed files and HMR will work.

Fixed Issues #

Build not working in CI or Heroku #

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

Refer to the Using Heroku section.

vite and vite-plugin-ruby were not installed #

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

Asset names can not be relative ../../vite/legacy-polyfills #

Make sure to upgrade vite_plugin_legacy manually with a compatible version of vite_ruby.

The upgrade command has now been fixed to also upgrade vite_plugin_legacy.

Upgrading to V3 #

Assets are failing to resolve after upgrade #

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.

Other Libraries #

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.

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.

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.

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! 😃