Ruby and Rails glossary

vite_rails

vite_rails is a Ruby gem that lets a Rails app build its JavaScript and CSS with Vite, with hot module replacement in development and a vite build run by assets:precompile in production.

vite_rails is a Ruby gem that lets a Rails app build its JavaScript and CSS with Vite. In development your pages load modules straight from the Vite dev server, so edits show up in the browser through hot module replacement. In production assets:precompile runs vite build and the gem's tag helpers point your layout at the fingerprinted files listed in Vite's manifest. Máximo Mussini maintains it in the ElMassimo/vite_ruby repository.

How the pieces fit

The project has three parts. vite_ruby is the engine. It reads config/vite.json, starts and talks to the Vite dev server, runs builds, and resolves entrypoints from the manifest. It works with any Rack app. vite_rails is the Rails integration on top of it. It adds a Railtie, the vite_*_tag helpers for your views, and an installer that knows the usual Rails layout. The third piece is the npm package vite-plugin-ruby, which reads the same config/vite.json from the Vite side, so Ruby and Node agree on paths and ports.

Versions, checked in November 2026:

  • vite_rails 3.11.1, released July 2026. It requires railties >= 5.1, < 9, so it covers Rails 5.1 through 8.1.
  • vite_ruby 3.11.1, released September 2026.
  • vite-plugin-ruby 5.2.6, released October 2026. Its peer dependency is vite >= 5.0.0.
  • A fresh install adds vite@^8.0.0 and vite-plugin-ruby@^5.2.5.

If you run Vite 8.1 or newer, use vite-plugin-ruby 5.2.6 or later. Releases 5.2.3 and 5.2.6 fixed the HMR client port on Vite 8.1+. bundle exec vite upgrade updates the gems and the npm packages together. When vite_ruby loads its config it checks the installed plugin version and raises an error if it doesn't match.

Installing it

Add the gem and run the installer:

# Gemfile
gem "vite_rails"
bundle install
bundle exec vite install

The installer creates bin/vite, vite.config.ts, config/vite.json and a sample entrypoint. It installs vite and vite-plugin-ruby as dev dependencies, adds two lines to Procfile.dev, adds /public/vite* to .gitignore, and injects vite_client_tag and vite_javascript_tag before </head> in app/views/layouts/application.html.erb. If your app already has app/javascript, as new Rails 7 and 8 apps do, the installer sets that as the source directory instead of app/frontend.

The generated Vite config is short:

// vite.config.ts
import { defineConfig } from 'vite'
import RubyPlugin from 'vite-plugin-ruby'

export default defineConfig({
  plugins: [
    RubyPlugin(),
  ],
})

The Ruby side of the configuration lives in config/vite.json:

{
  "all": {
    "sourceCodeDir": "app/frontend",
    "entrypointsDir": "entrypoints",
    "watchAdditionalPaths": []
  },
  "development": {
    "autoBuild": true,
    "skipProxy": true,
    "publicOutputDir": "vite-dev",
    "port": 3036
  },
  "test": {
    "autoBuild": true,
    "publicOutputDir": "vite-test",
    "port": 3037
  }
}

entrypointsDir defaults to entrypoints, so you can leave it out. Every file in app/frontend/entrypoints becomes a separate bundle. Everything else under app/frontend is code those entrypoints import. Imports can start with ~/ or @/, which both point at sourceCodeDir.

skipProxy: true has been the default for new installs since vite_rails 3.11.0 (May 2026). The browser then fetches modules from localhost:3036 directly instead of through a Rack proxy inside Rails. If your app sets a Content Security Policy, the installer leaves commented-out rules in config/initializers/content_security_policy.rb that allow the dev server's host and its websocket. Uncomment them for development.

The layout

<!-- app/views/layouts/application.html.erb -->
<head>
  <%= csrf_meta_tags %>
  <%= csp_meta_tag %>
  <%= vite_client_tag %>
  <%= vite_javascript_tag "application" %>
  <%= vite_stylesheet_tag "typography" %>
</head>

vite_client_tag loads Vite's HMR client in development and renders nothing when no dev server is running, so it is safe to leave in production. vite_javascript_tag "application" renders the module script, modulepreload links for the chunks it imports, and <link> tags for any CSS the entrypoint imports. Use vite_stylesheet_tag only for a standalone stylesheet entrypoint, here app/frontend/entrypoints/typography.css. For a TypeScript entrypoint use vite_typescript_tag "application". For .jsx or .tsx give the extension, as in vite_javascript_tag "application.tsx".

An entrypoint with Stimulus

Vite's import.meta.glob replaces the controller index file that importmap and esbuild setups keep by hand. Install the helpers first with npm add @hotwired/turbo-rails @hotwired/stimulus stimulus-vite-helpers, then:

// app/frontend/entrypoints/application.js
import "@hotwired/turbo-rails"
import { Application } from "@hotwired/stimulus"
import { registerControllers } from "stimulus-vite-helpers"

const application = Application.start()
const controllers = import.meta.glob("../controllers/**/*_controller.js", { eager: true })
registerControllers(application, controllers)

A file at app/frontend/controllers/date_picker_controller.js registers as date-picker. Add a controller file and it is picked up on the next reload, with no index to update.

For HMR on Stimulus controllers, the vite-ruby docs point to vite-plugin-stimulus-hmr. Its last npm release is 3.0.0, from January 2022. The repository is not archived and saw a commit in March 2026. Without it, editing a controller triggers a full page reload, which most Hotwire apps can live with.

Running it in development

# Procfile.dev
web: bin/rails server
vite: bin/vite dev

bin/dev starts both through foreman or overmind. The Vite dev server serves source files as native ES modules and pushes changes over a websocket, so a CSS edit applies in place without a reload. If you skip the dev server, autoBuild: true makes Rails run a Vite build on the next request that needs a changed asset. That is slower per change, but it is why the test environment works without a dev server.

Building for production

vite_ruby extends assets:precompile. When that task runs, it first installs JavaScript dependencies (npm ci, or yarn install --frozen-lockfile and its equivalents), then runs vite build. Your existing deploy step stays the same:

RAILS_ENV=production bin/rails assets:precompile

The output lands in public/vite with content-hashed filenames and a manifest the tag helpers read at runtime. Vite splits code shared between entrypoints and dynamic import() calls into separate chunks. Since Vite 8 (March 2026) the production bundler is Rolldown, which replaced Rollup. Parts of the vite-ruby docs still say Rollup. Set VITE_RUBY_SKIP_ASSETS_PRECOMPILE_INSTALL=true if your build already installs node modules, or VITE_RUBY_SKIP_ASSETS_PRECOMPILE_EXTENSION=true to stop the hook entirely and run bin/vite build yourself.

Using it alongside Propshaft

Rails 8 ships Propshaft, and vite_rails does not replace it. Vite writes to public/vite with its own manifest, and the vite_* helpers resolve paths through that manifest, so Propshaft keeps serving app/assets through stylesheet_link_tag and image_tag as before. assets:precompile runs Propshaft's step and then Vite's. The usual split is images, fonts and plain CSS in Propshaft, and everything that needs bundling or HMR in Vite. You can also move it all into Vite, since files under app/frontend/{assets,fonts,icons,images} count as entrypoints for vite_asset_path and vite_image_tag. The vite-ruby docs do not discuss Propshaft. This section comes from reading the gem's source.

When not to use it

A Hotwire app with a few Stimulus controllers and no build step needs is better off on importmap-rails, the Rails default, which has no Node dependency at all. If you need a bundler but not a dev server, jsbundling-rails with esbuild is lighter and has fewer moving parts. vite_rails is worth the extra setup when you write React, Vue, Svelte or TypeScript, or when you want CSS and component edits to show up without a page reload.

Summary

vite_rails connects a Rails app to Vite, with vite_ruby doing the work underneath and vite-plugin-ruby sharing its config with Node. You get HMR in development and vite build through the assets:precompile you already run. On Vite 8 that build uses Rolldown, and vite_rails sits next to Propshaft rather than replacing it. Avo, the Rails admin framework that publishes this glossary, ships its own compiled JavaScript and CSS, so it mounts in a vite_rails app without being part of your Vite build.

Try Avo for free