Rails UI: app kits and components for shipping a Rails SaaS faster

The value is in the screens, not the widgets

The positioning line in the README is precise: the product UI system for Rails SaaS builders, complete app kits and the Rails-native components behind them, in clean ERB and Tailwind, so you ship a finished product instead of a blank page.

The important word is kits. A page is described as a professionally designed starting point, and the app kits are the core of Rails UI, described as complete product surfaces for a kind of SaaS combining real screens, UI components, assets, JavaScript and color palettes. The guidance is to pick the app kit closest to what you are building, keep the screens that fit, and customize the rest.

That is a different proposition from a component library. A component library gives you a button and a card and leaves the page to you. An app kit gives you a working dashboard, a settings screen, a billing screen and a color palette, with the reusable components extracted out so they can be dropped into your own views. The README says app kits serve as a starting point for your app, with reusable components extracted for flexibility, and that these components are ready for use inside your application when you install Rails UI.

There is a terminology wrinkle worth knowing before you read the source. On railsui.com these are called app kits, but inside the gem and its config they are still referred to as themes, for example `Railsui.config.theme` and `app/assets/stylesheets/railsui/theme.css`, so you will see both terms. The repository carries a `tailwind.config.js` and a `postcss.config.js` alongside the gem's own `railsui.gemspec`, and the primary language is listed as HTML because most of the payload is ERB views.

The licence is reported as Other, a custom licence that GitHub cannot classify, with the terms in the LICENSE.md file, so that file is the one to read before you put it in a commercial product.

Tailwind comes from a gem, so the nobuild path needs no Node.js

The single most consequential change in the current version is stated in the installation section. Rails UI v3.3+ works with both importmap (nobuild) and JS bundler (build) setups, and it uses the `tailwindcss-rails` gem for CSS in both modes, so no separate Tailwind installation is needed.

That reshapes the requirements list. Rails 7.0 or higher is required. CSS is automatically handled via the `tailwindcss-rails` gem, which is included. JavaScript in build mode needs Node.js, a package manager such as yarn, npm, pnpm or bun, and jsbundling-rails. JavaScript in nobuild mode needs nothing extra.

There is a corresponding warning about the create command, and it is an IMPORTANT callout. Do not use `-c tailwind` when creating your app, as in previous versions of the gem, because Rails UI handles Tailwind CSS automatically now using the tailwindcss-rails gem. The old instruction is actively wrong for this version, and following it gives you a CSS build the installer does not expect.

The project also carries a migration task for the old arrangement. If your app uses `cssbundling-rails` for Tailwind, installed with `rails new myapp -c tailwind`, you can install Rails UI and then run `rails railsui:migrate_to_tailwindcss_rails`, which removes Tailwind from package.json and switches to the faster `tailwindcss-rails` gem.

The theme palette itself lives in `app/assets/stylesheets/railsui/theme.css`, and that file is where color palette customization and the Tailwind CSS configuration go. So the theme is a CSS file you edit, not a set of configuration keys, and it is the one file to look at when you want to understand how a kit is styled.

Installing on a new app is a bundle add and a rake task

The default path for a new application uses importmaps, and the README says so plainly: Rails 8 defaults to importmap.

# 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

The when-to-use line for this path is zero build step, no Node.js required, fast refresh.

The bundler path is the same with a different app creation flag and the `--build` flag on the installer:

# 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

This one is for TypeScript, advanced JS tooling, or complex dependencies.

One expectation to set on new apps: the README warns that `rails new myapp -j esbuild` may show build errors about missing packages, and says this is expected because the initial build runs before dependencies are installed, and that the errors are harmless and resolved when Rails UI installs the required packages.

For an existing application the commands shorten to `bundle add railsui` and `rails railsui:install`, with `--build` added for apps using esbuild, webpack, bun or rollup. Apps with no JavaScript setup at all still need `jsbundling-rails` and `rails javascript:install:[bun|esbuild|rollup|webpack]` before the `--build` install, and the same harmless build errors are expected there.

The installer is also self-aware about your setup and warns accordingly. It detects cssbundling-rails and suggests the migration task, it shows setup instructions when `--build` is used without jsbundling-rails present, and it provides recommendations for configuration conflicts. If the warnings are noise in a scripted environment, `RAILSUI_SKIP_WARNINGS=1 rails railsui:install` skips them.

Switching build modes later means migrating your own JavaScript

The build mode is a single setting in `config/railsui.yml`:

build_mode: nobuild  # or "build"

You can change it after installation and then run `rails railsui:update`. That part is easy.

The part that is not easy is the consequence, and the README marks it IMPORTANT. If you are moving from importmaps to a JS bundler for Rails UI, you will need to manually migrate your existing JavaScript imports from importmap format to bundler format. Rails UI will handle its own imports, but your app's custom JavaScript may need adjustments, and the README suggests considering removing `config/importmap.rb` if you are fully migrating to the bundler.

That is the real cost of the flexibility, and it is worth weighing before you start. The two modes are genuinely different toolchains, not a preference you can flip at runtime, and the installer does not convert your application's own JavaScript for you.

The `bin/dev` command is where the difference shows up at runtime. In nobuild mode it runs the Rails server plus the Tailwind CSS watcher. In build mode it runs the Rails server, the Tailwind CSS watcher and the JS bundler watcher. Both modes use the same `rails tailwindcss:watch` command for CSS, so the CSS pipeline is identical either way and only the JavaScript side differs.

Configuration happens in a browser at /railsui, and the kit pages are read-only

Rails UI is configured through `config/railsui.yml` or through an admin UI at `/railsui`, and the README says the easiest way to configure it is to visit `localhost:3000/railsui` and follow the prompts. After installation the same URL gives you the configuration screen, and the running application is reachable at `localhost:3000/railsui` once the server is up.

The quick configuration covers the application name and support email, theme selection, previewing the enabled pages for your theme, and previewing the theme.css file found in `app/assets/stylesheets/railsui/theme.css`.

The behavior that will cause you trouble is documented in the Important Notes. Each app kit comes with pages in `app/views/rui` that are treated as read-only, and updating your configuration will overwrite these files. To customize pages, you copy them to your app:

cp app/views/rui/pages/dashboard.html.erb app/views/pages/dashboard.html.erb

So the workflow is that the kit views are a generated artifact, your customizations live in your own app directory, and a configuration change will not clobber the copy but will overwrite the original. That is a reasonable design, and it does mean the kit pages are a starting point rather than a place to edit in place.

The main configuration file is `config/railsui.yml`, and the README points to a separate configuration guide in `guides/CONFIGURATION.md` for the detailed options, with a migration guide in `guides/MIGRATION_GUIDE.md` and extended documentation hosted at railsui.com/docs.

The JavaScript side ships Stimulus, esbuild and a small set of libraries

The `package.json` in the repository root gives a good picture of what the kit brings with it, and it is a modest list.

The runtime dependencies are `@hotwired/stimulus` at 3.2.1, `railsui-stimulus` at 1.0.8, `stimulus-use` at 0.52.0, `debounce`, `deepmerge`, `flatpickr` for date picking, `highlight.js` for code blocks, `tippy.js` for tooltips, and `vanilla-colorful` for the color picker that the theme configuration implies.

There is one build script, and it is the only one, named `build:js`, and it runs esbuild over `app/javascript/*.*` with `--bundle --sourcemap` and writes the output to `app/assets/builds/railsui`. So the JavaScript is Stimulus-based rather than a framework, and esbuild does the bundling.

Two things about the repository layout are worth noting for anyone reading the source. There is a `Procfile.dev`, which is the standard Rails file for defining development processes and the companion to `bin/dev`. And the repository carries a `Gemfile` and `Gemfile.lock` at the top level alongside `package.json` and `yarn.lock`, which is how a gem that also ships JavaScript ends up with two lockfiles.

The maintenance picture is modest but current. The repository is not archived, the last push was on 2026-06-08, and the listed releases are v3.4.2 and v3.4.1 both on 2026-02-13, with v3.4.0 on 2026-02-09. The homepage is railsui.com, with a docs site, a blog for updates, a discussions board for questions and a migration guide for anyone coming from v2.

Editorial conclusion

Adopt Rails UI if you are building a Rails SaaS and want designed screens and a theme on day one rather than a hand-built dashboard, and you can accept that the kit pages live under `app/views/rui` and are overwritten when you change configuration. Do not adopt it if you need full control of every view from the start, since the copy-out step is manual, or if you are on a Rails version below 7.0. Verify first which of the two build modes your app uses, since switching later means migrating your own JavaScript imports by hand, and check the custom licence in the LICENSE file before shipping it in a commercial product.

Frequently asked questions

Official sources

1. getrailsui/railsui on GitHub
2. Issues
3. Project website
4. README
5. Releases