Compile Sass to CSS

Compile Sass to CSS using LibSass.

sass(
  input = NULL,
  options = sass_options_get(),
  output = NULL,
  write_attachments = NA,
  cache = sass_cache_get(),
  cache_key_extra = NULL
)

Arguments

input

Any of the following:

A character vector containing Sass code.
A named list containing variable names and values.
A sass_file(), sass_layer(), and/or sass_bundle().
A list() containing any of the above.

options

Compiler sass_options().

output

Specifies path to output file for compiled CSS. May be a character string or output_template()

write_attachments

If the input contains sass_layer() objects that have file attachments, and output is not NULL, then copy the file attachments to the directory of output. (Defaults to NA, which merely emits a warning if file attachments are present, but does not write them to disk; the side-effect of writing extra files is subtle and potentially destructive, as files may be overwritten.)

cache

This can be a directory to use for the cache, a FileCache object created by sass_file_cache(), or FALSE or NULL for no caching.

cache_key_extra

additional information to considering when computing the cache key. This should include any information that could possibly influence the resulting CSS that isn't already captured by input. For example, if input contains something like "@import sass_file.scss" you may want to include the file.mtime() of sass_file.scss (or, perhaps, a packageVersion() if sass_file.scss is bundled with an R package).

Value

If output = NULL, the function returns a string value of the compiled CSS. If output is specified, the compiled CSS is written to a file and the filename is returned.

Caching

By default, caching is enabled, meaning that sass() avoids the possibly expensive re-compilation of CSS whenever the same options and input are requested. Unfortunately, in some cases, options and input alone aren't enough to determine whether new CSS output must be generated. For example, changes in local file imports that aren't captured through sass_file()/sass_import(), may lead to a false-positive cache hit. For this reason, developers are encouraged to capture such information in cache_key_extra (possibly with packageVersion('myPackage') if shipping Sass with a package), and users may want to disable caching altogether during local development by calling options(sass.cache=FALSE).

In some cases when developing and modifying .scss files, sass() might not detect changes, and keep using cached .css files instead of rebuilding them. To be safe, if you are developing a theme with sass, it's best to turn off caching by calling options(sass.cache=FALSE).

If caching is enabled, sass() will attempt to bypass the compilation process by reusing output from previous sass() calls that used equivalent inputs. This mechanism works by computing a cache key from each sass() call's input, option, and cache_key_extra arguments. If an object with that hash already exists within the cache directory, its contents are used instead of performing the compilation. If it does not exist, then compilation is performed and usual and the results are stored in the cache.

If a file that is included using sass_file() changes on disk (i.e. its last-modified time changes), its previous cache entries will effectively be invalidated (not removed from disk, but they'll no longer be matched). However, if a file imported using sass_file() itself imports other sass files using @import, changes to those files are invisible to the cache and you can end up with stale results. To avoid this problem when developing sass code, it's best to disable caching with options(sass.cache=FALSE).

By default, the maximum size of the cache is 40 MB. If it grows past that size, the least-recently-used objects will be evicted from the cache to keep it under that size. Also by default, the maximum age of objects in the cache is one week. Older objects will be evicted from the cache.

To clear the default cache, call sass_cache_get()$reset().

Examples

# Raw Sass input
sass("foo { margin: 122px * .3; }")
#> /* CSS */
#> foo {
#>   margin: 36.6px;
#> }
#> 

# List of inputs, including named variables
sass(list(
  list(width = "122px"),
  "foo { margin: $width * .3; }"
))
#> /* CSS */
#> foo {
#>   margin: 36.6px;
#> }
#> 

# Compile a .scss file
example_file <- system.file("examples/example-full.scss", package = "sass")
sass(sass_file(example_file))
#> /* CSS */
#> body {
#>   background-color: #333;
#>   color: white;
#>   font-size: 16px;
#> }
#> 

# Import a file
tmp_file <- tempfile()
writeLines("foo { margin: $width * .3; }", tmp_file)
sass(list(
  list(width = "122px"),
  sass_file(tmp_file)
))
#> /* CSS */
#> foo {
#>   margin: 36.6px;
#> }
#> 

if (FALSE) {
# ======================
# Caching examples
# ======================
# Very slow to compile
fib_sass <- "@function fib($x) {
  @if $x <= 1 {
    @return $x
  }
  @return fib($x - 2) + fib($x - 1);
}

body {
  width: fib(27);
}"

# The first time this runs it will be very slow
system.time(sass(fib_sass))

# But on subsequent calls, it should be very fast
system.time(sass(fib_sass))

# sass() can be called with cache=NULL; it will be slow
system.time(sass(fib_sass, cache = NULL))

# Clear the cache
sass_cache_get()$reset()
}

if (FALSE) {
# Example of disabling cache by setting the default cache to NULL.

# Disable the default cache (save the original one first, so we can restore)
old_cache <- sass_cache_get()
sass_cache_set(NULL)
# Will be slow, because no cache
system.time(sass(fib_sass))

# Restore the original cache
sass_cache_set(old_cache)
}

Arguments

Value

Caching

See also

Examples