Getting Rails Admin working on Rails 8 with Propshaft

rails_admin_rails8_guide.md

Getting Rails Admin Working on Rails 8 with Propshaft

Rails Admin 3.x doesn't work out of the box with Rails 8's Propshaft asset pipeline. The issue is that rails_admin's assets are SCSS files that need compilation, but Propshaft only serves static files—it doesn't compile SCSS like Sprockets did.

The Error

When you visit /admin, you'll see:

ActionView::Template::Error (The asset 'rails_admin.css' was not found in the load path.)
Caused by: Propshaft::MissingAssetError (The asset 'rails_admin.css' was not found in the load path.)

The Solution

Copy pre-compiled CSS from a working rails_admin instance into your app. The rails_admin-nobuild repo has done this work already.

Step 1: Download the compiled CSS

curl -o vendor/assets/stylesheets/rails_admin.css \
  https://raw.githubusercontent.com/3v0k4/rails_admin-nobuild/main/app/assets/stylesheets/rails_admin.css

Important: Put this in vendor/assets/stylesheets/, NOT app/assets/stylesheets/. If you put it in app/assets/stylesheets/, the Bootstrap styles will leak into your main site and break your styling.

Step 2: Copy the font files

The CSS references Font Awesome fonts at /rails_admin/. Copy them from the gem to your public directory:

mkdir -p public/rails_admin

# Find your gem path
GEM_PATH=$(bundle show rails_admin)

cp $GEM_PATH/vendor/assets/fonts/rails_admin/fa-solid-900.ttf public/rails_admin/
cp $GEM_PATH/vendor/assets/fonts/rails_admin/fa-solid-900.woff2 public/rails_admin/

Step 3: Update config/initializers/assets.rb

Add the vendor stylesheets directory to Propshaft's load path:

# config/initializers/assets.rb

Rails.application.config.assets.version = "1.0"

# Rails admin CSS is in vendor/assets/stylesheets/rails_admin.css
# Rails admin fonts are in public/rails_admin/ (served directly)
Rails.application.config.assets.paths << Rails.root.join("vendor/assets/stylesheets")

Step 4: Configure rails_admin to use importmap

In your rails_admin initializer, make sure you're using importmap for the JavaScript:

# config/initializers/rails_admin.rb

RailsAdmin.config do |config|
  config.asset_source = :importmap
  
  # ... rest of your config
end

Step 5: Verify it works

bin/rails server
# Visit http://localhost:3000/admin

Why This Works

1. CSS: Propshaft finds rails_admin.css in vendor/assets/stylesheets/ and serves it at /assets/rails_admin.css
2. Fonts: The CSS references fonts at /rails_admin/*.woff2 which are served directly from public/rails_admin/
3. JavaScript: The importmap asset source tells rails_admin to use its built-in importmap configuration for JS modules
4. Isolation: Keeping the CSS in vendor/ instead of app/assets/stylesheets/ prevents Bootstrap styles from leaking into your main app

File Structure

After setup, you should have:

your-app/
├── config/
│   └── initializers/
│       ├── assets.rb          # Updated with vendor path
│       └── rails_admin.rb     # asset_source = :importmap
├── public/
│   └── rails_admin/
│       ├── fa-solid-900.ttf
│       └── fa-solid-900.woff2
└── vendor/
    └── assets/
        └── stylesheets/
            └── rails_admin.css  # ~25k lines of compiled CSS

Troubleshooting

Styles leaking into main site

Make sure rails_admin.css is in vendor/assets/stylesheets/, not app/assets/stylesheets/.

Fonts not loading (icons missing)

Check that the font files are in public/rails_admin/ and accessible at /rails_admin/fa-solid-900.woff2.

JavaScript not working

Ensure config.asset_source = :importmap is set in your rails_admin initializer.

Credits

• Solution based on rails_admin-nobuild by Riccardo Odone
• The compiled CSS contains Bootstrap 5.1.3 + rails_admin custom styles