Skip to content

Latest commit

 

History

History
131 lines (90 loc) · 6.24 KB

README.md

File metadata and controls

131 lines (90 loc) · 6.24 KB
Raw

sbt-sassify: Sass for SBT

Download Build Status

An sbt plugin that enables you to use Sass in your sbt-web project.

This plugin is a reimplementation of sbt-sass. Since I wasn't allowed to install the sass command line compiler on my company's' webserver (damn you corporate IT), I decided to rewrite the plugin to use libsass instead. Due to these changes, the plugin no longer resembled the old plugin, which is why I decided to host it myself.

Sass language version

This plugin is based on libsass version 3.5.5, that implements the Sass 3.4 specification.

Compatibility

The sbt-sassify plugin supports the following operating systems:

  • OS X 10.8+
  • Windows (32/64 bit)
  • Linux (32/64 bit)

This plugin has been tested against sbt-web and the Play framework versions 1.4.1 and 2.4.3+ respectively. Additionally, it requires Java 7.

Usage

To use the sbt-sassify plugin you can include the plugin in project/plugins.sbt or project/sbt-sassify.sbt like this:

addSbtPlugin("io.github.irundaia" % "sbt-sassify" % "1.5.2")

Directory structure

This plugin uses the same conventions as sbt-web. As such all *.sass and *.scss files in the <source dir>/assetsdirectory will be compiled. Depending on the extension of the file, the plugin will decide which syntax should be used to compile the source file. .sass for the indented syntax and .scss for the css-like syntax. (Note that the input style can be forced. See the syntaxDetection option.)

For example, given a file structure as:

app
└ assets
  └ stylesheets
    └ main.scss
    └ utils
      └ _reset.scss
      └ _layout.scss

With the following main.scss source:

@import "utils/reset";
@import "utils/layout";

h1 {
  color: red;
}

The Sass file outlined above, will be compiled into public/stylesheets/main.css, and it will include all the content of the reset and layout partials.

Mixing Sass and web-jars

WebJars enable us to depend on client side libraries without pulling all dependencies into our own code base manually.

Compass is a library containing all sorts of reusable Sass functions and mixins. Unfortunately, it is targeted towards the Ruby implementation of Sass. Luckily, there is a number of useful mixins that can be extracted from it. These mixins are wrapped in a WebJar.

Including the compass mixins in your project is as easy as including the WebJar dependency in your library dependencies. For example, within a build.sbt file add:

libraryDependencies += "org.webjars.bower" % "compass-mixins" % "0.12.7"

sbt-web will automatically extract WebJars into a `lib`` folder relative to your asset's target folder. Therefore, to use the Compass mixins you can import them by:

@import "lib/compass-mixins/lib/compass";

table.ellipsed-table {
  tr td {
    max-width: 100px;
    @include ellipsis();
  }
}

The same idea can be used to include other Sass libraries, for instance the official Sass port of bootstrap. To include the WebJar use:

libraryDependencies += "org.webjars.bower" % "bootstrap-sass" % "3.3.6"

Then to use it in your project, you can use:

@import "lib/bootstrap-sass/assets/stylesheets/bootstrap";

Options

Some options can be passed to the Sass compiler. For an overview, see below:

Setting Description Supported values Default value
cssStyle The style of the output CSS file. Minified/Maxified/Sassy Minified
generateSourceMaps Whether or not source files are generated. true/false true
embedSources Whether or not the sources should be embedded in the source map file. true/false true
syntaxDetection How to determine whether the sass/scss syntax is used. Auto/ForceScss/ForceSass Auto
assetRootURL The base URL used to locate the assets. Any String /assets
floatingPointPrecision The number of digits of precision used when rounding decimal numbers. Any positive Int 10
extension The extension of the compiled file Any String css

Changing the settings can be done by including the following settings in your build.sbt file:

import org.irundaia.sbt.sass._

SassKeys.cssStyle := Maxified

SassKeys.generateSourceMaps := true

SassKeys.syntaxDetection := ForceScss

Versioning

sbt-sassify uses semantic versioning. Given a version number major.minor.patch, an increment in

  • major signifies a non-backwards-compatible API change;
  • minor signifies a backwards-compatible functionality implementation;
  • patch signifies a backwards-compatible bug fix/refactoring.

Known limitations

  1. Issues have been known to occur when a different version of libsass has been installed on your system. This is caused by the c-API changing in libsass version 3.4.5. If your system has a different version installed, this will cause linking errors. Currently, a workaround would be to make sure that the same version of libsass is installed.

  2. Only one Sass syntax style can be used at the same time. So when compiling a .scss file, one cannot include a .sass file. (Well, you can, but it won't compile.)

  3. Due to a lack of testing, this plugin might not work on all 32-bit linux distributions.