Rails Vite Plugin

0.2.4 verified Mon Apr 27 auth: no javascript

A Vite plugin for integrating Vite into Ruby on Rails applications, currently at stable version 0.2.4. It provides seamless asset pipeline integration with both Propshaft and Sprockets, supports SSR, glob patterns for entry points, and works with jsbundling-rails. Regular releases (approximately monthly) with active maintenance. Key differentiators: lightweight, no gem required in jsbundling mode, automatic entry point discovery, subresource integrity, and test mode isolation. Requires Vite >= 5.0.0 and Node >= 18.

Common errors

error Error: ERR_REQUIRE_ESM - require() of ES Module /path/to/rails-vite-plugin/index.js not supported. ↓

cause Using CommonJS require() on an ESM-only package.

fix

Change to import statement: import rails from 'rails-vite-plugin'. Ensure your project uses ESM (type: module in package.json) or use dynamic import() if needed.

error [vite] RollupError: Could not resolve entry point 'app/javascript/entrypoints/application.js' - entry paths must be relative or absolute. ↓

cause Entry point path is not properly resolved; plugin expects relative paths from sourceDir.

fix

Use a relative path like './entrypoints/application.js' or ensure sourceDir and entrypoints config are correct.

error TypeError: Cannot destructure property 'version' of 'rails is not a function' ↓

cause Using rails() as a function but it's not imported correctly (e.g., default import not used).

fix

Ensure you do import rails from 'rails-vite-plugin' and then rails({...}) in plugins array.

error Module not found: Error: Can't resolve 'vite' in ... when using rails-vite-plugin ↓

cause Missing peer dependency 'vite'.

fix

Install vite: npm install vite --save-dev or yarn add vite --dev.

Warnings

gotcha ESM-only package: CommonJS require() will fail. ↓

fix Use ES module import syntax instead of require().

breaking In v0.2.0, jsbundling mode was introduced, which changes default behavior and may require configuration updates. ↓

fix Check the jsbundling mode documentation; if using jsbundling-rails, ensure you follow the correct setup.

deprecated The old `vite_rails` gem integration is deprecated; use the standalone plugin or jsbundling mode. ↓

fix Migrate to jsbundling mode (no gem) or use the gem with updated config.

gotcha Node >= 18 is required; older versions are not supported. ↓

fix Upgrade Node.js to version 18 or higher.

gotcha In development mode, asset URLs may incorrectly point to Rails server instead of Vite dev server (fixed in v0.2.1). ↓

fix Upgrade to v0.2.1 or later.

Install

npm install rails-vite-plugin

yarn add rails-vite-plugin

pnpm add rails-vite-plugin

Imports

default

wrong

const rails = require('rails-vite-plugin')

correct

import rails from 'rails-vite-plugin'

ESM-only package; CommonJS require is not supported.

RailsPluginOptions

wrong

import { RailsPluginOptions } from 'rails-vite-plugin'

correct

import type { RailsPluginOptions } from 'rails-vite-plugin'

Type-only import; if used at runtime, remove 'type'.

default (named alias)

wrong

import rails from 'rails-vite-plugin'; // This is correct, but named default is also possible.

correct

import { default as rails } from 'rails-vite-plugin'

Both default import and named default work.

Quickstart

Configures Vite with the Rails plugin, specifying source directory and entry points.

// vite.config.ts
import { defineConfig } from 'vite';
import rails from 'rails-vite-plugin';

export default defineConfig({
  plugins: [
    rails({
      version: '0.2.4',
      sourceDir: 'app/javascript',
      entrypoints: 'app/javascript/entrypoints',
      publicDir: 'public/vite',
      envDir: undefined,
      // Optional: for SSR
      ssrBuildDirectory: 'public/vite-ssr',
    }),
  ],
});