| 1 | A pure JavaScript implementation of [Sass][sass]. **Sass makes CSS fun again**.
|
|---|
| 2 |
|
|---|
| 3 | <table>
|
|---|
| 4 | <tr>
|
|---|
| 5 | <td>
|
|---|
| 6 | <img width="118px" alt="Sass logo" src="https://rawgit.com/sass/sass-site/master/source/assets/img/logos/logo.svg" />
|
|---|
| 7 | </td>
|
|---|
| 8 | <td valign="middle">
|
|---|
| 9 | <a href="https://www.npmjs.com/package/sass"><img width="100%" alt="npm statistics" src="https://nodei.co/npm/sass.png?downloads=true"></a>
|
|---|
| 10 | </td>
|
|---|
| 11 | <td valign="middle">
|
|---|
| 12 | <a href="https://github.com/sass/dart-sass/actions"><img alt="GitHub actions build status" src="https://github.com/sass/dart-sass/workflows/CI/badge.svg"></a>
|
|---|
| 13 | <br>
|
|---|
| 14 | <a href="https://ci.appveyor.com/project/nex3/dart-sass"><img alt="Appveyor build status" src="https://ci.appveyor.com/api/projects/status/84rl9hvu8uoecgef?svg=true"></a>
|
|---|
| 15 | </td>
|
|---|
| 16 | </tr>
|
|---|
| 17 | </table>
|
|---|
| 18 |
|
|---|
| 19 | [sass]: https://sass-lang.com/
|
|---|
| 20 |
|
|---|
| 21 | This package is a distribution of [Dart Sass][], compiled to pure JavaScript
|
|---|
| 22 | with no native code or external dependencies. It provides a command-line `sass`
|
|---|
| 23 | executable and a Node.js API.
|
|---|
| 24 |
|
|---|
| 25 | [Dart Sass]: https://github.com/sass/dart-sass
|
|---|
| 26 |
|
|---|
| 27 | * [Usage](#usage)
|
|---|
| 28 | * [API](#api)
|
|---|
| 29 | * [See Also](#see-also)
|
|---|
| 30 | * [Behavioral Differences from Ruby Sass](#behavioral-differences-from-ruby-sass)
|
|---|
| 31 |
|
|---|
| 32 | ## Usage
|
|---|
| 33 |
|
|---|
| 34 | You can install Sass globally using `npm install -g sass` which will provide
|
|---|
| 35 | access to the `sass` executable. You can also add it to your project using
|
|---|
| 36 | `npm install --save-dev sass`. This provides the executable as well as a
|
|---|
| 37 | library:
|
|---|
| 38 |
|
|---|
| 39 | [npm]: https://www.npmjs.com/package/sass
|
|---|
| 40 |
|
|---|
| 41 | ```js
|
|---|
| 42 | var sass = require('sass');
|
|---|
| 43 |
|
|---|
| 44 | sass.render({file: scss_filename}, function(err, result) { /* ... */ });
|
|---|
| 45 |
|
|---|
| 46 | // OR
|
|---|
| 47 |
|
|---|
| 48 | var result = sass.renderSync({file: scss_filename});
|
|---|
| 49 | ```
|
|---|
| 50 |
|
|---|
| 51 | [See below](#api) for details on Dart Sass's JavaScript API.
|
|---|
| 52 |
|
|---|
| 53 | ## API
|
|---|
| 54 |
|
|---|
| 55 | When installed via npm, Dart Sass supports a JavaScript API that's fully
|
|---|
| 56 | compatible with [Node Sass][] (with a few exceptions listed below), with support
|
|---|
| 57 | for both the `render()` and `renderSync()` functions. See [the Sass
|
|---|
| 58 | website][js api] for full API documentation!
|
|---|
| 59 |
|
|---|
| 60 | [Node Sass]: https://github.com/sass/node-sass
|
|---|
| 61 | [js api]: https://sass-lang.com/documentation/js-api
|
|---|
| 62 |
|
|---|
| 63 | Note however that by default, **`renderSync()` is more than twice as fast as
|
|---|
| 64 | `render()`** due to the overhead of asynchronous callbacks. To avoid this
|
|---|
| 65 | performance hit, `render()` can use the [`fibers`][fibers] package to call
|
|---|
| 66 | asynchronous importers from the synchronous code path. To enable this, pass the
|
|---|
| 67 | `Fiber` class to the `fiber` option:
|
|---|
| 68 |
|
|---|
| 69 | [fibers]: https://www.npmjs.com/package/fibers
|
|---|
| 70 |
|
|---|
| 71 | ```js
|
|---|
| 72 | var sass = require("sass");
|
|---|
| 73 | var Fiber = require("fibers");
|
|---|
| 74 |
|
|---|
| 75 | sass.render({
|
|---|
| 76 | file: "input.scss",
|
|---|
| 77 | importer: function(url, prev, done) {
|
|---|
| 78 | // ...
|
|---|
| 79 | },
|
|---|
| 80 | fiber: Fiber
|
|---|
| 81 | }, function(err, result) {
|
|---|
| 82 | // ...
|
|---|
| 83 | });
|
|---|
| 84 | ```
|
|---|
| 85 |
|
|---|
| 86 | Both `render()` and `renderSync()` support the following options:
|
|---|
| 87 |
|
|---|
| 88 | * [`data`](https://github.com/sass/node-sass#data)
|
|---|
| 89 | * [`file`](https://github.com/sass/node-sass#file)
|
|---|
| 90 | * [`functions`](https://github.com/sass/node-sass#functions--v300---experimental)
|
|---|
| 91 | * [`importer`](https://github.com/sass/node-sass#importer--v200---experimental)
|
|---|
| 92 | * [`includePaths`](https://github.com/sass/node-sass#includepaths)
|
|---|
| 93 | * [`indentType`](https://github.com/sass/node-sass#indenttype)
|
|---|
| 94 | * [`indentWidth`](https://github.com/sass/node-sass#indentwidth)
|
|---|
| 95 | * [`indentedSyntax`](https://github.com/sass/node-sass#indentedsyntax)
|
|---|
| 96 | * [`linefeed`](https://github.com/sass/node-sass#linefeed)
|
|---|
| 97 | * [`omitSourceMapUrl`](https://github.com/sass/node-sass#omitsourcemapurl)
|
|---|
| 98 | * [`outFile`](https://github.com/sass/node-sass#outfile)
|
|---|
| 99 | * [`sourceMapContents`](https://github.com/sass/node-sass#sourcemapcontents)
|
|---|
| 100 | * [`sourceMapEmbed`](https://github.com/sass/node-sass#sourcemapembed)
|
|---|
| 101 | * [`sourceMapRoot`](https://github.com/sass/node-sass#sourcemaproot)
|
|---|
| 102 | * [`sourceMap`](https://github.com/sass/node-sass#sourcemap)
|
|---|
| 103 | * Only the `"expanded"` and `"compressed"` values of
|
|---|
| 104 | [`outputStyle`](https://github.com/sass/node-sass#outputstyle) are supported.
|
|---|
| 105 |
|
|---|
| 106 | No support is intended for the following options:
|
|---|
| 107 |
|
|---|
| 108 | * [`precision`](https://github.com/sass/node-sass#precision). Dart Sass defaults
|
|---|
| 109 | to a sufficiently high precision for all existing browsers, and making this
|
|---|
| 110 | customizable would make the code substantially less efficient.
|
|---|
| 111 |
|
|---|
| 112 | * [`sourceComments`](https://github.com/sass/node-sass#sourcecomments). Source
|
|---|
| 113 | maps are the recommended way of locating the origin of generated selectors.
|
|---|
| 114 |
|
|---|
| 115 | ## See Also
|
|---|
| 116 |
|
|---|
| 117 | * [Dart Sass][], from which this package is compiled, can be used either as a
|
|---|
| 118 | stand-alone executable or as a Dart library. Running Dart Sass on the Dart VM
|
|---|
| 119 | is substantially faster than running the pure JavaScript version, so this may
|
|---|
| 120 | be appropriate for performance-sensitive applications. The Dart API is also
|
|---|
| 121 | (currently) more user-friendly than the JavaScript API. See
|
|---|
| 122 | [the Dart Sass README][Using Dart Sass] for details on how to use it.
|
|---|
| 123 |
|
|---|
| 124 | * [Node Sass][], which is a wrapper around [LibSass][], the C++ implementation
|
|---|
| 125 | of Sass. Node Sass supports the same API as this package and is also faster
|
|---|
| 126 | (although it's usually a little slower than Dart Sass). However, it requires a
|
|---|
| 127 | native library which may be difficult to install, and it's generally slower to
|
|---|
| 128 | add features and fix bugs.
|
|---|
| 129 |
|
|---|
| 130 | [Using Dart Sass]: https://github.com/sass/dart-sass#using-dart-sass
|
|---|
| 131 | [Node Sass]: https://www.npmjs.com/package/node-sass
|
|---|
| 132 | [LibSass]: https://sass-lang.com/libsass
|
|---|
| 133 |
|
|---|
| 134 | ## Behavioral Differences from Ruby Sass
|
|---|
| 135 |
|
|---|
| 136 | There are a few intentional behavioral differences between Dart Sass and Ruby
|
|---|
| 137 | Sass. These are generally places where Ruby Sass has an undesired behavior, and
|
|---|
| 138 | it's substantially easier to implement the correct behavior than it would be to
|
|---|
| 139 | implement compatible behavior. These should all have tracking bugs against Ruby
|
|---|
| 140 | Sass to update the reference behavior.
|
|---|
| 141 |
|
|---|
| 142 | 1. `@extend` only accepts simple selectors, as does the second argument of
|
|---|
| 143 | `selector-extend()`. See [issue 1599][].
|
|---|
| 144 |
|
|---|
| 145 | 2. Subject selectors are not supported. See [issue 1126][].
|
|---|
| 146 |
|
|---|
| 147 | 3. Pseudo selector arguments are parsed as `<declaration-value>`s rather than
|
|---|
| 148 | having a more limited custom parsing. See [issue 2120][].
|
|---|
| 149 |
|
|---|
| 150 | 4. The numeric precision is set to 10. See [issue 1122][].
|
|---|
| 151 |
|
|---|
| 152 | 5. The indented syntax parser is more flexible: it doesn't require consistent
|
|---|
| 153 | indentation across the whole document. See [issue 2176][].
|
|---|
| 154 |
|
|---|
| 155 | 6. Colors do not support channel-by-channel arithmetic. See [issue 2144][].
|
|---|
| 156 |
|
|---|
| 157 | 7. Unitless numbers aren't `==` to unit numbers with the same value. In
|
|---|
| 158 | addition, map keys follow the same logic as `==`-equality. See
|
|---|
| 159 | [issue 1496][].
|
|---|
| 160 |
|
|---|
| 161 | 8. `rgba()` and `hsla()` alpha values with percentage units are interpreted as
|
|---|
| 162 | percentages. Other units are forbidden. See [issue 1525][].
|
|---|
| 163 |
|
|---|
| 164 | 9. Too many variable arguments passed to a function is an error. See
|
|---|
| 165 | [issue 1408][].
|
|---|
| 166 |
|
|---|
| 167 | 10. Allow `@extend` to reach outside a media query if there's an identical
|
|---|
| 168 | `@extend` defined outside that query. This isn't tracked explicitly, because
|
|---|
| 169 | it'll be irrelevant when [issue 1050][] is fixed.
|
|---|
| 170 |
|
|---|
| 171 | 11. Some selector pseudos containing placeholder selectors will be compiled
|
|---|
| 172 | where they wouldn't be in Ruby Sass. This better matches the semantics of
|
|---|
| 173 | the selectors in question, and is more efficient. See [issue 2228][].
|
|---|
| 174 |
|
|---|
| 175 | 12. The old-style `:property value` syntax is not supported in the indented
|
|---|
| 176 | syntax. See [issue 2245][].
|
|---|
| 177 |
|
|---|
| 178 | 13. The reference combinator is not supported. See [issue 303][].
|
|---|
| 179 |
|
|---|
| 180 | 14. Universal selector unification is symmetrical. See [issue 2247][].
|
|---|
| 181 |
|
|---|
| 182 | 15. `@extend` doesn't produce an error if it matches but fails to unify. See
|
|---|
| 183 | [issue 2250][].
|
|---|
| 184 |
|
|---|
| 185 | 16. Dart Sass currently only supports UTF-8 documents. We'd like to support
|
|---|
| 186 | more, but Dart currently doesn't support them. See [dart-lang/sdk#11744][],
|
|---|
| 187 | for example.
|
|---|
| 188 |
|
|---|
| 189 | [issue 1599]: https://github.com/sass/sass/issues/1599
|
|---|
| 190 | [issue 1126]: https://github.com/sass/sass/issues/1126
|
|---|
| 191 | [issue 2120]: https://github.com/sass/sass/issues/2120
|
|---|
| 192 | [issue 1122]: https://github.com/sass/sass/issues/1122
|
|---|
| 193 | [issue 2176]: https://github.com/sass/sass/issues/2176
|
|---|
| 194 | [issue 2144]: https://github.com/sass/sass/issues/2144
|
|---|
| 195 | [issue 1496]: https://github.com/sass/sass/issues/1496
|
|---|
| 196 | [issue 1525]: https://github.com/sass/sass/issues/1525
|
|---|
| 197 | [issue 1408]: https://github.com/sass/sass/issues/1408
|
|---|
| 198 | [issue 1050]: https://github.com/sass/sass/issues/1050
|
|---|
| 199 | [issue 2228]: https://github.com/sass/sass/issues/2228
|
|---|
| 200 | [issue 2245]: https://github.com/sass/sass/issues/2245
|
|---|
| 201 | [issue 303]: https://github.com/sass/sass/issues/303
|
|---|
| 202 | [issue 2247]: https://github.com/sass/sass/issues/2247
|
|---|
| 203 | [issue 2250]: https://github.com/sass/sass/issues/2250
|
|---|
| 204 | [dart-lang/sdk#11744]: https://github.com/dart-lang/sdk/issues/11744
|
|---|
| 205 |
|
|---|
| 206 | Disclaimer: this is not an official Google product.
|
|---|
