A modern, high-performance Crystal wrapper for the Dart Sass CLI.

sassd.cr provides a familiar, libsass-style API while leveraging the power and spec-compliance of the official Dart Sass implementation. By shelling out to the native binary, it avoids the complexities of C bindings and the obsolescence of the deprecated LibSass library.

• Modern Sass Support: Full support for the latest Sass features and syntax.
• Full API Compatibility: Drop-in replacement for sass.cr - just change the require from "sass" to "sassd".
• Reusable Compiler Instance: Create a Sass::Compiler instance for efficient repeated compilations with consistent options.
• Zero-Config Installation: Automatically downloads the correct Dart Sass binary for your OS and Architecture.
• Cross-Platform Support: Works on Linux (arm64/amd64), macOS, and FreeBSD using precompiled Dart Sass binaries.
• Batch Compilation: Efficiently compile entire directories in a single process—perfect for static site generators.
• Flexible Output: Control output styles (expanded, compressed) and source map generation.
• Advanced Source Map Control: Customize source map behavior with options like source_map_urls (relative/absolute) and embed_sources.
• Charset Control: Control whether to emit @charset or BOM for CSS with non-ASCII characters.
• Error Handling: Option to emit error stylesheets when compilation fails instead of raising exceptions.
• Warning Control: Fine-grained control over warning behavior with quiet, quiet_deps, and verbose options.
• CLI Tool: Includes a standalone sassd executable for quick compilations.

1. Add the dependency to your shard.yml:

   dependencies:
     sassd:
       github: kritoke/sassd.cr

2. Run shards install.

This shard requires the Dart Sass executable. By default, shards install will automatically download the standalone binary to your project's bin/ folder.

If you need to trigger the installation manually, use Just:

Just is a modern command runner that provides better error handling and cross-platform compatibility.

# Install Just first (if not already installed)
# Then run:
just sass

To build the included CLI tool:

just build

require "sassd"

scss = <<-SCSS
.container {
  .content { color: #333; }
}
SCSS

css = Sass.compile(scss)

css = Sass.compile_file("src/assets/main.scss", style: "compressed")

Ideal for build pipelines and static site generators:

Sass.compile_directory(
  input_dir: "src/assets/sass",
  output_dir: "public/css",
  style: "compressed",
  source_map: true
)

For API compatibility with sass.cr, you can create a reusable Sass::Compiler instance:

compiler = Sass::Compiler.new(
  style: "compressed",
  source_map: true,
  source_map_embed: true,
  source_map_urls: "absolute",
  embed_sources: true,
  charset: false,
  error_css: false,
  quiet: true,
  load_paths: ["vendor/stylesheets"],
  include_path: "includes"
)

# Compile multiple files with the same options
css_application = compiler.compile_file("application.scss")
css_layout = compiler.compile("@import 'layout';")

# Modify options dynamically
compiler.style = "expanded"
compiler.source_map_urls = "relative"
compiler.embed_sources = false
compiler.load_paths << "additional/styles"

You can manually point the library to a specific Sass binary:

Sass.bin_path = "/usr/local/bin/sass"

This library is designed as a drop-in replacement for sass.cr. To migrate:

1. Change require "sass" to require "sassd" in your code
2. No other code changes needed - all methods and parameters are compatible
3. Optionally use the Sass::Compiler class for reusable compiler instances

For detailed migration instructions, see MIGRATION.md.

After running shards build, you can use the sassd utility:

./bin/sassd src/style.scss > public/style.css

This will attempt to download the standalone Dart Sass binary for your platform. If it cannot find a matching binary, it will fallback to an npm global installation.

The project uses Justfile for development tasks:

just sass          # Install Sass binary
just clean-sass    # Remove local Sass binaries
just test          # Run tests  
just build         # Build the project

Note: This library has been primarily tested on macOS (arm64). While it includes support for Linux (arm64/amd64) and FreeBSD (arm64/amd64) through the build system's platform detection and precompiled Dart Sass binary downloads, extensive testing on those platforms has not yet been performed. If you encounter any issues on these platforms, please open an issue.

This library is heavily inspired by and designed to be API-compatible with sass.cr by Johannes Müller. The original sass.cr library provided an excellent API design for Sass compilation in Crystal, and this implementation aims to preserve that experience while leveraging the modern Dart Sass implementation.

1. Fork it (https://github.com/kritoke/sassd.cr/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

• kritoke - creator and maintainer