Vite Ruby
Return to top
On this page

Developing with Vite

In this section, we'll cover the basics to get started with Vite in Ruby web apps.

Development Server 💻

Run bin/vite dev to start a Vite development server.

It will use your config/vite.json configuration, which can be used to configure the host and port, as well as other options.

Entrypoints ⤵️

Any files inside your entrypointsDir will be considered entries to your application (SPAs or pages), and will be bundled by Vite.

app/frontend: sourceCodeDir
  ├── entrypoints: entrypointsDir
  │   # only Vite entry files here
  │   │── application.js
  │   └── typography.css
  │── components:
  │   └── App.vue
  │── channels:
  │   │── index.js
  │   └── chat.js
  │── stylesheets:
  │   └── my_styles.css
  └── images:
      └── logo.svg

These files will be automatically detected and passed on to Vite, all configuration is done for you.

You can add them to your HTML layouts or views using the provided tag helpers.

Additional Entrypoints

By default, files inside ~/{assets,fonts,icons,images}/**/* are also bundled as entrypoints, allowing you to reference them in tag helpers.

Use additionalEntrypoints to configure entrypoints manually.

Import Aliases 👉

For convenience, ~/ and @/ are aliased to your sourceCodeDir, which simplifies imports:

import App from '~/components/App.vue'
import '@/channels/index.js'

When importing files outside your sourceCodeDir, make sure to check watchAdditionalPaths.

Stylesheets 🎨

Vite provides great support for CSS, supporting PostCSS out of the box, and built-in support for preprocessors like Sass.

In Vite Ruby the most common ways to add styles are:

Auto-Build 🤖

Even when not running the Vite development server, Vite Ruby can detect if any assets have changed in sourceCodeDir, and trigger a build automatically when the asset is requested.

This is very convenient when running integration tests, or when a developer does not want to start the Vite development server (at the expense of a slower feedback loop).

Enabled locally

By default, autoBuild is enabled in the test and development environments.

CLI Commands ⌨️

A CLI tool is provided, you can run it using bundle exec vite, or bin/vite after installation.

For information about the CLI options run bin/vite command --help.

  • bundle exec vite install: Install configuration files and sample setup for your web app

  • bin/vite dev: Starts the Vite development server

  • bin/vite build: Makes a production bundle with Vite using Rollup behind the scenes

  • bin/vite upgrade: Updates Vite Ruby gems and npm packages to compatible versions

  • bin/vite info: Provide information on Vite Ruby and related libraries

  • bin/vite clobber: Clears the Vite cache, temp files, and builds.

    Also available through the --clear flag in the dev and build commands.

Environment-aware

All these commands are aware of the environment. When running them locally in development you can pass --mode production to simulate a production build.

Tag Helpers 🏷

Tag helpers are provided in the framework-specific integrations:

HMR for Integration Tests ✅

When iterating on integration tests locally, you can avoid rebuilds by starting an additional Vite dev server for tests with bin/vite dev --mode=test.

To reuse the same Vite dev server from development, you can configure publicOutputDir and port in test to match the development config.

Intended for quick iteration

The trade-off is that your app might not even build correctly.

It's safe if you are running tests in a CI as it will build in production mode.

When running tests locally, you can test the production build by not starting the Vite dev server for tests, or by setting the CI environment variable.

Integration Tests in the CI ✅

When running tests in the CI, it's more reliable if assets are available before tests start to run, as it:

  • Prevents timeouts in Capybara during autoBuild
  • Prevents race conditions when running tests in parallel (each thread could start a build)

To achieve that, it's recommended to run bin/rake assets:precompile—which should also run vite build—in a previous CI step.

You can verify your setup is working by disabling autoBuild. A convenient way to do that is to add VITE_RUBY_AUTO_BUILD="false" to the build environment variables.