From a980945d3febcd981bcd3bbd48c10fd8b9430257 Mon Sep 17 00:00:00 2001 From: EJ Mason Date: Mon, 7 Jun 2021 16:05:44 -0700 Subject: [PATCH 01/21] Update node-sass to 6.0.0 Also moves node-sass to devDependencies and peerDependencies. This helps prevent dupes and conflicts in packages using gulp-sass --- package.json | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/package.json b/package.json index fde276c4..9ce3864b 100644 --- a/package.json +++ b/package.json @@ -26,7 +26,6 @@ "dependencies": { "chalk": "^2.3.0", "lodash": "^4.17.11", - "node-sass": "^4.8.3", "plugin-error": "^1.0.1", "replace-ext": "^1.0.0", "strip-ansi": "^4.0.0", @@ -39,13 +38,18 @@ "eslint-config-airbnb-base": "^12.1.0", "eslint-plugin-import": "^2.9.0", "globule": "^1.0.0", - "gulp": "^3.8.11", - "gulp-postcss": "^7.0.1", - "gulp-sourcemaps": "^2.6.4", - "gulp-tap": "^0.1.3", + "gulp": "^4.0.2", + "gulp-postcss": "^9.0.0", + "gulp-sourcemaps": "^3.0.0", + "gulp-tap": "^2.0.0", "mocha": "^5.0.4", + "node-sass": "^6.0.0", + "postcss": "^8.3.0", "rimraf": "^2.4.3", "should": "^13.2.1", "vinyl": "^2.1.0" + }, + "peerDependencies": { + "node-sass": "^6.0.0" } } From 169c5c2ff08ea3a8f1fb87ff7ddcc052ed5d5d0f Mon Sep 17 00:00:00 2001 From: EJ Mason Date: Mon, 7 Jun 2021 16:07:53 -0700 Subject: [PATCH 02/21] Make mocha test compatible with gulp@4 --- test/main.js | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/test/main.js b/test/main.js index 2ae56f05..75e4fab6 100644 --- a/test/main.js +++ b/test/main.js @@ -469,8 +469,8 @@ describe('gulp-sass -- sync compile', () => { .pipe(tap((file) => { should.exist(file.sourceMap); file.sourceMap.sources.should.eql(expectedSourcesAfter); - })) - .on('end', done); + })); + done(); }); it('should work with gulp-sourcemaps and a globbed source', (done) => { @@ -491,8 +491,8 @@ describe('gulp-sass -- sync compile', () => { const actual = normaliseEOL(file.sourceMap.sourcesContent[0]); const expected = normaliseEOL(filesContent[path.normalize(file.sourceMap.sources[0])]); actual.should.eql(expected); - })) - .on('end', done); + })); + done(); }); it('should work with gulp-sourcemaps and autoprefixer with different file.base', (done) => { @@ -519,8 +519,8 @@ describe('gulp-sass -- sync compile', () => { .pipe(tap((file) => { should.exist(file.sourceMap); file.sourceMap.sources.should.eql(expectedSourcesAfter); - })) - .on('end', done); + })); + done(); }); it('should work with empty files', (done) => { @@ -533,7 +533,7 @@ describe('gulp-sass -- sync compile', () => { } catch (e) { should.fail(false, true, 'Empty file was produced'); } - })) - .on('end', done); + })); + done(); }); }); From bed1e99e710ed587c2b6986bc272ee7d952225d5 Mon Sep 17 00:00:00 2001 From: EJ Mason Date: Mon, 7 Jun 2021 16:08:16 -0700 Subject: [PATCH 03/21] Update package version, engines --- package.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/package.json b/package.json index 9ce3864b..f4cc968c 100644 --- a/package.json +++ b/package.json @@ -1,10 +1,10 @@ { "name": "gulp-sass", - "version": "4.1.0", + "version": "5.0.0", "description": "Gulp plugin for sass", "main": "index.js", "engines": { - "node": ">=6" + "node": ">=12" }, "scripts": { "test": "./node_modules/.bin/mocha test" From 8637494b2623b9d07230915513631ece47b706cb Mon Sep 17 00:00:00 2001 From: EJ Mason Date: Mon, 14 Jun 2021 19:57:21 -0700 Subject: [PATCH 04/21] Remove node-sass as peer dependency --- package.json | 3 --- 1 file changed, 3 deletions(-) diff --git a/package.json b/package.json index f4cc968c..f1bfd6bc 100644 --- a/package.json +++ b/package.json @@ -48,8 +48,5 @@ "rimraf": "^2.4.3", "should": "^13.2.1", "vinyl": "^2.1.0" - }, - "peerDependencies": { - "node-sass": "^6.0.0" } } From 2f668da6582062d3a3d158590282066d32c3cc3f Mon Sep 17 00:00:00 2001 From: EJ Mason Date: Mon, 14 Jun 2021 22:54:27 -0700 Subject: [PATCH 05/21] Replace through2 with transfob --- index.js | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/index.js b/index.js index b0aed3b9..67a24226 100644 --- a/index.js +++ b/index.js @@ -1,18 +1,34 @@ const chalk = require('chalk'); const PluginError = require('plugin-error'); +const { Transform } = require('stream'); const replaceExtension = require('replace-ext'); const stripAnsi = require('strip-ansi'); -const through = require('through2'); const clonedeep = require('lodash/cloneDeep'); const path = require('path'); const applySourceMap = require('vinyl-sourcemaps-apply'); const PLUGIN_NAME = 'gulp-sass'; + +/** + * @typedef { import('stream').TransformCallback } TransformCallback + * + * A tiny wrapper for dealing with streams. + * @param {function(*, BufferEncoding, TransformCallback):void} transform + * @see https://metafizzy.co/blog/transfob-replaces-through2-gulp/ + */ +function transfob(transform) { + return new Transform({ + transform, + objectMode: true, + }); +} + + ////////////////////////////// // Main Gulp Sass function ////////////////////////////// -const gulpSass = (options, sync) => through.obj((file, enc, cb) => { // eslint-disable-line consistent-return +const gulpSass = (options, sync) => transfob((file, enc, cb) => { // eslint-disable-line consistent-return if (file.isNull()) { return cb(null, file); } From 89d6b7c36d8428164aed3977aab0045e6ceed82d Mon Sep 17 00:00:00 2001 From: EJ Mason Date: Mon, 14 Jun 2021 22:54:38 -0700 Subject: [PATCH 06/21] Uninstall through2 --- package.json | 1 - 1 file changed, 1 deletion(-) diff --git a/package.json b/package.json index f1bfd6bc..535d0818 100644 --- a/package.json +++ b/package.json @@ -29,7 +29,6 @@ "plugin-error": "^1.0.1", "replace-ext": "^1.0.0", "strip-ansi": "^4.0.0", - "through2": "^2.0.0", "vinyl-sourcemaps-apply": "^0.2.0" }, "devDependencies": { From af7eb7262bbf16e5a38e0301031ace063d6fd72d Mon Sep 17 00:00:00 2001 From: EJ Mason Date: Mon, 14 Jun 2021 23:46:42 -0700 Subject: [PATCH 07/21] Throw error if compiler not set --- index.js | 21 ++++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) diff --git a/index.js b/index.js index 67a24226..55c03d16 100644 --- a/index.js +++ b/index.js @@ -29,6 +29,22 @@ function transfob(transform) { // Main Gulp Sass function ////////////////////////////// const gulpSass = (options, sync) => transfob((file, enc, cb) => { // eslint-disable-line consistent-return + if (!gulpSass.compiler || !gulpSass.compiler.render) { + const message = new PluginError( + PLUGIN_NAME, + '\n' + + 'gulp-sass 5 does not have a default SASS compiler; please set one yourself.\n' + + 'Both the `sass` and `node-sass` packages are permitted.\n' + + + 'For example, in your gulpfile:\n\n' + + ' var sass = require(\'gulp-sass\');\n' + + ' sass.compiler = require(\'sass\');\n', + { showProperties: false }, + ).toString(); + process.stderr.write(`${message}\n`); + process.exit(1); + } + if (file.isNull()) { return cb(null, file); } @@ -176,9 +192,4 @@ gulpSass.logError = function logError(error) { this.emit('end'); }; -////////////////////////////// -// Store compiler in a prop -////////////////////////////// -gulpSass.compiler = require('node-sass'); - module.exports = gulpSass; From 93b363d32f90719dacbfc650361187ca1c9662ad Mon Sep 17 00:00:00 2001 From: EJ Mason Date: Mon, 14 Jun 2021 23:52:20 -0700 Subject: [PATCH 08/21] Fix casing of Sass Co-authored-by: Michael Mifsud --- index.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.js b/index.js index 55c03d16..af189fce 100644 --- a/index.js +++ b/index.js @@ -33,7 +33,7 @@ const gulpSass = (options, sync) => transfob((file, enc, cb) => { // eslint-disa const message = new PluginError( PLUGIN_NAME, '\n' + - 'gulp-sass 5 does not have a default SASS compiler; please set one yourself.\n' + + 'gulp-sass 5 does not have a default Sass compiler; please set one yourself.\n' + 'Both the `sass` and `node-sass` packages are permitted.\n' + 'For example, in your gulpfile:\n\n' + From 6e82e251b185eefa09ce285acac86f2d2fe97b2b Mon Sep 17 00:00:00 2001 From: EJ Mason Date: Tue, 15 Jun 2021 00:32:10 -0700 Subject: [PATCH 09/21] Use function arg to set compiler, use transfob package --- index.js | 53 +++++++++++++++++++--------------------------------- package.json | 1 + 2 files changed, 20 insertions(+), 34 deletions(-) diff --git a/index.js b/index.js index af189fce..885d8c32 100644 --- a/index.js +++ b/index.js @@ -1,50 +1,18 @@ const chalk = require('chalk'); const PluginError = require('plugin-error'); -const { Transform } = require('stream'); const replaceExtension = require('replace-ext'); const stripAnsi = require('strip-ansi'); +const transfob = require('transfob'); const clonedeep = require('lodash/cloneDeep'); const path = require('path'); const applySourceMap = require('vinyl-sourcemaps-apply'); const PLUGIN_NAME = 'gulp-sass'; - -/** - * @typedef { import('stream').TransformCallback } TransformCallback - * - * A tiny wrapper for dealing with streams. - * @param {function(*, BufferEncoding, TransformCallback):void} transform - * @see https://metafizzy.co/blog/transfob-replaces-through2-gulp/ - */ -function transfob(transform) { - return new Transform({ - transform, - objectMode: true, - }); -} - - ////////////////////////////// // Main Gulp Sass function ////////////////////////////// const gulpSass = (options, sync) => transfob((file, enc, cb) => { // eslint-disable-line consistent-return - if (!gulpSass.compiler || !gulpSass.compiler.render) { - const message = new PluginError( - PLUGIN_NAME, - '\n' + - 'gulp-sass 5 does not have a default Sass compiler; please set one yourself.\n' + - 'Both the `sass` and `node-sass` packages are permitted.\n' + - - 'For example, in your gulpfile:\n\n' + - ' var sass = require(\'gulp-sass\');\n' + - ' sass.compiler = require(\'sass\');\n', - { showProperties: false }, - ).toString(); - process.stderr.write(`${message}\n`); - process.exit(1); - } - if (file.isNull()) { return cb(null, file); } @@ -192,4 +160,21 @@ gulpSass.logError = function logError(error) { this.emit('end'); }; -module.exports = gulpSass; +module.exports = (compiler) => { + if (!compiler || !compiler.render) { + const message = new PluginError( + PLUGIN_NAME, + '\n' + + 'gulp-sass 5 does not have a default Sass compiler; please set one yourself.\n' + + 'Both the `sass` and `node-sass` packages are permitted.\n' + + + 'For example, in your gulpfile:\n\n' + + ' var sass = require(\'gulp-sass\')(require(\'sass\'));\n', + { showProperties: false }, + ).toString(); + process.stderr.write(`${message}\n`); + process.exit(1); + } + gulpSass.compiler = compiler; + return gulpSass; +}; diff --git a/package.json b/package.json index 535d0818..ea42ede4 100644 --- a/package.json +++ b/package.json @@ -29,6 +29,7 @@ "plugin-error": "^1.0.1", "replace-ext": "^1.0.0", "strip-ansi": "^4.0.0", + "transfob": "^1.0.0", "vinyl-sourcemaps-apply": "^0.2.0" }, "devDependencies": { From b47ca497db977aa4838d1ac85ce783fb7dd60ba4 Mon Sep 17 00:00:00 2001 From: EJ Mason Date: Tue, 15 Jun 2021 00:32:25 -0700 Subject: [PATCH 10/21] Update test to new API signature --- test/main.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/test/main.js b/test/main.js index 75e4fab6..4cdc81ce 100644 --- a/test/main.js +++ b/test/main.js @@ -2,7 +2,7 @@ const should = require('should'); const Vinyl = require('vinyl'); const path = require('path'); const fs = require('fs'); -const sass = require('../index'); +const sass = require('../index')(require('node-sass')); const rimraf = require('rimraf'); const gulp = require('gulp'); const sourcemaps = require('gulp-sourcemaps'); From 0ccfa8b694697307cf5cf8fd708d887aec0cf422 Mon Sep 17 00:00:00 2001 From: EJ Mason Date: Wed, 16 Jun 2021 12:22:00 -0700 Subject: [PATCH 11/21] Update package versions --- package.json | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/package.json b/package.json index ea42ede4..49ec5e9b 100644 --- a/package.json +++ b/package.json @@ -7,7 +7,7 @@ "node": ">=12" }, "scripts": { - "test": "./node_modules/.bin/mocha test" + "test": "mocha test" }, "repository": { "type": "git", @@ -24,29 +24,29 @@ "url": "https://github.com/dlmanning/gulp-sass/issues" }, "dependencies": { - "chalk": "^2.3.0", - "lodash": "^4.17.11", + "chalk": "^4.1.1", + "lodash": "^4.17.21", "plugin-error": "^1.0.1", - "replace-ext": "^1.0.0", - "strip-ansi": "^4.0.0", + "replace-ext": "^2.0.0", + "strip-ansi": "^6.0.0", "transfob": "^1.0.0", - "vinyl-sourcemaps-apply": "^0.2.0" + "vinyl-sourcemaps-apply": "^0.2.1" }, "devDependencies": { - "autoprefixer": "^8.1.0", - "eslint": "^4.18.2", - "eslint-config-airbnb-base": "^12.1.0", - "eslint-plugin-import": "^2.9.0", - "globule": "^1.0.0", + "autoprefixer": "^10.2.6", + "eslint": "^7.28.0", + "eslint-config-airbnb-base": "^14.2.1", + "eslint-plugin-import": "^2.23.4", + "globule": "^1.3.2", "gulp": "^4.0.2", "gulp-postcss": "^9.0.0", "gulp-sourcemaps": "^3.0.0", "gulp-tap": "^2.0.0", - "mocha": "^5.0.4", + "mocha": "^9.0.0", "node-sass": "^6.0.0", - "postcss": "^8.3.0", - "rimraf": "^2.4.3", - "should": "^13.2.1", - "vinyl": "^2.1.0" + "postcss": "^8.3.4", + "rimraf": "^3.0.2", + "should": "^13.2.3", + "vinyl": "^2.2.1" } } From a8de2a03bc4aca8849165de76f05b881f6c5f054 Mon Sep 17 00:00:00 2001 From: EJ Mason Date: Wed, 16 Jun 2021 12:22:47 -0700 Subject: [PATCH 12/21] Fix eslint errors --- index.js | 42 +++++++++++++++++++++--------------------- test/main.js | 37 +++++++++++++++++++------------------ 2 files changed, 40 insertions(+), 39 deletions(-) diff --git a/index.js b/index.js index 885d8c32..7b011ef4 100644 --- a/index.js +++ b/index.js @@ -9,9 +9,9 @@ const applySourceMap = require('vinyl-sourcemaps-apply'); const PLUGIN_NAME = 'gulp-sass'; -////////////////////////////// +/// /////////////////////////// // Main Gulp Sass function -////////////////////////////// +/// /////////////////////////// const gulpSass = (options, sync) => transfob((file, enc, cb) => { // eslint-disable-line consistent-return if (file.isNull()) { return cb(null, file); @@ -59,9 +59,9 @@ const gulpSass = (options, sync) => transfob((file, enc, cb) => { // eslint-disa opts.sourceMapContents = true; } - ////////////////////////////// + /// /////////////////////////// // Handles returning the file to the stream - ////////////////////////////// + /// /////////////////////////// const filePush = (sassObj) => { let sassMap; let sassMapFile; @@ -88,7 +88,7 @@ const gulpSass = (options, sync) => transfob((file, enc, cb) => { // eslint-disa } // Remove 'stdin' from souces and replace with filenames! - sassMap.sources = sassMap.sources.filter(src => src !== 'stdin' && src); + sassMap.sources = sassMap.sources.filter((src) => src !== 'stdin' && src); // Replace the map file with the original file name (but new extension) sassMap.file = replaceExtension(sassFileSrc, '.css'); @@ -106,9 +106,9 @@ const gulpSass = (options, sync) => transfob((file, enc, cb) => { // eslint-disa cb(null, file); }; - ////////////////////////////// + /// /////////////////////////// // Handles error message - ////////////////////////////// + /// /////////////////////////// const errorM = (error) => { const filePath = (error.file === 'stdin' ? file.path : error.file) || file.path; const relativePath = path.relative(process.cwd(), filePath); @@ -123,9 +123,9 @@ const gulpSass = (options, sync) => transfob((file, enc, cb) => { // eslint-disa }; if (sync !== true) { - ////////////////////////////// + /// /////////////////////////// // Async Sass render - ////////////////////////////// + /// /////////////////////////// const callback = (error, obj) => { // eslint-disable-line consistent-return if (error) { return errorM(error); @@ -135,9 +135,9 @@ const gulpSass = (options, sync) => transfob((file, enc, cb) => { // eslint-disa gulpSass.compiler.render(opts, callback); } else { - ////////////////////////////// + /// /////////////////////////// // Sync Sass render - ////////////////////////////// + /// /////////////////////////// try { filePush(gulpSass.compiler.renderSync(opts)); } catch (error) { @@ -146,14 +146,14 @@ const gulpSass = (options, sync) => transfob((file, enc, cb) => { // eslint-disa } }); -////////////////////////////// +/// /////////////////////////// // Sync Sass render -////////////////////////////// -gulpSass.sync = options => gulpSass(options, true); +/// /////////////////////////// +gulpSass.sync = (options) => gulpSass(options, true); -////////////////////////////// +/// /////////////////////////// // Log errors nicely -////////////////////////////// +/// /////////////////////////// gulpSass.logError = function logError(error) { const message = new PluginError('sass', error.messageFormatted).toString(); process.stderr.write(`${message}\n`); @@ -164,12 +164,12 @@ module.exports = (compiler) => { if (!compiler || !compiler.render) { const message = new PluginError( PLUGIN_NAME, - '\n' + - 'gulp-sass 5 does not have a default Sass compiler; please set one yourself.\n' + - 'Both the `sass` and `node-sass` packages are permitted.\n' + + '\n' + + 'gulp-sass 5 does not have a default Sass compiler; please set one yourself.\n' + + 'Both the `sass` and `node-sass` packages are permitted.\n' - 'For example, in your gulpfile:\n\n' + - ' var sass = require(\'gulp-sass\')(require(\'sass\'));\n', + + 'For example, in your gulpfile:\n\n' + + ' var sass = require(\'gulp-sass\')(require(\'sass\'));\n', { showProperties: false }, ).toString(); process.stderr.write(`${message}\n`); diff --git a/test/main.js b/test/main.js index 4cdc81ce..d7739a92 100644 --- a/test/main.js +++ b/test/main.js @@ -2,7 +2,6 @@ const should = require('should'); const Vinyl = require('vinyl'); const path = require('path'); const fs = require('fs'); -const sass = require('../index')(require('node-sass')); const rimraf = require('rimraf'); const gulp = require('gulp'); const sourcemaps = require('gulp-sourcemaps'); @@ -11,6 +10,8 @@ const autoprefixer = require('autoprefixer'); const tap = require('gulp-tap'); const globule = require('globule'); +const sass = require('../index')(require('node-sass')); + const createVinyl = (filename, contents) => { const base = path.join(__dirname, 'scss'); const filePath = path.join(base, filename); @@ -23,7 +24,7 @@ const createVinyl = (filename, contents) => { }); }; -const normaliseEOL = str => str.toString('utf8').replace(/\r\n/g, '\n'); +const normaliseEOL = (str) => str.toString('utf8').replace(/\r\n/g, '\n'); describe('test helpers', () => { it('should normalise EOL', (done) => { @@ -224,14 +225,14 @@ describe('gulp-sass -- async compile', () => { it('should work with gulp-sourcemaps', (done) => { const sassFile = createVinyl('inheritance.scss'); - sassFile.sourceMap = '{' + - '"version": 3,' + - '"file": "scss/subdir/multilevelimport.scss",' + - '"names": [],' + - '"mappings": "",' + - '"sources": [ "scss/subdir/multilevelimport.scss" ],' + - '"sourcesContent": [ "@import ../inheritance;" ]' + - '}'; + sassFile.sourceMap = '{' + + '"version": 3,' + + '"file": "scss/subdir/multilevelimport.scss",' + + '"names": [],' + + '"mappings": "",' + + '"sources": [ "scss/subdir/multilevelimport.scss" ],' + + '"sourcesContent": [ "@import ../inheritance;" ]' + + '}'; // Expected sources are relative to file.base const expectedSources = [ @@ -425,14 +426,14 @@ describe('gulp-sass -- sync compile', () => { 'includes/_dogs.sass', ]; - sassFile.sourceMap = '{' + - '"version": 3,' + - '"file": "scss/subdir/multilevelimport.scss",' + - '"names": [],' + - '"mappings": "",' + - '"sources": [ "scss/subdir/multilevelimport.scss" ],' + - '"sourcesContent": [ "@import ../inheritance;" ]' + - '}'; + sassFile.sourceMap = '{' + + '"version": 3,' + + '"file": "scss/subdir/multilevelimport.scss",' + + '"names": [],' + + '"mappings": "",' + + '"sources": [ "scss/subdir/multilevelimport.scss" ],' + + '"sourcesContent": [ "@import ../inheritance;" ]' + + '}'; const stream = sass.sync(); stream.on('data', (cssFile) => { From dd752197c690919c2fc76d82c8da502651d6d1b9 Mon Sep 17 00:00:00 2001 From: EJ Mason <13525251+mxmason@users.noreply.github.com> Date: Thu, 24 Jun 2021 21:00:48 -0700 Subject: [PATCH 13/21] Incorporate previously proposed documentation changes Copied from https://github.com/dlmanning/gulp-sass/pull/694 --- CONTRIBUTING.md | 11 ++++++++--- README.md | 42 ++++++++---------------------------------- 2 files changed, 16 insertions(+), 37 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b4649a1c..f6fd5abc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,10 +1,15 @@ # Contributing to Gulp Sass -Gulp Sass is a very light-weight [Gulp](https://github.com/gulpjs/gulp) wrapper for [`node-sass`](https://github.com/sass/node-sass), which in turn is a Node binding for [`libsass`](https://github.com/sass/libsass), which in turn is a port of [`Sass`](https://github.com/sass/sass). +`gulp-sass` is a very light-weight wrapper around either [Dart Sass][] or [Node Sass][] (which in turn is a Node binding for [LibSass][]. All of these are implementations of the [Sass][] language. + +[Dart Sass]: http://sass-lang.com/dart-sass +[Node Sass]: https://github.com/sass/node-sass +[LibSass]: https://sass-lang.com/libsass +[Sass]: https://sass-lang.com ## Submitting Issues -* Before creating a new issue, perform a [cursory search](https://github.com/issues?utf8=%E2%9C%93&q=repo%3Adlmanning%2Fgulp-sass+repo%3Asass%2Fnode-sass+repo%3Asass%2Flibsass+repo%3Asass%2Fsass+repo%3Asass-eyeglass%2Feyeglass) in the Gulp Sass, Node Sass, Libsass, and main Sass repos to see if a similar issue has already been submitted. Please also refer to our [Common Issues and Their Fixes](https://github.com/dlmanning/gulp-sass/wiki/Common-Issues-and-Their-Fixes) page for some basic troubleshooting. +* Before creating a new issue, perform a [cursory search](https://github.com/issues?utf8=%E2%9C%93&q=repo%3Adlmanning%2Fgulp-sass+repo%3Asass%2Fdart-sass+repo%3Asass%2Fnode-sass+repo%3Asass%2Flibsass+repo%3Asass%2Fsass+repo%3Asass-eyeglass%2Feyeglass) in the Gulp Sass, Dart Sass, Node Sass, Libsass, and main Sass repos to see if a similar issue has already been submitted. Please also refer to our [Common Issues and Their Fixes](https://github.com/dlmanning/gulp-sass/wiki/Common-Issues-and-Their-Fixes) page for some basic troubleshooting. * You can create an issue [here](https://github.com/dlmanning/gulp-sass/issues). Please include as many details as possible in your report. * Issue titles should be descriptive, explaining at the high level what it is about. * Please include the version of `gulp-sass`, Node, and NPM you are using, as well as what operating system you are having a problem on. @@ -60,4 +65,4 @@ When creating creating commits or updating the CHANGELOG, please **start** the c * :arrow_up: `:arrow_up:` when upgrading dependencies * :arrow_down: `:arrow_down:` when downgrading dependencies * :shirt: `:shirt:` when removing linter warnings -* :shipit: `:shipit:` when creating a new release +* :shipit: `:shipit:` when creating a new release \ No newline at end of file diff --git a/README.md b/README.md index c266742a..32da41e5 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ Only [Active LTS and Current releases][1] are supported. # Install ``` -npm install node-sass gulp-sass --save-dev +npm install sass gulp-sass --save-dev ``` # Basic Usage @@ -24,9 +24,7 @@ Something like this will compile your Sass files: 'use strict'; var gulp = require('gulp'); -var sass = require('gulp-sass'); - -sass.compiler = require('node-sass'); +var sass = require('gulp-sass')(require('sass')); gulp.task('sass', function () { return gulp.src('./sass/**/*.scss') @@ -45,9 +43,7 @@ You can also compile synchronously, doing something like this: 'use strict'; var gulp = require('gulp'); -var sass = require('gulp-sass'); - -sass.compiler = require('node-sass'); +var sass = require('gulp-sass')(require('sass')); gulp.task('sass', function () { return gulp.src('./sass/**/*.scss') @@ -60,35 +56,13 @@ gulp.task('sass:watch', function () { }); ``` -You can choose whether to use [Dart Sass][] or [Node Sass][] by setting the `sass.compiler` property. Node Sass will be used by default, but it's strongly recommended that you set it explicitly for forwards-compatibility in case the default ever changes. +## Options + +`gulp-sass` supports both [Dart Sass][] and [Node Sass][]. You choose which one to use by writing either `require('gulp-sass')(require('sass'))` for Dart Sass or `require('gulp-sass')(require('node-sass'))` for Node Sass. One or the other must be passed in. [Dart Sass]: http://sass-lang.com/dart-sass [Node Sass]: https://github.com/sass/node-sass -Note that when using Dart Sass, **synchronous compilation is twice as fast as asynchronous compilation** by default, due to the overhead of asynchronous callbacks. To avoid this overhead, you can use the [`fibers`](https://www.npmjs.com/package/fibers) package to call asynchronous importers from the synchronous code path. To enable this, pass the `Fiber` class to the `fiber` option: - -```javascript -'use strict'; - -var Fiber = require('fibers'); -var gulp = require('gulp'); -var sass = require('gulp-sass'); - -sass.compiler = require('sass'); - -gulp.task('sass', function () { - return gulp.src('./sass/**/*.scss') - .pipe(sass({fiber: Fiber}).on('error', sass.logError)) - .pipe(gulp.dest('./css')); -}); - -gulp.task('sass:watch', function () { - gulp.watch('./sass/**/*.scss', ['sass']); -}); -``` - -## Options - Pass in options just like you would for [Node Sass](https://github.com/sass/node-sass#options); they will be passed along just as if you were using Node Sass. Except for the `data` option which is used by gulp-sass internally. Using the `file` option is also unsupported and results in undefined behaviour that may change without notice. For example: @@ -142,7 +116,7 @@ gulp.task('sass', function () { # Issues -`gulp-sass` is a very light-weight wrapper around either [Dart Sass][] or [Node Sass][] (which in turn is a Node binding for [LibSass][]). Because of this, the issue you're having likely isn't a `gulp-sass` issue, but an issue with one those projects or with [Sass][] as a whole. +`gulp-sass` is a very light-weight wrapper around either [Dart Sass][] or [Node Sass][] (which in turn is a Node binding for [LibSass][]. Because of this, the issue you're having likely isn't a `gulp-sass` issue, but an issue with one those projects or with [Sass][] as a whole. [LibSass]: https://sass-lang.com/libsass [Sass]: https://sass-lang.com @@ -151,4 +125,4 @@ If you have a feature request/question how Sass works/concerns on how your Sass If you're having problems with the options you're passing in, it's likely a Dart Sass or Node Sass issue and you should file your issue with one of those projects. -We may, in the course of resolving issues, direct you to one of these other projects. If we do so, please follow up by searching that project's issue queue (both open and closed) for your problem and, if it doesn't exist, filing an issue with them. +We may, in the course of resolving issues, direct you to one of these other projects. If we do so, please follow up by searching that project's issue queue (both open and closed) for your problem and, if it doesn't exist, filing an issue with them. \ No newline at end of file From 921f4b0e0c192620bb23765f679dcb0cba0293b1 Mon Sep 17 00:00:00 2001 From: EJ Mason <13525251+mxmason@users.noreply.github.com> Date: Thu, 24 Jun 2021 22:13:24 -0700 Subject: [PATCH 14/21] Update document outline, apply copyedits --- README.md | 81 ++++++++++++++++++++++++------------------------------- 1 file changed, 35 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index 32da41e5..710edc83 100644 --- a/README.md +++ b/README.md @@ -4,40 +4,29 @@ Sass plugin for [Gulp](https://github.com/gulpjs/gulp). **_Before filing an issue, please make sure you have [Updated to the latest Gulp Sass](https://github.com/dlmanning/gulp-sass/wiki/Update-to-the-latest-Gulp-Sass) and have gone through our [Common Issues and Their Fixes](https://github.com/dlmanning/gulp-sass/wiki/Common-Issues-and-Their-Fixes) section._** -# Support +## Support Only [Active LTS and Current releases][1] are supported. [1]: https://github.com/nodejs/Release#release-schedule -# Install +## Installation + +To use `gulp-sass`, you must install both `gulp-sass` itself *and* a Sass compiler. `gulp-sass` supports both [Dart Sass][] and [Node Sass][], but Node Sass is [deprecated](https://sass-lang.com/blog/libsass-is-deprecated). We recommend that you use Dart Sass for new projects, and migrate Node Sass projects to Dart Sass when possible. + +Whichever compiler you choose, it's best to install these as dev dependencies: ``` npm install sass gulp-sass --save-dev ``` -# Basic Usage +## Basic usage: render your Sass -Something like this will compile your Sass files: +You need to import `gulp-sass` into your gulpfile and pass it the compiler of your choice. From there, you can call `sass()` inside `gulp.pipe()` to asynchronously render your Sass into CSS. To render your CSS synchronously, you can call `sass.sync()`. -```javascript -'use strict'; - -var gulp = require('gulp'); -var sass = require('gulp-sass')(require('sass')); - -gulp.task('sass', function () { - return gulp.src('./sass/**/*.scss') - .pipe(sass().on('error', sass.logError)) - .pipe(gulp.dest('./css')); -}); - -gulp.task('sass:watch', function () { - gulp.watch('./sass/**/*.scss', ['sass']); -}); -``` +**Note:** With Dart Sass, asynchronous rendering is much slower than synchronous rendering. If you're using Dart Sass, you're better off using synchronous rendering. -You can also compile synchronously, doing something like this: +Rendering your Sass in a Gulp task looks something like this: ```javascript 'use strict'; @@ -45,27 +34,25 @@ You can also compile synchronously, doing something like this: var gulp = require('gulp'); var sass = require('gulp-sass')(require('sass')); -gulp.task('sass', function () { - return gulp.src('./sass/**/*.scss') - .pipe(sass.sync().on('error', sass.logError)) - .pipe(gulp.dest('./css')); -}); + gulp.task('sass', function () { + return gulp.src('./sass/**/*.scss') + .pipe(sass().on('error', sass.logError)) + .pipe(gulp.dest('./css')); + }); -gulp.task('sass:watch', function () { - gulp.watch('./sass/**/*.scss', ['sass']); -}); + gulp.task('sass:watch', function () { + gulp.watch('./sass/**/*.scss', ['sass']); + }); ``` -## Options +## Render with options -`gulp-sass` supports both [Dart Sass][] and [Node Sass][]. You choose which one to use by writing either `require('gulp-sass')(require('sass'))` for Dart Sass or `require('gulp-sass')(require('node-sass'))` for Node Sass. One or the other must be passed in. - -[Dart Sass]: http://sass-lang.com/dart-sass -[Node Sass]: https://github.com/sass/node-sass +To change the final output of your CSS, you can pass an options object to your renderer. `gulp-sass` supports [Node Sass's render options](https://github.com/sass/node-sass#options), with two unsupported exceptions: -Pass in options just like you would for [Node Sass](https://github.com/sass/node-sass#options); they will be passed along just as if you were using Node Sass. Except for the `data` option which is used by gulp-sass internally. Using the `file` option is also unsupported and results in undefined behaviour that may change without notice. +- The `data` option, which is used by `gulp-sass` internally. +- The `file` option, which has undefined behavior that may change without notice. -For example: +For example, the following code will compress the rendered CSS: ```javascript gulp.task('sass', function () { @@ -75,7 +62,7 @@ gulp.task('sass', function () { }); ``` -Or this for synchronous code: +Or this for synchronous rendering: ```javascript gulp.task('sass', function () { @@ -85,9 +72,9 @@ gulp.task('sass', function () { }); ``` -## Source Maps +## Source maps -`gulp-sass` can be used in tandem with [gulp-sourcemaps](https://github.com/floridoo/gulp-sourcemaps) to generate source maps for the Sass to CSS compilation. You will need to initialize [gulp-sourcemaps](https://github.com/floridoo/gulp-sourcemaps) prior to running `gulp-sass` and write the source maps after. +`gulp-sass` can be used in tandem with [`gulp-sourcemaps`](https://github.com/floridoo/gulp-sourcemaps) to generate source maps for the Sass-to-CSS compilation. You will need to initialize `gulp-sourcemaps` _before_ running `gulp-sass`, and write the source maps after. ```javascript var sourcemaps = require('gulp-sourcemaps'); @@ -101,7 +88,7 @@ gulp.task('sass', function () { }); ``` -By default, [gulp-sourcemaps](https://github.com/floridoo/gulp-sourcemaps) writes the source maps inline in the compiled CSS files. To write them to a separate file, specify a path relative to the `gulp.dest()` destination in the `sourcemaps.write()` function. +By default, `gulp-sourcemaps` writes the source maps inline, in the compiled CSS files. To write them to a separate file, specify a path relative to the `gulp.dest()` destination in the `sourcemaps.write()` function. ```javascript var sourcemaps = require('gulp-sourcemaps'); @@ -114,15 +101,17 @@ gulp.task('sass', function () { }); ``` -# Issues +## Issues -`gulp-sass` is a very light-weight wrapper around either [Dart Sass][] or [Node Sass][] (which in turn is a Node binding for [LibSass][]. Because of this, the issue you're having likely isn't a `gulp-sass` issue, but an issue with one those projects or with [Sass][] as a whole. - -[LibSass]: https://sass-lang.com/libsass -[Sass]: https://sass-lang.com +`gulp-sass` is a light-weight wrapper around either [Dart Sass][] or [Node Sass][] (which in turn is a Node binding for [LibSass][]. Because of this, the issue you're having likely isn't a `gulp-sass` issue, but an issue with one those projects or with [Sass][] as a whole. If you have a feature request/question how Sass works/concerns on how your Sass gets compiled/errors in your compiling, it's likely a Dart Sass or LibSass issue and you should file your issue with one of those projects. If you're having problems with the options you're passing in, it's likely a Dart Sass or Node Sass issue and you should file your issue with one of those projects. -We may, in the course of resolving issues, direct you to one of these other projects. If we do so, please follow up by searching that project's issue queue (both open and closed) for your problem and, if it doesn't exist, filing an issue with them. \ No newline at end of file +We may, in the course of resolving issues, direct you to one of these other projects. If we do so, please follow up by searching that project's issue queue (both open and closed) for your problem and, if it doesn't exist, filing an issue with them. + +[Dart Sass]: http://sass-lang.com/dart-sass +[LibSass]: https://sass-lang.com/libsass +[Node Sass]: https://github.com/sass/node-sass +[Sass]: https://sass-lang.com \ No newline at end of file From a5345a173470c44aee01fcb668946de4de8da24f Mon Sep 17 00:00:00 2001 From: EJ Mason <13525251+mxmason@users.noreply.github.com> Date: Thu, 24 Jun 2021 22:27:10 -0700 Subject: [PATCH 15/21] Copyedit: overall clarifications --- README.md | 26 ++++++++++++++++++-------- 1 file changed, 18 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 710edc83..11f927dd 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ npm install sass gulp-sass --save-dev You need to import `gulp-sass` into your gulpfile and pass it the compiler of your choice. From there, you can call `sass()` inside `gulp.pipe()` to asynchronously render your Sass into CSS. To render your CSS synchronously, you can call `sass.sync()`. -**Note:** With Dart Sass, asynchronous rendering is much slower than synchronous rendering. If you're using Dart Sass, you're better off using synchronous rendering. +**⚠️ Note:** With Dart Sass, asynchronous rendering is much slower than synchronous rendering. If you're using Dart Sass, you're better off using synchronous rendering. Rendering your Sass in a Gulp task looks something like this: @@ -34,17 +34,27 @@ Rendering your Sass in a Gulp task looks something like this: var gulp = require('gulp'); var sass = require('gulp-sass')(require('sass')); - gulp.task('sass', function () { + gulp.task('sass', function() { return gulp.src('./sass/**/*.scss') .pipe(sass().on('error', sass.logError)) .pipe(gulp.dest('./css')); }); - gulp.task('sass:watch', function () { + gulp.task('sass:watch', function() { gulp.watch('./sass/**/*.scss', ['sass']); }); ``` +With synchronous rendering, that Gulp task looks like this: + +``` javascript +gulp.task('sass', function() { + return gulp.src('./sass/**/*.scss') + .pipe(sass.sync().on('error', sass.logError)) + .pipe(gulp.dest('./css')); +}); +``` + ## Render with options To change the final output of your CSS, you can pass an options object to your renderer. `gulp-sass` supports [Node Sass's render options](https://github.com/sass/node-sass#options), with two unsupported exceptions: @@ -52,10 +62,10 @@ To change the final output of your CSS, you can pass an options object to your r - The `data` option, which is used by `gulp-sass` internally. - The `file` option, which has undefined behavior that may change without notice. -For example, the following code will compress the rendered CSS: +For example, to compress your CSS, you can call `sass({outputStyle: 'compressed'}`. In the context of a Gulp task, that looks like this: ```javascript -gulp.task('sass', function () { +gulp.task('sass', function() { return gulp.src('./sass/**/*.scss') .pipe(sass({outputStyle: 'compressed'}).on('error', sass.logError)) .pipe(gulp.dest('./css')); @@ -65,7 +75,7 @@ gulp.task('sass', function () { Or this for synchronous rendering: ```javascript -gulp.task('sass', function () { +gulp.task('sass', function() { return gulp.src('./sass/**/*.scss') .pipe(sass.sync({outputStyle: 'compressed'}).on('error', sass.logError)) .pipe(gulp.dest('./css')); @@ -79,7 +89,7 @@ gulp.task('sass', function () { ```javascript var sourcemaps = require('gulp-sourcemaps'); -gulp.task('sass', function () { +gulp.task('sass', function() { return gulp.src('./sass/**/*.scss') .pipe(sourcemaps.init()) .pipe(sass().on('error', sass.logError)) @@ -92,7 +102,7 @@ By default, `gulp-sourcemaps` writes the source maps inline, in the compiled CSS ```javascript var sourcemaps = require('gulp-sourcemaps'); -gulp.task('sass', function () { +gulp.task('sass', function() { return gulp.src('./sass/**/*.scss') .pipe(sourcemaps.init()) .pipe(sass().on('error', sass.logError)) From f02c1c5cb48978f21f55b257543826e9247ee019 Mon Sep 17 00:00:00 2001 From: EJ Mason <13525251+mxmason@users.noreply.github.com> Date: Thu, 24 Jun 2021 23:38:03 -0700 Subject: [PATCH 16/21] Call out migration guide, update badges --- README.md | 35 ++++++++++++++++++++++++++++++++--- 1 file changed, 32 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 11f927dd..bf2238a9 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,10 @@ -# gulp-sass [![Build Status](https://travis-ci.org/dlmanning/gulp-sass.svg?branch=master)](https://travis-ci.org/dlmanning/gulp-sass) [![Join the chat at https://gitter.im/dlmanning/gulp-sass](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/dlmanning/gulp-sass?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![npm version](https://badge.fury.io/js/gulp-sass.svg)](http://badge.fury.io/js/gulp-sass) +# gulp-sass ![Build status](https://img.shields.io/travis/dlmanning/gulp-sass) [![Join the chat at https://gitter.im/dlmanning/gulp-sass](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/dlmanning/gulp-sass?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) ![Node support](https://img.shields.io/node/v/gulp-sass) ![NPM package version](https://img.shields.io/npm/v/gulp-sass?label=npm%20version) Sass plugin for [Gulp](https://github.com/gulpjs/gulp). -**_Before filing an issue, please make sure you have [Updated to the latest Gulp Sass](https://github.com/dlmanning/gulp-sass/wiki/Update-to-the-latest-Gulp-Sass) and have gone through our [Common Issues and Their Fixes](https://github.com/dlmanning/gulp-sass/wiki/Common-Issues-and-Their-Fixes) section._** +**_Before filing an issue, please make sure you have [updated to the latest version of `gulp-sass`](https://github.com/dlmanning/gulp-sass/wiki/Update-to-the-latest-Gulp-Sass) and have gone through our [Common Issues and Their Fixes](https://github.com/dlmanning/gulp-sass/wiki/Common-Issues-and-Their-Fixes) section._** + +**Migrating your existing project to version 5? Please read our (short!) [migration guide](#migrating-to-version-5).** ## Support @@ -24,7 +26,7 @@ npm install sass gulp-sass --save-dev You need to import `gulp-sass` into your gulpfile and pass it the compiler of your choice. From there, you can call `sass()` inside `gulp.pipe()` to asynchronously render your Sass into CSS. To render your CSS synchronously, you can call `sass.sync()`. -**⚠️ Note:** With Dart Sass, asynchronous rendering is much slower than synchronous rendering. If you're using Dart Sass, you're better off using synchronous rendering. +**⚠️ Note:** With Dart Sass, **synchronous rendering is twice as fast as asynchronous rendering**. The Sass team is exploring ways to improve asynchronous rendering with Dart Sass, but for now you will get the best performance from `sass.sync()` Rendering your Sass in a Gulp task looks something like this: @@ -111,6 +113,33 @@ gulp.task('sass', function() { }); ``` +

Migrating to version 5

+ +`gulp-sass` version 5 requires Node 12 or later, and introduces some breaking changes. Additionally, changes in Node itself mean that we should no longer use Node fibers to speed up asynchronous rendering with Dart Sass. + +### Setting a Sass compiler + +As of version 5, `gulp-sass` _does not include a default Sass compiler_, so you must install one (either `node-sass` or `sass`) along with `gulp-sass`. + +``` +npm install sass gulp-sass --save-dev +``` + +Then, you must explicitly set that compiler in your gulpfille. Instead of setting a `compiler` prop on the `gulp-sass` instance, you pass the compiler into a function call when instantiating `gulp-sass`. + +These changes look something like this: + +``` diff +- var sass = require('gulp-sass')); +- var compiler = require('sass'); +- sass.compiler = compiler; ++ var sass = require('gulp-sass')(require('sass')); +``` + +### What about fibers? + +We used to recommend Node fibers as a way to speed up asynchronous rendering with Dart Sass. Unfortunately, [Node fibers are discontinued](https://sass-lang.com/blog/node-fibers-discontinued). The Sass team is exploring ways to improve asynchronous rendering with Dart Sass, but for now you will get the best performance from `sass.sync()`. + ## Issues `gulp-sass` is a light-weight wrapper around either [Dart Sass][] or [Node Sass][] (which in turn is a Node binding for [LibSass][]. Because of this, the issue you're having likely isn't a `gulp-sass` issue, but an issue with one those projects or with [Sass][] as a whole. From 30b37481d8f6ec7359f7736b434d0b0d9abfaffc Mon Sep 17 00:00:00 2001 From: EJ Mason <13525251+mxmason@users.noreply.github.com> Date: Fri, 25 Jun 2021 00:48:50 -0700 Subject: [PATCH 17/21] Document Gulp 4 usage --- README.md | 96 +++++++++++++++++++++++++++++++------------------------ 1 file changed, 55 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index bf2238a9..4beeaf70 100644 --- a/README.md +++ b/README.md @@ -22,13 +22,17 @@ Whichever compiler you choose, it's best to install these as dev dependencies: npm install sass gulp-sass --save-dev ``` -## Basic usage: render your Sass +## Usage -You need to import `gulp-sass` into your gulpfile and pass it the compiler of your choice. From there, you can call `sass()` inside `gulp.pipe()` to asynchronously render your Sass into CSS. To render your CSS synchronously, you can call `sass.sync()`. +**Note:** These examples assume you're using Gulp 4. For examples that work with Gulp 3, [check the docs for an earlier version of `gulp-sass`](https://github.com/dlmanning/gulp-sass/tree/v4.1.1). + +`gulp-sass` runs inside of Gulp tasks. No matter what else you do with `gulp-sass`, you must first import it into your gulpfile, making sure to pass it the compiler of your choice. From there, create a Gulp task that calls either `sass()` (to asynchronously render your CSS), or `sass.sync()` (to render it synchronously). Then, export your task with the `export` keyword. We'll show some examples of how to do that. **⚠️ Note:** With Dart Sass, **synchronous rendering is twice as fast as asynchronous rendering**. The Sass team is exploring ways to improve asynchronous rendering with Dart Sass, but for now you will get the best performance from `sass.sync()` -Rendering your Sass in a Gulp task looks something like this: +### Basic tasks: render your Sass + +Rendering your Sass with a Gulp task looks something like this: ```javascript 'use strict'; @@ -36,28 +40,29 @@ Rendering your Sass in a Gulp task looks something like this: var gulp = require('gulp'); var sass = require('gulp-sass')(require('sass')); - gulp.task('sass', function() { - return gulp.src('./sass/**/*.scss') - .pipe(sass().on('error', sass.logError)) - .pipe(gulp.dest('./css')); - }); +function buildStyles() { + return gulp.src('./sass/**/*.scss') + .pipe(sass().on('error', sass.logError)) + .pipe(gulp.dest('./css')); +}; - gulp.task('sass:watch', function() { - gulp.watch('./sass/**/*.scss', ['sass']); - }); +exports.buildStyles = buildStyles; +exports.watch = function () { + gulp.watch('./sass/**/*.scss', ['sass']); +}; ``` With synchronous rendering, that Gulp task looks like this: ``` javascript -gulp.task('sass', function() { - return gulp.src('./sass/**/*.scss') - .pipe(sass.sync().on('error', sass.logError)) - .pipe(gulp.dest('./css')); -}); +function sassTask() { +return gulp.src('./sass/**/*.scss') + .pipe(sass().on('error', sass.logError)) + .pipe(gulp.dest('./css')); +}; ``` -## Render with options +### Advanced tasks: render with options To change the final output of your CSS, you can pass an options object to your renderer. `gulp-sass` supports [Node Sass's render options](https://github.com/sass/node-sass#options), with two unsupported exceptions: @@ -67,21 +72,25 @@ To change the final output of your CSS, you can pass an options object to your r For example, to compress your CSS, you can call `sass({outputStyle: 'compressed'}`. In the context of a Gulp task, that looks like this: ```javascript -gulp.task('sass', function() { - return gulp.src('./sass/**/*.scss') - .pipe(sass({outputStyle: 'compressed'}).on('error', sass.logError)) - .pipe(gulp.dest('./css')); -}); +function buildStyles() { + return gulp.src('./sass/**/*.scss') + .pipe(sass({outputStyle: 'compressed'}).on('error', sass.logError)) + .pipe(gulp.dest('./css')); +}; + +exports.buildStyles = buildStyles; ``` Or this for synchronous rendering: ```javascript -gulp.task('sass', function() { - return gulp.src('./sass/**/*.scss') - .pipe(sass.sync({outputStyle: 'compressed'}).on('error', sass.logError)) - .pipe(gulp.dest('./css')); -}); +function buildStyles() { + return gulp.src('./sass/**/*.scss') + .pipe(sass.sync({outputStyle: 'compressed'}).on('error', sass.logError)) + .pipe(gulp.dest('./css')); +}; + +exports.buildStyles = buildStyles; ``` ## Source maps @@ -91,26 +100,31 @@ gulp.task('sass', function() { ```javascript var sourcemaps = require('gulp-sourcemaps'); -gulp.task('sass', function() { - return gulp.src('./sass/**/*.scss') - .pipe(sourcemaps.init()) - .pipe(sass().on('error', sass.logError)) - .pipe(sourcemaps.write()) - .pipe(gulp.dest('./css')); -}); +function buildStyles() { + return gulp.src('./sass/**/*.scss') + .pipe(sourcemaps.init()) + .pipe(sass().on('error', sass.logError)) + .pipe(sourcemaps.write()) + .pipe(gulp.dest('./css')); +} + +exports.buildStyles = buildStyles; ``` By default, `gulp-sourcemaps` writes the source maps inline, in the compiled CSS files. To write them to a separate file, specify a path relative to the `gulp.dest()` destination in the `sourcemaps.write()` function. ```javascript var sourcemaps = require('gulp-sourcemaps'); -gulp.task('sass', function() { - return gulp.src('./sass/**/*.scss') - .pipe(sourcemaps.init()) - .pipe(sass().on('error', sass.logError)) - .pipe(sourcemaps.write('./maps')) - .pipe(gulp.dest('./css')); -}); + +function buildStyles() { + return gulp.src('./sass/**/*.scss') + .pipe(sourcemaps.init()) + .pipe(sass().on('error', sass.logError)) + .pipe(sourcemaps.write('./maps')) + .pipe(gulp.dest('./css')); +}; + +exports.buildStyles = buildStyles; ```

Migrating to version 5

From 76a8d8c92d638c7ff1854388e8b274c99bdec145 Mon Sep 17 00:00:00 2001 From: EJ Mason <13525251+mxmason@users.noreply.github.com> Date: Fri, 25 Jun 2021 00:53:49 -0700 Subject: [PATCH 18/21] smol clarification --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 4beeaf70..39ee6083 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ npm install sass gulp-sass --save-dev ### Basic tasks: render your Sass -Rendering your Sass with a Gulp task looks something like this: +To render your CSS with a build task, then watch your files for changes, you might write something like this.: ```javascript 'use strict'; @@ -55,9 +55,9 @@ exports.watch = function () { With synchronous rendering, that Gulp task looks like this: ``` javascript -function sassTask() { +function buildStyles() { return gulp.src('./sass/**/*.scss') - .pipe(sass().on('error', sass.logError)) + .pipe(sass.sync().on('error', sass.logError)) .pipe(gulp.dest('./css')); }; ``` From b57a94c6125c6344c3c34c3bd97d2f6f01b25037 Mon Sep 17 00:00:00 2001 From: EJ Mason <13525251+mxmason@users.noreply.github.com> Date: Fri, 25 Jun 2021 01:08:00 -0700 Subject: [PATCH 19/21] Copyedit some headings --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 39ee6083..ee97b6c8 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,7 @@ npm install sass gulp-sass --save-dev **⚠️ Note:** With Dart Sass, **synchronous rendering is twice as fast as asynchronous rendering**. The Sass team is exploring ways to improve asynchronous rendering with Dart Sass, but for now you will get the best performance from `sass.sync()` -### Basic tasks: render your Sass +### Render your CSS To render your CSS with a build task, then watch your files for changes, you might write something like this.: @@ -62,7 +62,7 @@ return gulp.src('./sass/**/*.scss') }; ``` -### Advanced tasks: render with options +### Render with options To change the final output of your CSS, you can pass an options object to your renderer. `gulp-sass` supports [Node Sass's render options](https://github.com/sass/node-sass#options), with two unsupported exceptions: @@ -93,7 +93,7 @@ function buildStyles() { exports.buildStyles = buildStyles; ``` -## Source maps +### Include a source map `gulp-sass` can be used in tandem with [`gulp-sourcemaps`](https://github.com/floridoo/gulp-sourcemaps) to generate source maps for the Sass-to-CSS compilation. You will need to initialize `gulp-sourcemaps` _before_ running `gulp-sass`, and write the source maps after. From ffddd9d59654e8958e159038d8ae57a094ebea44 Mon Sep 17 00:00:00 2001 From: EJ Mason <13525251+mxmason@users.noreply.github.com> Date: Fri, 25 Jun 2021 01:12:23 -0700 Subject: [PATCH 20/21] =?UTF-8?q?Yet=20Another=20Copyedit=E2=84=A2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ee97b6c8..0c09e0c3 100644 --- a/README.md +++ b/README.md @@ -152,7 +152,7 @@ These changes look something like this: ### What about fibers? -We used to recommend Node fibers as a way to speed up asynchronous rendering with Dart Sass. Unfortunately, [Node fibers are discontinued](https://sass-lang.com/blog/node-fibers-discontinued). The Sass team is exploring ways to improve asynchronous rendering with Dart Sass, but for now you will get the best performance from `sass.sync()`. +We used to recommend Node fibers as a way to speed up asynchronous rendering with Dart Sass. Unfortunately, [Node fibers are discontinued](https://sass-lang.com/blog/node-fibers-discontinued). The Sass team is exploring its optons for future performance improvements, but for now you will get the best performance from `sass.sync()`. ## Issues From bbcac478bfc42ce1ab5adb1ab18430d733d40461 Mon Sep 17 00:00:00 2001 From: Michael Mifsud Date: Fri, 25 Jun 2021 18:38:36 +1000 Subject: [PATCH 21/21] Update README.md --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 0c09e0c3..5e7ed849 100644 --- a/README.md +++ b/README.md @@ -56,9 +56,9 @@ With synchronous rendering, that Gulp task looks like this: ``` javascript function buildStyles() { -return gulp.src('./sass/**/*.scss') - .pipe(sass.sync().on('error', sass.logError)) - .pipe(gulp.dest('./css')); + return gulp.src('./sass/**/*.scss') + .pipe(sass.sync().on('error', sass.logError)) + .pipe(gulp.dest('./css')); }; ``` @@ -167,4 +167,4 @@ We may, in the course of resolving issues, direct you to one of these other proj [Dart Sass]: http://sass-lang.com/dart-sass [LibSass]: https://sass-lang.com/libsass [Node Sass]: https://github.com/sass/node-sass -[Sass]: https://sass-lang.com \ No newline at end of file +[Sass]: https://sass-lang.com