DOCSEARCHbyAlgolia
Submit Docs

Rails UI

repository·main·Indexed 20 days ago

https://github.com/getrailsui/railsui

A Rails engine providing a product UI system for SaaS builders. It includes complete app kits, Rails-native components, and professional layouts using ERB and Tailwind CSS. Supports two JavaScript modes: 'nobuild' (using importmaps) and 'build' (using JS bundlers like esbuild, bun, rollup, or webpack). Features include Stimulus.js-based components, Heroicons integration via the railsui_icon gem, and a visual configuration Admin UI.

Tokens
3.2K
Snippets
14
Records
19
Agent score
68%

What's inside railsui

  1. Choose between No-build (importmap) and Build mode

    main

    Rails UI supports two JavaScript build modes via the build_mode setting in config/railsui.yml.

    No-build mode (nobuild)

    Default for Rails UI v3.3+.

    • Best for: Simple apps, prototypes, or apps without complex JS requirements.
    • Setup: Run rails railsui:install.
    • Characteristics: Zero JS build step, no Node.js required, uses importmaps via CDN. Requires internet for CDN dependencies in dev mode.
    • Dev Server: bin/dev runs only the Rails server and Tailwind CSS watcher.

    Build Mode (build)

    • Best for: Production apps, TypeScript projects, or complex JS requirements.
    • Setup: Run rails railsui:install --build.
    • Characteristics: Full control over JS bundling, supports TypeScript/JSX, works offline, requires Node.js and a package manager. Supports Bun, esbuild, Rollup, and Webpack.
    • Dev Server: bin/dev runs the Rails server, Tailwind CSS watcher, and a JS bundler watcher.
    # Example for Build Mode
build_mode: build

  2. Understand Rails UI App Kits and Components

    main

    Rails UI provides App Kits (also referred to as themes in the code/config), which are complete product surfaces for SaaS applications.

    Core Concepts

    • App Kits/Themes: A collection of screens, UI components, assets, and color palettes. You can swap these via config/railsui.yml.
    • Pages: Professionally designed starting points located in app/views/rui. These are optional and should be copied to your own views if you wish to customize them.
    • UI Components: Built on top of Stimulus.js. They use the railsui-stimulus library for interactive behavior.
    • Icons: Uses the railsui_icon gem, which is currently based on Heroicons.
    • Colors: Each kit uses a custom palette built on the Tailwind CSS v4 color palette, customizable in app/assets/stylesheets/railsui/theme.css.

  3. Switch between nobuild and build modes

    main

    Rails UI supports two modes: nobuild (using Importmaps, default for Rails 8) and build (using a JS bundler like esbuild or bun). You can switch between them by updating your configuration and asset pipeline.

    Switch to nobuild mode (Importmaps)

    1. Install importmap-rails if not present: bundle add importmap-rails && rails importmap:install.
    2. In config/railsui.yml, set build_mode: nobuild.
    3. Regenerate assets: rails generate railsui:update.
    4. Update Procfile.dev to remove the js line (keep web and css).
    5. Restart with bin/dev.

    Switch to build mode (JS Bundler)

    1. Install jsbundling-rails and your preferred bundler: bundle add jsbundling-rails && rails javascript:install:[bun|esbuild|rollup|webpack].
    2. In config/railsui.yml, set build_mode: build.
    3. Regenerate assets: rails generate railsui:update.
    4. Install JS dependencies: yarn install (or your bundler's equivalent).
    5. Update Procfile.dev to include the js line (e.g., js: yarn build:js --watch).
    6. Restart with bin/dev.

  4. Customize Rails UI pages

    main

    Pages provided by Rails UI are located in app/views/rui and are treated as read-only. If you update your Rails UI configuration, these files may be overwritten.

    To customize a page and ensure your changes persist, copy the file from the rui directory to your application's view directory:

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

  5. Customize colors and themes

    main

    Themes use Tailwind CSS v4. You can customize your brand colors by editing the theme CSS file.

    1. Edit app/assets/stylesheets/railsui/theme.css.
    2. Update color or utility values within the @theme block using Tailwind CSS syntax.
    3. Rebuild your CSS to apply changes.

    Example CSS update:

    @theme {
  /* Your brand colors */
  --color-primary-500: #3b82f6;
  --color-primary-600: #2563eb;
  /* ... update other shades ... */
}

    Rebuild command:

    rails tailwindcss:build

    Usage in templates: Use the defined colors via standard Tailwind utility classes:

    <button class="bg-primary-600 hover:bg-primary-700 text-white">
  Click me
</button>
    @theme {
  --color-primary-500: #3b82f6;
  --color-primary-600: #2563eb;
}

  6. Install Rails UI on a new application

    main

    Rails UI supports two modes: nobuild (using importmaps) and build (using a JS bundler).

    Option 1: Importmaps (nobuild mode)

    Use this for zero build steps and no Node.js requirement. This is the default for Rails 8.

    rails new myapp
cd myapp
bundle add railsui
rails railsui:install
bin/dev

    Option 2: JS Bundler (build mode)

    Use this if you need TypeScript, advanced JS tooling, or complex dependencies. Requires Node.js and a package manager.

    # Create app with a bundler (esbuild, bun, etc.)
rails new myapp -j [bun|esbuild|rollup|webpack]
cd myapp
bundle add railsui
rails railsui:install --build
bin/dev

    Note: If you see build errors immediately after rails new, they are harmless and will resolve once the dependencies are installed by the railsui:install command.

    # Example for Importmaps (nobuild)
rails new myapp
cd myapp
bundle add railsui
rails railsui:install
bin/dev

  7. Migrate from cssbundling-rails to tailwindcss-rails

    main

    If your application was created with rails new myapp -c tailwind (using cssbundling-rails), you should migrate to the faster tailwindcss-rails gem used by Rails UI.

    1. Install Rails UI:
      bundle add railsui
rails railsui:install
    2. Run the migration task:
   ```bash
   rails railsui:migrate_to_tailwindcss_rails

    This process removes Tailwind from your package.json and switches the implementation to the tailwindcss-rails gem.

    bundle add railsui
rails railsui:install
rails railsui:migrate_to_tailwindcss_rails

  8. Upgrade from Rails UI v3.2 or earlier

    main

    To upgrade from version 3.2 or earlier to the current version, follow these steps to ensure the new tailwindcss-rails dependency and installation workflow are applied correctly.

    1. Update the gem.
    2. Run the Tailwind migration command.
    3. Regenerate Rails UI assets.
    4. Restart your development server.
    bundle update railsui
rails railsui:migrate_to_tailwindcss_rails
rails generate railsui:update
bin/dev

  9. Switch between Rails UI build modes

    main

    You can switch between nobuild (importmaps) and build (JS bundler) modes after installation by modifying the configuration file.

    1. Edit config/railsui.yml and update the build_mode key:
      build_mode: nobuild  # or "build"
    2. Run the update command to regenerate assets:
      rails railsui:update
    # config/railsui.yml
build_mode: build
    rails railsui:update

  10. Install Rails UI on an existing application

    main

    Depending on your existing JavaScript setup, follow the corresponding steps:

    Importmaps (nobuild)

    bundle add railsui
rails railsui:install

    JS Bundler (esbuild, webpack, bun, rollup)

    bundle add railsui
rails railsui:install --build

    No JavaScript setup

    If your app has no JS setup, you must first install jsbundling-rails if you want to use build mode:

    # For JS Bundler mode
bundle add jsbundling-rails
rails javascript:install:[bun|esbuild|rollup|webpack]
bundle add railsui
rails railsui:install --build
    # Example for existing app with JS Bundler
bundle add railsui
rails railsui:install --build

  11. Configure Rails UI via Admin UI or YAML

    main

    Rails UI can be configured in two ways:

    1. Admin UI: Visit localhost:3000/railsui in your browser to use a visual configuration screen. This allows you to set the application name, support email, theme selection, and preview pages.
    2. Configuration File: Edit config/railsui.yml directly.

    Customizing Styles

    To customize your color palette and Tailwind CSS configuration, edit: app/assets/stylesheets/railsui/theme.css

  12. Configure Rails UI via config/railsui.yml

    main

    Rails UI configuration is managed through the config/railsui.yml file. This file is automatically created during installation and can be edited manually or via the admin UI at /railsui.

    application_name: My App
support_email: support@example.com
theme: hound
build_mode: nobuild
pages:
  - dashboard
  - pricing
  - ...