@lmcd/gulp-dartsass

gulp-dartsass is a Sass-wrapper for Gulp with support for the modern API's custom file importers and functions.

Installation

To use gulp-dartsass, you must install both gulp-dartsass itself and the sass package.

npm install --save-dev @lmcd/gulp-dartsass sass

Usage

gulp-dartsass supports both sync and async compilation. You should only use async compilation when utilising async custom importers. Otherwise, sync compilation is preferred for speed.

For sync compilation:

const { src, dest } = require('gulp');
const { sync } = require('@lmcd/gulp-dartsass');
const sass = require('sass');

function compile() {
  return src('./sass/**/*.scss')
    .pipe(sync(sass))
    .pipe(dest('./css'));
};

exports.styles = compile;

Or for async compilation:

const { src, dest } = require('gulp');
const { async } = require('@lmcd/gulp-dartsass');
const sass = require('sass');

function compile() {
  return src('./sass/**/*.scss')
    .pipe(async(sass))
    .pipe(dest('./css'));
};

exports.styles = compile;

API

const { sync, async } = require('@lmcd/gulp-dartsass');

gulp-dartsass exports both sync and async factory methods with the following signature:

(sass: SassCompiler, options?: Record<string, any>)

Where:

• SassCompiler must be the sass package.
• options is passed directly to Sass and should match StringOptionsWithImporter or StringOptionsWithoutImporter.

Sourcemaps

Gulp's src and dest built-in support for sourcemaps is the preferred way to use include sourcemaps in your output. However, gulp-dartsass will also function with gulp-sourcemaps.

const { src, dest } = require('gulp');
const { sync } = require('@lmcd/gulp-dartsass');
const sass = require('sass');
 
.src('./sass/**/*.scss', { sourcemaps: true })
  .pipe(sync())
  .pipe(dest('./css', { sourcemaps: true }));

Tests

Tests are written with Jest. However, as the virtualisation employed by Jest is not presently compatible with Sass, jest-light-runner is used as the runner.

Implementation notes

• This plugin does not support legacy/deprecated versions of sass, such as LibSass/Node Sass. Nor does it support Gulp versions earlier than Gulp 4.
• This plugin does not support Sass's legacy API options.
• Passing a character-encodings other than UTF-8 is not explicitly disallowed, but the results are indeterminate.

License

This repository is licensed under the MIT license.