sprockets-sass_embedded

A Ruby gem for processing and compressing Sass files using Sprockets 4 and Embedded Dart Sass.

Getting Started

Before installing and using sprockets-sass_embedded, you'll want to have Ruby 2.7 (or newer) installed. Using a Ruby version managment tool like rbenv, chruby, or rvm is recommended.

sprockets-sass_embedded is developed using Ruby 2.7.8 and is tested against additional Ruby versions using GitHub Actions.

Installation

Add sprockets-sass_embedded to your project's Gemfile and run bundle install:

source "https://rubygems.org"

gem "sprockets-sass_embedded"

Usage

sprockets-sass_embedded works with projects leveraging Sprockets 4 for asset processing. With minimal configuration changes, Ruby on Rails, Sinatra, and Roda applications can take advantage of the features in recent versions of Dart Sass. sprockets-sass_embedded uses Natsuki's sass-embedded gem whose platform-specific releases closely track (and match version-for-version) the official dart-sass project's releases.

The examples below assume a Sass file named application.scss located in the assets path (e.g. app/assets/stylesheets/application.scss) appropriate for your app's framework. Asset paths are highly configurable, so the location of your asset files may vary.

Ruby on Rails

With sprockets-sass_embedded added to your project's Gemfile and installed, set config.assets.css_compressor = :sass_embedded in your application's environment configuration. See the Configuring Assets guide for additional details.

Sinatra

In Sinatra applications, sprockets-sass_embedded can work in conjunction with the sinatra-asset-pipeline gem. Using sinatra-asset-pipeline's defaults, a sample app.rb file may look like:

class App < Sinatra::Base
  set :assets_precompile, %w(application.css)

  set :assets_css_compressor, :sass_embedded

  register Sinatra::AssetPipeline

  get "/" do
    "Hello, world!"
  end
end

Roda

Similar to Sinatra, Roda applications may be configured to use sprockets-sass_embedded alongside the roda-sprockets gem. A sample config.ru file might look like:

class App < Roda
  plugin :render

  plugin :sprockets,
         css_compressor: :sass_embedded,
         debug: false,
         precompile: %w[application.css]

  route do |r|
    r.sprockets unless opts[:environment] == "production"

    r.root do
      render :index
    end
  end
end

run App.freeze.app

Asset Helpers

sprockets-sass_embedded includes a number of familiar helpers (e.g. image_path, image_url, font_path, font_url) that generate asset paths for use in your application. See the Functions module in lib/sprockets/sass_embedded/sass_processor.rb for the available helpers.

@font-face {
  font-family: "Hot Rush";
  src: font_url("hot-rush.woff2") format("woff2"),
       font_url("hot-rush.woff") format("woff");
}

html {
  background: image_url("vaporwave.png") repeat 50% 50%;
  font-family: "Times New Roman"
}

h1 {
  font-family: "Hot Rush";
}

Acknowledgments

sprockets-sass_embedded implements Natsuki's work from rails/sprockets#737 and wouldn't exist if not for their work bringing Dart Sass to Sprockets-enabled Ruby projects. Sprockets' internal workings are fairly complicated, so the Extending Sprockets guide was also helpful.

sprockets-sass_embedded is written and maintained by Jason Garber.

License

sprockets-sass_embedded is freely available under the MIT License. Use it, learn from it, fork it, improve it, change it, tailor it to your needs.