grunt-sass-modern

Compile SASS to CSS using Dart Sass

This is a fork of the original grunt-sass repository which required a small update as per this issue after Dart SASS started emitting the following deprecation warning starting with version 1.79.0:

Deprecation Warning: The legacy JS API is deprecated and will be removed in Dart Sass 2.0.0. More info: https://sass-lang.com/d/legacy-js-api

Since the author of the original repository did not provide a fix and still a lot o projects are relying on it, a fix was created by Matt Robinson via this commit, and I decided to fork the main repository, add the fix to it and also update this page about what you can do to properly update your code and not just silence the warning.

This version also fixes broken source map generation which was not working in the original grunt-sass since probably Dart Sass version 1.48.0 but I can't tell for sure the version where it broke - please let me know if you know better.

Install

If you are already using the original grunt-sass, edit your package.json file and look for something like

"grunt-sass": "^3.1.0",

...and delete that.

Afterwards, call

$ npm install --save-dev grunt-sass-modern

...to install the updated version

Usage

In your Gruntfile.js, in the sass section, you need to add the api entry to the options part, and set its value to "modern":

module.exports = function(grunt) {

    const sass = require('sass');

    grunt.initConfig({
        sass: {
            options: {
                implementation: sass,
                sourceMap: true,    // broken in "grunt-sass" for versions of SASS newer than 1.48.0
                api: 'modern'       // this is required starting with Dart-Sass 1.79.0
                                    // (and only working with grunt-sass-modern)
            },
            dist: {
                files: {
                    'destination.css': 'source.scss'
                }
            }
        }
    });

    // remember to also update this from "grunt-sass" to "grunt-sass-modern"!
    grunt.loadNpmTasks('grunt-sass-modern');
    grunt.registerTask('default', ['sass']);

}

Silencing the warning

If for whatever reason you are not able to update your code and you just want to silence the warning as in the example below

module.exports = function(grunt) {

    const sass = require('sass');

    grunt.initConfig({
        sass: {
            options: {
                implementation: sass,
                sourceMap: true,
                silenceDeprecations: ['legacy-js-api']	// this is needed in order to silence the deprecation warning
            },
            dist: {
                files: {
                    'destination.css': 'source.scss'
                }
            }
        }
    });

    grunt.loadNpmTasks('grunt-sass-modern');
    grunt.registerTask('default', ['sass']);

}

Heads-up regarding the sourceMap attribute

Note that in the original repo, sourceMap generation is broken and it is fixed in grunt-sass-modern.

The caviat is that the newer versions of Sass do not add a sourceMappingURL comment to the generated CSS by default!

Excerpt from their docs:

Sass doesn't automatically add a sourceMappingURL comment to the generated CSS. It's up to callers to do that, since callers have full knowledge of where the CSS and the source map will exist in relation to one another and how they'll be served to the browser.

grunt-sass-modern fixes this by automatically adding the sourceMappingURL comment to your compiled CSS, and making the sourceMap option work as it used to in legacy mode of Sass:

module.exports = function(grunt) {

    const sass = require('sass');

    grunt.initConfig({
        sass: {
            options: {
                implementation: sass,

                // use it like this to create the map where destination.css resides
                // (and write the sourceMappingURL comment in to the destination.css)
                sourceMap: true,

                // use it like this to create the map at given path
                // (and write the sourceMappingURL comment in to the destination.css)
                sourceMap: 'path/to/map',

                files: {
                    'destination.css': 'source.scss'
                }
            }
        }
    });

    grunt.loadNpmTasks('grunt-sass-modern');
    grunt.registerTask('default', ['sass']);

}

Options

See the Dart Sass options.

For more information please refer to the original grunt-sass repository.