better-sass-loader

Fork of fast-sass-loader updated for Webpack 3.

Features:

• 5~10 times faster than sass-loader in large sass project
• support sass file dedupe, never worry about @ import same file in different place
• support url resolve, never worry about the problem with url(...) (see https://github.com/webpack-contrib/sass-loader#problems-with-url)

better-sass-loader for Webpack 3. 5~10 times faster than sass-loader, and support url resolve. Majority of this comes from fast-sass-loader, but updated for use with Webpack 3.

vs sass-loader

| Features | better-sass-loader | sass-loader | |---------------|------------------|-----------------------------------------| | Performance | Fast (5~10 times)| Slow | | Sass Dedupe | ✓ | × | | Url Resolve | ✓ | × (need resolve-url-loader, it's buggy) | | Loader Config | × | ✓ | | Source Map | × | ✓ | | Internal Cache| ✓ | × |

Performance

performance benchmark:

************** RUN WITH BETTER SASS LOADER **************
Hash: 5a4a04caf3b4ae519987
Version: webpack 3.2.0
Time: 7457ms
        Asset     Size  Chunks                    Chunk Names
dist/index.js  2.67 kB       0  [emitted]         index
    index.css   627 kB       0  [emitted]  [big]  index
   [0] ./index.scss 41 bytes {0} [built]
   [1] ../~/.0.23.1@css-loader/lib/css-base.js 1.51 kB [built]
Child extract-text-webpack-plugin:
       [0] ../~/.0.23.1@css-loader/lib/css-base.js 1.51 kB {0} [built]
       [1] ../~/.0.23.1@css-loader!../lib!./index.scss 648 kB {0} [built]

[build] better-sass-loader: 9348.760ms


************** RUN WITH SASS LOADER **************
Hash: 0b034e431d1a93826d38
Version: webpack 3.2.0
Time: 64124ms
        Asset     Size  Chunks                    Chunk Names
dist/index.js  2.67 kB       0  [emitted]         index
    index.css  6.95 MB       0  [emitted]  [big]  index
   [0] ./index.scss 41 bytes {0} [built]
   [1] ../~/.0.23.1@css-loader/lib/css-base.js 1.51 kB [built]
Child extract-text-webpack-plugin:
       [0] ../~/.0.23.1@css-loader/lib/css-base.js 1.51 kB {0} [built]
       [1] ../~/.0.23.1@css-loader!../~/.6.0.3@sass-loader/lib/loader.js!./index.scss 7.18 MB {0} [built]

[build] sass-loader: 64892.699ms

Since the sass-loader doesn't dedupe repeated sass files, the result will be very very large (6.95MB!!!), and the total compile time takes 64.9 seconds (nearly 6 times longer than better-sass-loader).

Why better-sass-loader is faster than sass-loader ?

1. Support sass file dedupe, so node-sass won't compile same file repeatedly, the performance improvement is significant when your sass files number grows very large.
2. Before node-sass compile, better-sass-loader will merge all sass files into a single file, so node-sass only need to compile one large file, it's faster than @importer of libsass.
3. The internal cache will store all result for every entry, only compile sass when related file changed.

Install

install by npm:

npm install fast-sass-loader --save-dev

and you need install node-sass and webpack as peer dependencies.

Usage

{
  module: {
    rules: [
      {
        test: /\.(scss|sass)$/,
        use: [
          { loader: 'css-loader',
            options: {
              ...
              }
          },
          { loader: 'postcss-loader' },
          {
            loader: 'better-sass-loader',
            options: {
              includePaths: [ ... ]
            }
          }
        ]
      },
    ]
  }
}

Options

includePaths:

An array of paths that node-sass can look in to attempt to resolve your @import declarations. When using data, it is recommended that you use this.

data:

If you want to prepend Sass code before the actual entry file, you can set the data option. In this case, the loader will not override the data option but just append the entry's content. This is especially useful when some of your Sass variables depend on the environment:

{
    loader: "better-sass-loader",
    options: {
        data: "$env: " + process.env.NODE_ENV + ";"
    }
}

Please note: Since you're injecting code, this will break the source mappings in your entry file. Often there's a simpler solution than this.

Warning

Mixing import .scss and.sass file is not allowed

Since better-sass-loader will parse @import and merge all files into single sass file, you cannot import .scss file from .sass (or opposite).

For example:

// file: entry.scss
@import "path/to/file.sass";  // cannot import `path/to/file.sass` in a `.scss` file

body {
  background: #FFF;
}

Avoid same variable name in different sass files

Since better-sass-loader will dedupe sass file, later imported file will be ignored. Using same variable name in different sass fill would produce unexpected output.

For example (compile entry.scss with better-sass-loader):

// a.scss
$foobar: #000;

// b.scss
@import "a.scss";
$foobar: #AAA;

h1 { color: $foobar; }

// entry.scss
@import "b.scss";
@import "a.scss"; // this file will be ignore: $foobar === #AAA

h2 { color: $foobar; }

// will output:
// h1 { color: #AAA; }
// h2 { color: #AAA; }