R: Compile Sass to CSS

sass {sass} | R Documentation

## Compile Sass to CSS

### Description

Compile Sass to CSS using LibSass.

### Usage

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

### Arguments

`input` | Accepts raw Sass, a named list of variables, a list of raw Sass and/or named variables, or a `sass_layer()` object. See `as_sass()` and `sass_import()` / `sass_file()` for more details.
`options` | Compiler options for Sass. Please specify options using `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()`.

### See Also

https://sass-lang.com/guide

### Examples

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

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

    # Compile a .scss file
    example_file <- system.file("examples/example-full.scss", package = "sass")
    sass(sass_file(example_file))

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

    ## Not run:
    # ======================
    # 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()

    ## End(Not run)

    ## Not run:
    # 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)

    ## End(Not run)

[Package sass version 0.3.1 Index]