Overview

This section provides a high-level overview of how this library interacts with Rails and Vite.js, and is intended for users that would like to know more about the internals of the library.

For usage instructions, please refer to the guide instead.

Rack and Rails

The following conventions are common in Rack-based applications:

  • The public directory contains static and compiled assets, and will be exposed as-is.

  • rake assets:precompile will process CSS and JS files in the project, and write the result in a subdirectory under public.

Vite.js

In production, Vite.js will bundle assets for efficiency and write the result to an output directory—just like webpack or the assets pipeline.

The main difference is that in development it will leverage native ESM to transform and serve source on demand, as the browser requests it. Any code that is not imported in the current page will not be processed nor served.

Vite Ruby

This library consists of two main components:

Vite.js and the plugin are used during development and deployment, but not once an application is live in production. In contrast, the gem is used in production as well.

In Development

When the Vite development server is running, Vite Ruby will proxy requests to it allowing files to be processed and served on demand.

No files are written to the public directory.

Instant Updates ⚡️

When using vite_client_tag, the browser will establish a WebSocket connection with the Vite development server in order to receive notifications whenever a module has been invalidated and should be re-fetched (usually when the user edits the source code).

In Production

Vite Ruby extends assets:precompile to perform a Vite.js build— processed assets are placed inside the public folder.

The build also generates a manifest with metadata which allows to map the original file names to their fingerprinted equivalent in the bundle, and specifies other dependencies such as stylesheets or nested imports.

This metadata is used by Vite Ruby in tag helpers to map file names when rendering URLs, and render additional link tags.

The resulting URLs will correspond to files in the public directory, which may be served by the web application or by a CDN.

Auto-Build

If Vite is not running, Vite Ruby can detect if files have changed and rebuild as needed.

The resulting fingerprinted assets are then served from public, just as in production.

This mode is typically used during CI, as the source code will not be modified and fast updates are not a concern.