# 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:

```ruby
# Gemfile
gem "vite_rails"
```

```bash
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:

```ts
// 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`:

```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

```erb
<!-- 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:

```js
// 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:

```bash
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](https://avohq.io/glossary/importmap-rails), the Rails default, which has no Node dependency at all. If you need a bundler but not a dev server, [jsbundling-rails](https://avohq.io/glossary/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](https://avohq.io/rails-admin) 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.
