dartsass-rails

Follow these steps to switch from sass-rails (or sassc-rails) to dartsass-rails:

1. Remove the old gem:

   ./bin/bundle remove sass-rails

2. Install dartsass-rails using the installation guide.
3. Clean up Sprockets: Remove any references to Sass files from app/assets/config/manifest.js. Dart Sass handles these files now, and Sprockets attempting to build them will cause errors.
4. CI/CD Update: Ensure your continuous integration pipeline runs the build command before running browser-based tests:

   bundle exec rails dartsass:build

./bin/bundle remove sass-rails
./bin/rails dartsass:install
# Remove Sass references from app/assets/config/manifest.js
bundle exec rails dartsass:build

To add Dart Sass support to your Rails application, add the gem to your bundle and run the installer.

1. Add the gem:

   ./bin/bundle add dartsass-rails

2. Run the installer:

   ./bin/rails dartsass:install

This creates a default Sass input file at app/assets/stylesheets/application.scss. You should use the @use rule to import other style files into this entry point. The compiled output will be generated in app/assets/builds/application.css.

To ensure CSS changes are automatically reflected in your output, you need to run Dart Sass in watch mode. You can do this in two ways:

1. Separate process: Run rails dartsass:watch in a dedicated terminal.
2. Integrated (Recommended): Run ./bin/dev, which uses foreman to start both the Dart Sass watch process and the Rails server simultaneously.

You can customize the flags passed to the Dart Sass executable by modifying Rails.application.config.dartsass.build_options.

By default, the options are ["--style=compressed", "--no-source-map"]. Use the << operator to append new options to the existing array.

# config/initializers/dartsass.rb
Rails.application.config.dartsass.build_options << "--no-charset" << "--quiet-deps"

By default, only app/assets/stylesheets/application.scss is built. You can customize the input paths, output filenames, or add additional entry points by configuring the Rails.application.config.dartsass.builds hash in an initializer.

File-to-File mapping: The key is the relative path in app/assets/stylesheets/ and the value is the desired filename in app/assets/builds/.

Directory-to-Directory mapping: If both the key and value are directories, it performs directory-to-directory compilation. This compiles all Sass files in the source directory that do not start with an underscore (_).

# config/initializers/dartsass.rb
Rails.application.config.dartsass.builds = {
  "app/index.sass"  => "app.css",
  "site.scss"       => "site.css"
}

# Example: Directory-to-directory compilation
Rails.application.config.dartsass.builds = {
  "." => "."
}

If you are using propshaft and require sourcemaps, you must replace the default --no-source-map option with --embed-sources in your configuration.

# config/initializers/dartsass.rb
Rails.application.config.dartsass.build_options = ['--no-charset', '--embed-sources']

If you see LoadError: cannot load such file -- sassc, it means Sprockets is attempting to compile Sass files, but the required sass-rails or sassc-rails gems are missing. Since you are using dartsass-rails, Sprockets should not be touching Sass files.

Common Causes and Solutions:

• Sass files in Sprockets manifest: Check app/assets/config/manifest.js. If any Sass files are listed there, remove them. They should be managed by Dart Sass via the builds configuration.
• Dart Sass not running locally: If you've cleaned the manifest but still see the error, ensure the watch process is active by running ./bin/dev.
• CI/CD failure: If the error occurs in CI, ensure you have a build step that runs bundle exec rails dartsass:build before your tests start.

You can configure how dartsass-rails processes your Sass files using the config.dartsass object in a Rails initializer.

• config.dartsass.builds: A hash mapping source Sass files to their desired output CSS files. The default is {"application.scss" => "application.css"}.
• config.dartsass.build_options: An array of command-line flags passed directly to the Dart Sass executable (e.g., --style=compressed, --no-source-map).

# config/initializers/dartsass.rb
Rails.application.configure do
  config.dartsass.builds = { "application.scss" => "application.css", "other.scss" => "other.css" }
  config.dartsass.build_options = ["--style=compressed", "--no-source-map"]
end