Skip to main content

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​

  1. Install dependencies β€” runs npm install in the cm-admin engine directory
  2. Run the build script β€” runs the npm script (build:css, watch:css)
  3. 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 .scss file β€” this is the entry point, pull in other stylesheets with @import.
  • Remove any Sprockets directives (*= require_tree ., *= require_self) from it and from cm_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
.gitignore
/app/assets/builds/*
!/app/assets/builds/.keep
warning

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
SourceOutput
app/assets/stylesheets/public.scssapp/assets/builds/public.css
app/assets/stylesheets/layouts/embedded.scssapp/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​

CommandWhat it does
cm_admin:scss:buildCompiles cm_admin.css.scss, cm_session.css.scss and application.scss into app/assets/builds/.
cm_admin:scss:watchRecompiles automatically when source files change β€” use during development.
assets:precompileRuns 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:build manually to force rebuild
  • Check file permissions in app/assets/builds/