Skip to main content

CSS Bundler

Overview​

CM Admin includes a CSS bundling system that compiles Sass/SCSS stylesheets. The bundler handles both the core CM Admin stylesheets and your application's custom styles

The system is built around a shared helper module CmAdminCssBundler that provides common functionality for running yarn-based CSS build processes.

How It Works​

The CSS bundler follows these steps:

  1. Install dependencies — Runs yarn install in the CM Admin engine directory
  2. Execute build script — Runs the specified yarn script (e.g., build:css, watch:css)
  3. Compile stylesheets — Uses Sass to compile SCSS files to CSS with optimized flags

Application Setup​

Step 1 — Ensure application stylesheet exists​

Create or update your main application stylesheet:

// app/assets/stylesheets/application.scss

NOTES:

  1. File should be scss
  2. No File on application should have, remove from app/assets/stylesheets/application.scss and cm_admin/app/assets/stylesheets/cm_admin/custom.css
*= require_tree .
*= require_self
  1. you can include any other stylesheets using @import directive in application.scss, it is the entry point for all your stylesheets.

Step 2 — Remove sassc-rails gem​

Remove the sassc-rails gem from your Gemfile since CM Admin's CSS bundler handles Sass compilation:

# Gemfile

# Remove this line
gem 'sassc-rails'

Then run bundle install to update your dependencies.

Step 3 — Remove stylesheet inclusion from manifest.js​

// app/assets/config/manifest.js

//= link_directory ../stylesheets .css

Step 4 — Add CSS build to manifest.js​

// app/assets/config/manifest.js

//= link_tree ../builds

Step 5 - Add .keep file to builds directory​

# Create .keep file to ensure directory is tracked by git
touch app/assets/builds/.keep

Step 6 - Update gitignore​

/app/assets/builds/*
!/app/assets/builds/.keep

Custom Layout CSS Files​

If your application uses multiple layouts (e.g., a separate layout for public-facing pages, landing pages, or embedded views), you can register additional SCSS files to be compiled alongside the default CM Admin stylesheets.

Configuration​

Add the layout_css_files option in your CM Admin initializer:

# config/initializers/zcm_admin.rb

CmAdmin.configure do |config|
  config.layout = 'admin'
  config.layout_css_files = ['public.scss', 'landing.scss']
end

Each entry should be a path relative to app/assets/stylesheets/. For example, 'public.scss' maps to app/assets/stylesheets/public.scss.

How It Works​

During the CSS build, each file listed in layout_css_files is compiled from its source location to app/assets/builds/ with the same base name:

SourceOutput
app/assets/stylesheets/public.scssapp/assets/builds/public.css
app/assets/stylesheets/landing.scssapp/assets/builds/landing.css

These files are compiled using the same Sass flags and load paths as the core CM Admin stylesheets, so you can use @import directives referencing CM Admin or node module dependencies.

Subdirectory Support​

You can also point to files inside subdirectories:

config.layout_css_files = ['layouts/public.scss', 'layouts/embedded.scss']
SourceOutput
app/assets/stylesheets/layouts/public.scssapp/assets/builds/public.css
app/assets/stylesheets/layouts/embedded.scssapp/assets/builds/embedded.css

Note: The output file name is derived from the base name only, regardless of subdirectory depth.

Stylesheet Import Paths​

If your application depends on stylesheets provided by Ruby gems (e.g., bootstrap, select2-rails, intl-tel-input-rails), you can register their stylesheet directories so the cm-admin Sass build can resolve @import/@use directives.

Configuration​

Add the stylesheet_import_paths option in your CM Admin initializer:

# config/initializers/zcm_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",
    "#{Gem.loaded_specs['intl-tel-input-rails'].full_gem_path}/app/assets/stylesheets"
  ]
end

How It Works​

Each entry is a directory path. During the Sass build, each directory is passed to the compiler as a --load-path=<path> flag, so any @import in application.scss or layout_css_files can resolve partials located in those directories.

Note: These are paths, not full flags. For example, assets/stylesheets not --load-path=assets/stylesheets.

Rake Commands​

Build Commands​

# Build all CSS files for production (already enhanced in assets:precompile rake task)
rake cm_admin:scss:build

These commands:

  • Compile cm_admin.css.scss → cm_admin.css
  • Compile cm_session.css.scss → cm_session.css
  • Compile application.scss → application.css
  • Place outputs in app/assets/builds/

Watch Commands​

# Watch for changes and auto-recompile during development
rake cm_admin:scss:watch

These commands start the Sass compiler in watch mode, automatically recompiling when source files change.

Integration with Assets Precompile​

The CSS build automatically runs during assets:precompile:

rake assets:precompile

This ensures your CSS is always up-to-date when deploying to production.

File Structure​

your-app/
├── app/assets/
│   ├── builds/           # Compiled CSS output (generated)
│   │   ├── cm_admin/
│   │   │   ├── cm_admin.css
│   │   │   └── cm_session.css
│   │   └── application.css

Troubleshooting​

Common Issues​

"yarn install failed"

  • Ensure Node.js and Yarn 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/