Vite Rails Plugin

0.6.0 verified Mon Apr 27 auth: no javascript

vite-plugin-rails v0.6.0 is a Vite plugin that brings convention over configuration to Rails projects, bundling several commonly needed plugins (Ruby integration, gzip/brotli compression, environment variable exposure, full reload on template changes, Stimulus HMR, and SRI manifest hashing) with zero-config defaults while remaining fully configurable. Unlike the minimal vite-plugin-ruby, this plugin provides an opinionated, batteries-included setup for Rails developers. Released under MIT license, maintained by ElMassimo as part of the vite_ruby ecosystem. Requires Vite >=5.0.0.

Common errors

error Cannot find module 'vite-plugin-rails' or its corresponding type declarations. ↓

cause Package not installed or missing from node_modules.

fix

Run npm install vite-plugin-rails --save-dev (or yarn) and ensure package.json includes it.

error Error: [vite] Internal server error: The plugin 'vite-plugin-rails' requires Vite version >=5.0.0. Current version: 4.x ↓

cause Installed Vite version is too old.

fix

Upgrade Vite to version 5.0.0 or newer.

error TypeError: Cannot read properties of undefined (reading 'gzip') ↓

cause Passed invalid options object (e.g., undefined or malformed).

fix

Ensure options object is properly formatted; for example, set compress: { gzip: true, brotli: false }.

error UnhandledPromiseRejectionWarning: Error: No manifest.json found. ↓

cause SRI plugin expects manifest to be generated by Vite build but it's missing.

fix

Ensure build is run with the plugin; check if vite build completes and manifest.json is produced.

error Dynamic require of 'vite-plugin-rails' is not supported ↓

cause Using CommonJS require() instead of ESM import.

fix

Switch to import ViteRails from 'vite-plugin-rails' and ensure your project uses ESM (type: module in package.json).

Warnings

breaking Upgrading from vite-plugin-ruby (without the -rails suffix) requires switching to the new package name and updated API. ↓

fix Replace import from 'vite-plugin-ruby' to 'vite-plugin-rails'; adjust options to match the new config shape.

breaking vite-plugin-rails v0.6.0 requires Vite >=5.0.0; older Vite versions are incompatible. ↓

fix Update Vite to version 5.0.0 or higher.

deprecated The plugin may deprecate or remove old option keys; always check the latest configuration options source. ↓

fix Refer to the latest src/index.ts for valid options.

gotcha External plugins like rollup-plugin-gzip and vite-plugin-full-reload are bundled by default; do not install them separately or duplicate them in plugins array. ↓

fix Use plugin options to configure bundled plugins; pass `compress: false` to disable completely.

gotcha The default fullReload paths may trigger unnecessary full page reloads on certain file changes if custom caching is used. ↓

fix Set `fullReload: { additionalPaths: [] }` or configure to match your exact template patterns.

Install

npm install vite-plugin-rails

yarn add vite-plugin-rails

pnpm add vite-plugin-rails

Imports

ViteRails
wrong
```
const ViteRails = require('vite-plugin-rails')
```
correct
```
import ViteRails from 'vite-plugin-rails'
```
Default import; the plugin ships TypeScript types. ESM only; CJS require will cause error at runtime.
type ViteRailsOptions
```
import type { ViteRailsOptions } from 'vite-plugin-rails'
```
The package exports a `ViteRailsOptions` interface for configuring the plugin in TypeScript.
default
wrong
```
import { ViteRailsPlugin } from 'vite-plugin-rails'
```
correct
```
import ViteRailsPlugin from 'vite-plugin-rails'
```
The package has a default export; named export `ViteRailsPlugin` does not exist. Use default import.

Quickstart

Registers the plugin with Vite config, showing optional compression, environment variables, full reload paths, and Stimulus HMR configuration.

import { defineConfig } from 'vite';
import ViteRails from 'vite-plugin-rails';

export default defineConfig({
  plugins: [
    ViteRails({
      compress: { gzip: true, brotli: false },
      envVars: { RAILS_ENV: process.env.RAILS_ENV ?? 'development' },
      fullReload: { additionalPaths: ['app/serializers/**/*'] },
      stimulus: { controllersPath: 'app/assets/controllers' }
    })
  ]
});