Installation

Rails UI v3.3+ now works with both importmap (nobuild) and JS bundler (build) setups. It uses the tailwindcss-rails gem for CSS in both modes so no separate Tailwind installation needed.

Requirements

• Rails: 7.0 or higher
• CSS: Automatically handled via tailwindcss-rails gem (included)
• JS (build mode): Node.js, package manager (yarn/npm/pnpm/bun), and jsbundling-rails
• JS (nobuild mode): Nothing extra needed.

Installing Rails UI on new applications

With importmaps (nobuild) - default

# Create app (Rails 8 defaults to importmap)
rails new myapp
cd myapp

# Install Rails UI
bundle add railsui
rails railsui:install

# Start server
bin/dev

When to use: Zero build step, no Node.js required, fast refresh.

With JS Bundler (build mode)

# Create app with JS bundler
rails new myapp -j [bun|esbuild|rollup|webpack]
cd myapp

# Install Rails UI with --build flag
bundle add railsui
rails railsui:install --build

# Start server
bin/dev

When to use: TypeScript, advanced JS tooling, or complex dependencies.

Note: When you run rails new myapp -j esbuild (or other bundler), you may see build errors about missing packages. This is expected - the initial build runs before dependencies are installed. These errors are harmless and will be resolved when Rails UI installs the required packages.

Installing Rails UI on existing applications

Importmaps (nobuild)

bundle add railsui
rails railsui:install

Apps with a JS Bundler (esbuild, webpack, bun, rollup)

bundle add railsui
rails railsui:install --build

Apps without any JavaScript setup

Importmap:

bundle add railsui
rails railsui:install

JS Bundler:

# First install jsbundling-rails
bundle add jsbundling-rails
rails javascript:install:[bun|esbuild|rollup|webpack]
# Note: You may see build errors - this is expected and harmless

# Then install Rails UI
bundle add railsui
rails railsui:install --build

Migration scenarios

If you use an older version of Rails UI or have the cssbundling-rails gem configured, you can move to the new version with the built-in migration task.

Migrating from cssbundling-rails

If your app uses cssbundling-rails for Tailwind (installed with rails new myapp -c tailwind):

# Install Rails UI first
bundle add railsui
rails railsui:install

# Then migrate to tailwindcss-rails
rails railsui:migrate_to_tailwindcss_rails

This removes Tailwind from package.json and switches to the faster tailwindcss-rails gem.

Migrating from importmaps to JS Bundler

If your existing app uses importmap and you want to switch to a JS bundler for Rails UI:

# First install jsbundling-rails
bundle add jsbundling-rails
rails javascript:install:[bun|esbuild|rollup|webpack]

# Then install Rails UI with --build flag
bundle add railsui
rails railsui:install --build

Switching between build modes

You can change modes after installation by editing config/railsui.yml:

Example configuration:

build_mode: nobuild  # or "build"

Then run the appropriate setup:

rails railsui:update

Installation Warnings

Rails UI detects your setup and tries to provide helpful guidance:

• cssbundling-rails detected: suggests the migration task
• Missing jsbundling-rails with --build: shows setup instructions
• Configuration conflicts: provides recommendations

Skip warnings: RAILSUI_SKIP_WARNINGS=1 rails railsui:install

Running Your App

After installing Rails UI, start your server:

bin/dev

Then visit localhost:3000/railsui to access the configuration screen and customize your install.

What `bin/dev` does

• nobuild mode: Runs Rails server + Tailwind CSS watcher
• build mode: Runs Rails server + Tailwind CSS watcher + JS bundler watcher

Both modes use the same rails tailwindcss:watch command for CSS.