CSS Bundler
cm-admin compiles its Sass/SCSS stylesheets β and any host-app stylesheets you register β with the CmAdminCssBundler helper, which runs npm-based CSS builds.
How it worksβ
- Install dependencies β runs
npm installin the cm-admin engine directory - Run the build script β runs the npm script (
build:css,watch:css) - Compile β Dart Sass compiles SCSS to CSS into
app/assets/builds/
Setupβ
1. Create application.scssβ
// app/assets/stylesheets/application.scss
- It must be a
.scssfile β this is the entry point, pull in other stylesheets with@import. - Remove any Sprockets directives (
*= require_tree .,*= require_self) from it and fromcm_admin/app/assets/stylesheets/cm_admin/custom.css.
2. Remove sassc-railsβ
# Gemfile β remove this line, then `bundle install`
gem 'sassc-rails'
3. Update manifest.jsβ
// app/assets/config/manifest.js
//= link_tree ../builds // add
//= link_directory ../stylesheets .css // remove
4. Create the builds directory and ignore its outputβ
touch app/assets/builds/.keep
/app/assets/builds/*
!/app/assets/builds/.keep
Required since Bootstrap 6
cm-admin uses Bootstrap 6, which can only be compiled with Dart Sass. cm-admin's stylesheets are therefore always built by this bundler; sassc-rails can't compile them. If your application still depends on sassc-rails for other stylesheets, set config.assets.css_compressor = nil in every non-development environment, otherwise libsass tries to re-compress the built CSS and fails on modern CSS syntax.
Custom layout CSS filesβ
To compile extra host-app stylesheets alongside the cm-admin stylesheets (e.g. for a public-facing layout), register them with layout_css_files. Each entry is a path relative to app/assets/stylesheets/ and compiles to app/assets/builds/<basename>.css with the same Sass flags and load paths as the core stylesheets.
# config/initializers/cm_admin.rb
CmAdmin.configure do |config|
config.layout_css_files = ['public.scss', 'layouts/embedded.scss']
end
| Source | Output |
|---|---|
app/assets/stylesheets/public.scss | app/assets/builds/public.css |
app/assets/stylesheets/layouts/embedded.scss | app/assets/builds/embedded.css |
The output name comes from the basename only, regardless of subdirectory depth.
Stylesheet import pathsβ
To @import/@use stylesheets shipped inside Ruby gems (e.g. bootstrap, select2-rails), register their stylesheet directories. Each entry is passed to the Sass compiler as a --load-path.
# config/initializers/cm_admin.rb
CmAdmin.configure do |config|
config.stylesheet_import_paths = [
"#{Gem.loaded_specs['bootstrap'].full_gem_path}/assets/stylesheets",
"#{Gem.loaded_specs['select2-rails'].full_gem_path}/vendor/assets/stylesheets"
]
end
Entries are plain paths β assets/stylesheets, not --load-path=assets/stylesheets.
Rake commandsβ
| Command | What it does |
|---|---|
cm_admin:scss:build | Compiles cm_admin.css.scss, cm_session.css.scss and application.scss into app/assets/builds/. |
cm_admin:scss:watch | Recompiles automatically when source files change β use during development. |
assets:precompile | Runs the CSS build automatically, so production deploys always have fresh CSS. |
File structureβ
your-app/
βββ app/assets/
β βββ builds/ # Compiled CSS output (generated)
β β βββ cm_admin/
β β β βββ cm_admin.css
β β β βββ cm_session.css
β β βββ application.css
Troubleshootingβ
Common Issuesβ
"npm install failed"
- Ensure Node.js and npm are installed
- Check that the CM Admin engine directory exists and is accessible
Compiled CSS not updating
- Run
rake cm_admin:scss:buildmanually to force rebuild - Check file permissions in
app/assets/builds/