sass-site/source/dart-sass.md

144 lines
3.8 KiB
Markdown
Raw Normal View History

---
layout: has_no_sidebars
title: Dart Sass
no_container: true
introduction: >
Dart Sass is the primary implementation of Sass, which means it gets new
features before any other implementation. It's fast, easy to install, and it
compiles to pure JavaScript which makes it easy to integrate into modern web
development workflows. Find out more or help out with its development on
[GitHub](https://github.com/sass/dart-sass).
---
<div class="sl-l-grid sl-l-grid--full sl-l-large-grid--fit sl-l-large-grid--gutters-large">
<div class="sl-l-grid__column">
## Command Line
Dart Sass's stand-alone command-line executable uses the blazing-fast Dart VM to
compile your stylesheets. To install Dart Sass on the command line, check out
the [installation instructions](/install). Once you've got it running, you can
use it compile files:
```shell
sass source/index.scss css/index.css
```
See `sass --help` for additional information on the command-line interface.
### Dart Library
You can also use Dart Sass as a Dart library to get the speed of the Dart VM
plus the ability to define your own functions and importers. To add it to an
existing project:
1. [Install the Dart SDK][install]. Make sure its `bin` directory is [on your
`PATH`][path].
[install]: https://dart.dev/get-dart
[path]: https://katiek2.github.io/path-doc/
2. Create a `pubspec.yaml` file like this:
```yaml
name: my_project
dev_dependencies:
sass: ^{{ releases['dart-sass'].version }}
```
3. Run `dart pub get`.
4. Create a `compile-sass.dart` file like this:
```dart
import 'dart:io';
import 'package:sass/sass.dart' as sass;
void main(List<String> arguments) {
var result = sass.compile(arguments[0]);
new File(arguments[1]).writeAsStringSync(result);
}
```
5. You can now use this to compile files:
```shell
dart compile-sass.dart styles.scss styles.css
```
6. Learn more about [writing Dart code][dart] (it's easy!) and about [Sass's
Dart API][sass].
[dart]: https://www.dartlang.org/guides/language/language-tour
[sass]: https://pub.dev/documentation/sass/latest/sass/compileToResult.html
</div>
<div class="sl-l-grid__column">
## JavaScript Library
Dart Sass is also distributed as the pure JavaScript [`sass`
package](https://www.npmjs.com/package/sass) on npm. The pure JS version is
slower than the stand-alone executable, but it's easy to integrate into existing
workflows and it allows you to define custom functions and importers in
JavaScript. You can add it to your project using `npm install --save-dev sass`
and `require()` it as a library:
```js
var sass = require('sass');
sass.render(
{
file: scss_filename,
},
function (err, result) {
/* ... */
},
);
// OR
var result = sass.renderSync({
file: scss_filename,
});
```
When installed via npm, Dart Sass supports a JavaScript API that aims to be
compatible with [Node Sass](https://github.com/sass/node-sass#usage). Full
compatibility is a work in progress, but Dart Sass currently supports the
`render()` and `renderSync()` functions. Note however that by default,
**`renderSync()` is more than twice as fast as `render()`**, due to the overhead
of asynchronous callbacks.
To avoid this performance hit, `render()` can use the [`fibers`][fibers] package
to call asynchronous importers from the synchronous code path. To enable this,
pass the `Fiber` class to the `fiber` option:
[fibers]: https://www.npmjs.com/package/fibers
```js
var sass = require('sass');
var Fiber = require('fibers');
sass.render(
{
file: 'input.scss',
importer: function (url, prev, done) {
// ...
},
fiber: Fiber,
},
function (err, result) {
// ...
},
);
```
See [Dart Sass's documentation][js api] for more information about its
JavaScript API.
[js api]: https://github.com/sass/dart-sass#legacy-javascript-api
</div>
</div>