@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:

import { src, dest } from 'gulp';
import { sync } from '@lmcd/gulp-dartsass';
import sass from 'sass';

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

Or for async compilation:

import { src, dest } from 'gulp';
import { async } from '@lmcd/gulp-dartsass';
import sass from 'sass';

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

API

import { sync, async } from '@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 Sass' Options interface.

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.

import { src, dest } from 'gulp';
import { sync } from '@lmcd/gulp-dartsass';
import sass from 'sass';
 
export function compile() {
  return 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.