vite-plugin-ruby

5.2.1 verified Sat Apr 25 auth: no javascript

A Vite plugin that provides convention-over-configuration integration for Ruby projects, primarily used with Rails, Hanami, or plain Ruby via the vite_ruby gem. Current stable version is 5.2.1. It is updated regularly alongside the vite_ruby ecosystem. Unlike generic Vite setups, it auto-discovers entry points, handles asset paths, and bridges Vite's HMR with Ruby development servers. Ships TypeScript types. Requires Vite >=5.0.0.

Common errors

error Error: Cannot find module 'vite-plugin-ruby' ↓

cause The package is not installed or the path is incorrect.

fix

Run npm install vite-plugin-ruby or yarn add vite-plugin-ruby.

error export 'ViteRuby' (imported as 'ViteRuby') was not found in 'vite-plugin-ruby' ↓

cause Attempting named import instead of default import.

fix

Change to: import ViteRuby from 'vite-plugin-ruby'

error TypeError: ViteRuby is not a function ↓

cause Accidentally imported the default as an object or used wrong import style.

fix

Ensure you import the default and call it as a function: import ViteRuby from 'vite-plugin-ruby'; ViteRuby()

Warnings

breaking In v5, the plugin no longer automatically resolves the entry point from config/vite.json if missing; you must explicitly define entry points in vite.json or via plugin options. ↓

fix Ensure your config/vite.json has a 'source_code_dir' and 'entry_points' defined, or pass them in the plugin options.

deprecated Support for Node.js 14 and 16 is deprecated as of v5. Future versions may require Node 18+. ↓

fix Upgrade to Node.js 18 or later.

gotcha The plugin assumes a specific directory structure (e.g., app/frontend/entrypoints). If your project does not follow the convention, you must configure it explicitly. ↓

fix Set custom paths in vite.json under 'source_code_dir' and 'entry_points'.

gotcha HMR may not work correctly if the Ruby server (e.g., Rails) is not configured to proxy Vite's WebSocket. The vite_ruby gem must be properly set up. ↓

fix Follow the setup guide of vite_ruby to add the ViteRuby middleware in your Rails config.

Install

npm install vite-plugin-ruby

yarn add vite-plugin-ruby

pnpm add vite-plugin-ruby

Imports

default (ViteRuby)
wrong
```
const { ViteRuby } = require('vite-plugin-ruby')
```
correct
```
import ViteRuby from 'vite-plugin-ruby'
```
The plugin exports a default function. Named export does not exist. CommonJS require is supported but the default import style is preferred.
ViteRuby (named import attempt)
wrong
```
import { ViteRuby } from 'vite-plugin-ruby'
```
correct
```
import ViteRuby from 'vite-plugin-ruby'
```
There is no named export 'ViteRuby'; only default export. Using curly braces will result in undefined.
type (TypeScript)
wrong
```
import type ViteRuby from 'vite-plugin-ruby'
```
correct
```
import ViteRuby from 'vite-plugin-ruby'
```
If you need the type of the plugin instance, import the default. The package does not export a separate type.

Quickstart

Basic setup of vite-plugin-ruby in vite.config.ts. Instantiates the plugin without options, relying on convention-based defaults.

import { defineConfig } from 'vite'
import ViteRuby from 'vite-plugin-ruby'

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