sass-loader 12.2.0 → 12.6.0

package/README.md

@@ -27,7 +27,19 @@ To begin, you'll need to install `sass-loader`:
 npm install sass-loader sass webpack --save-dev
 ```
 
-`sass-loader` requires you to install either [Dart Sass](https://github.com/sass/dart-sass) or [Node Sass](https://github.com/sass/node-sass) on your own (more documentation can be found below).
+or
+
+```console
+yarn add -D sass-loader sass webpack
+```
+
+or
+
+```console
+pnpm add -D sass-loader sass webpack
+```
+
+`sass-loader` requires you to install either [Dart Sass](https://github.com/sass/dart-sass), [Node Sass](https://github.com/sass/node-sass) on your own (more documentation can be found below) or [Sass Embedded](https://github.com/sass/embedded-host-node).
 
 This allows you to control the versions of all your dependencies, and to choose which Sass implementation to use.
 
@@ -35,6 +47,8 @@ This allows you to control the versions of all your dependencies, and to choose
 
 > ⚠ [Node Sass](https://github.com/sass/node-sass) does not work with [Yarn PnP](https://classic.yarnpkg.com/en/docs/pnp/) feature and doesn't support [@use rule](https://sass-lang.com/documentation/at-rules/use).
 
+> ⚠ [Sass Embedded](https://github.com/sass/embedded-host-node) is experimental and in `beta`, therefore some features may not work
+
 Chain the `sass-loader` with the [css-loader](https://github.com/webpack-contrib/css-loader) and the [style-loader](https://github.com/webpack-contrib/style-loader) to immediately apply all styles to the DOM or the [mini-css-extract-plugin](https://github.com/webpack-contrib/mini-css-extract-plugin) to extract it into a separate file.
 
 Then add the loader to your Webpack configuration. For example:
@@ -119,17 +133,21 @@ Thankfully there are a two solutions to this problem:
 
 ## Options
 
-|                   Name                    |         Type         |                 Default                 | Description                                                       |
-| :---------------------------------------: | :------------------: | :-------------------------------------: | :---------------------------------------------------------------- |
-|  **[`implementation`](#implementation)**  |  `{Object\|String}`  |                 `sass`                  | Setup Sass implementation to use.                                 |
-|     **[`sassOptions`](#sassoptions)**     | `{Object\|Function}` | defaults values for Sass implementation | Options for Sass.                                                 |
-|       **[`sourceMap`](#sourcemap)**       |     `{Boolean}`      |           `compiler.devtool`            | Enables/Disables generation of source maps.                       |
-|  **[`additionalData`](#additionaldata)**  | `{String\|Function}` |               `undefined`               | Prepends/Appends `Sass`/`SCSS` code before the actual entry file. |
-| **[`webpackImporter`](#webpackimporter)** |     `{Boolean}`      |                 `true`                  | Enables/Disables the default Webpack importer.                    |
+- **[`implementation`](#implementation)**
+- **[`sassOptions`](#sassoptions)**
+- **[`sourceMap`](#sourcemap)**
+- **[`additionalData`](#additionaldata)**
+- **[`webpackImporter`](#webpackimporter)**
+- **[`warnRuleAsWarning`](#warnruleaswarning)**
 
 ### `implementation`
 
-Type: `Object | String`
+Type:
+
+```ts
+type implementation = object | string;
+```
+
 Default: `sass`
 
 The special `implementation` option determines which implementation of Sass to use.
@@ -168,7 +186,7 @@ In order to avoid this situation you can use the `implementation` option.
 
 The `implementation` options either accepts `sass` (`Dart Sass`) or `node-sass` as a module.
 
-#### Object
+#### `object`
 
 For example, to use Dart Sass, you'd pass:
 
@@ -195,7 +213,7 @@ module.exports = {
 };
 ```
 
-#### String
+#### `string`
 
 For example, to use Dart Sass, you'd pass:
 
@@ -301,7 +319,18 @@ module.exports = {
 
 ### `sassOptions`
 
-Type: `Object|Function`
+Type:
+
+```ts
+type sassOptions =
+  | import("sass").LegacyOptions<"async">
+  | ((
+      content: string | Buffer,
+      loaderContext: LoaderContext,
+      meta: any
+    ) => import("sass").LegacyOptions<"async">);
+```
+
 Default: defaults values for Sass implementation
 
 Options for [Dart Sass](http://sass-lang.com/dart-sass) or [Node Sass](https://github.com/sass/node-sass) implementation.
@@ -323,9 +352,9 @@ Please consult documentation before using them:
 - [Dart Sass documentation](https://github.com/sass/dart-sass#javascript-api) for all available `sass` options.
 - [Node Sass documentation](https://github.com/sass/node-sass/#options) for all available `node-sass` options.
 
-#### `Object`
+#### `object`
 
-Use and object for the Sass implementation setup.
+Use an object for the Sass implementation setup.
 
 **webpack.config.js**
 
@@ -354,7 +383,7 @@ module.exports = {
 };
 ```
 
-#### `Function`
+#### `function`
 
 Allows to setup the Sass implementation by setting different options based on the loader context.
 
@@ -396,7 +425,12 @@ module.exports = {
 
 ### `sourceMap`
 
-Type: `Boolean`
+Type:
+
+```ts
+type sourceMap = boolean;
+```
+
 Default: depends on the `compiler.devtool` value
 
 Enables/Disables generation of source maps.
@@ -468,7 +502,14 @@ module.exports = {
 
 ### `additionalData`
 
-Type: `String|Function`
+Type:
+
+```ts
+type additionalData =
+  | string
+  | ((content: string | Buffer, loaderContext: LoaderContext) => string);
+```
+
 Default: `undefined`
 
 Prepends `Sass`/`SCSS` code before the actual entry file.
@@ -476,7 +517,7 @@ In this case, the `sass-loader` will not override the `data` option but just **p
 
 This is especially useful when some of your Sass variables depend on the environment:
 
-#### `String`
+#### `string`
 
 ```js
 module.exports = {
@@ -500,7 +541,7 @@ module.exports = {
 };
 ```
 
-#### `Function`
+#### `function`
 
 ##### Sync
 
@@ -572,7 +613,12 @@ module.exports = {
 
 ### `webpackImporter`
 
-Type: `Boolean`
+Type:
+
+```ts
+type webpackImporter = boolean;
+```
+
 Default: `true`
 
 Enables/Disables the default Webpack importer.
@@ -604,6 +650,113 @@ module.exports = {
 };
 ```
 
+### `warnRuleAsWarning`
+
+Type:
+
+```ts
+type warnRuleAsWarning = boolean;
+```
+
+Default: `false`
+
+Treats the `@warn` rule as a webpack warning.
+
+> ℹ️ It will be `true` by default in the next major release.
+
+**style.scss**
+
+```scss
+$known-prefixes: webkit, moz, ms, o;
+
+@mixin prefix($property, $value, $prefixes) {
+  @each $prefix in $prefixes {
+    @if not index($known-prefixes, $prefix) {
+      @warn "Unknown prefix #{$prefix}.";
+    }
+
+    -#{$prefix}-#{$property}: $value;
+  }
+  #{$property}: $value;
+}
+
+.tilt {
+  // Oops, we typo'd "webkit" as "wekbit"!
+  @include prefix(transform, rotate(15deg), wekbit ms);
+}
+```
+
+The presented code will throw webpack warning instead logging.
+
+To ignore unnecessary warnings you can use the [ignoreWarnings](https://webpack.js.org/configuration/other-options/#ignorewarnings) option.
+
+**webpack.config.js**
+
+```js
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.s[ac]ss$/i,
+        use: [
+          "style-loader",
+          "css-loader",
+          {
+            loader: "sass-loader",
+            options: {
+              warnRuleAsWarning: true,
+            },
+          },
+        ],
+      },
+    ],
+  },
+};
+```
+
+### `api`
+
+Type:
+
+```ts
+type api = "legacy" | "modern";
+```
+
+Default: `"legacy"`
+
+Allows you to switch between `legacy` and `modern` API. You can find more information [here](https://sass-lang.com/documentation/js-api).
+
+> ⚠ "modern" API is experimental, so some features may not work (known: built-in `importer` is not working and files with errors is not watching on initial run), you can follow this [here](https://github.com/webpack-contrib/sass-loader/issues/774).
+
+> ⚠ The sass options are different for `modern` and `old` APIs. Please look at [docs](https://sass-lang.com/documentation/js-api) how to migrate on new options.
+
+**webpack.config.js**
+
+```js
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.s[ac]ss$/i,
+        use: [
+          "style-loader",
+          "css-loader",
+          {
+            loader: "sass-loader",
+            options: {
+              api: "modern",
+              sassOptions: {
+                // Your sass options
+              },
+            },
+          },
+        ],
+      },
+    ],
+  },
+};
+```
+
 ## Examples
 
 ### Extracts CSS into separate files

package/dist/SassError.js

@@ -8,14 +8,19 @@ exports.default = void 0;
 class SassError extends Error {
   constructor(sassError) {
     super();
-    this.name = "SassError";
+    this.name = "SassError"; // TODO remove me in the next major release
+
     this.originalSassError = sassError;
-    this.loc = {
-      line: sassError.line,
-      column: sassError.column
-    }; // Keep original error if `sassError.formatted` is unavailable
 
-    this.message = `${this.name}: ${this.originalSassError.message}`;
+    if (typeof sassError.line !== "undefined" || typeof sassError.column !== "undefined") {
+      this.loc = {
+        line: sassError.line,
+        column: sassError.column
+      };
+    } // Keep original error if `sassError.formatted` is unavailable
+
+
+    this.message = `${this.name}: ${typeof this.originalSassError.message !== "undefined" ? this.originalSassError.message : this.originalSassError}`;
 
     if (this.originalSassError.formatted) {
       this.message = `${this.name}: ${this.originalSassError.formatted.replace(/^Error: /, "")}`; // Instruct webpack to hide the JS stack from the console.

package/dist/SassWarning.js

@@ -0,0 +1,25 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+
+class SassWarning extends Error {
+  constructor(warning, options) {
+    super(warning);
+    this.name = "SassWarning";
+    this.hideStack = true;
+
+    if (options.span) {
+      this.loc = {
+        line: options.span.start.line,
+        column: options.span.start.column
+      };
+    }
+  }
+
+}
+
+var _default = SassWarning;
+exports.default = _default;

package/dist/index.js

@@ -5,6 +5,8 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.default = void 0;
 
+var _url = _interopRequireDefault(require("url"));
+
 var _path = _interopRequireDefault(require("path"));
 
 var _options = _interopRequireDefault(require("./options.json"));
@@ -36,31 +38,57 @@ async function loader(content) {
   const shouldUseWebpackImporter = typeof options.webpackImporter === "boolean" ? options.webpackImporter : true;
 
   if (shouldUseWebpackImporter) {
-    const {
-      includePaths
-    } = sassOptions;
-    sassOptions.importer.push((0, _utils.getWebpackImporter)(this, implementation, includePaths));
+    const isModernAPI = options.api === "modern";
+
+    if (!isModernAPI) {
+      const {
+        includePaths
+      } = sassOptions;
+      sassOptions.importer.push((0, _utils.getWebpackImporter)(this, implementation, includePaths));
+    } else {
+      sassOptions.importers.push((0, _utils.getModernWebpackImporter)(this, implementation));
+    }
   }
 
-  const render = (0, _utils.getRenderFunctionFromSassImplementation)(implementation);
-  render(sassOptions, (error, result) => {
-    if (error) {
-      // There are situations when the `file` property do not exist
-      if (error.file) {
-        // `node-sass` returns POSIX paths
-        this.addDependency(_path.default.normalize(error.file));
-      }
-
-      callback(new _SassError.default(error));
-      return;
+  const compile = (0, _utils.getCompileFn)(implementation, options);
+  let result;
+
+  try {
+    result = await compile(sassOptions, options);
+  } catch (error) {
+    // There are situations when the `file`/`span.url` property do not exist
+    // Modern API
+    if (error.span && typeof error.span.url !== "undefined") {
+      this.addDependency(_url.default.fileURLToPath(error.span.url));
+    } // Legacy API
+    else if (typeof error.file !== "undefined") {
+      // `node-sass` returns POSIX paths
+      this.addDependency(_path.default.normalize(error.file));
     }
 
-    let map = result.map ? JSON.parse(result.map) : null; // Modify source paths only for webpack, otherwise we do nothing
+    callback(new _SassError.default(error));
+    return;
+  }
+
+  let map = // Modern API, then legacy API
+  result.sourceMap ? result.sourceMap : result.map ? JSON.parse(result.map) : null; // Modify source paths only for webpack, otherwise we do nothing
+
+  if (map && useSourceMap) {
+    map = (0, _utils.normalizeSourceMap)(map, this.rootContext);
+  } // Modern API
 
-    if (map && useSourceMap) {
-      map = (0, _utils.normalizeSourceMap)(map, this.rootContext);
-    }
 
+  if (typeof result.loadedUrls !== "undefined") {
+    result.loadedUrls.forEach(includedFile => {
+      const normalizedIncludedFile = _url.default.fileURLToPath(includedFile); // Custom `importer` can return only `contents` so includedFile will be relative
+
+
+      if (_path.default.isAbsolute(normalizedIncludedFile)) {
+        this.addDependency(normalizedIncludedFile);
+      }
+    });
+  } // Legacy API
+  else if (typeof result.stats !== "undefined" && typeof result.stats.includedFiles !== "undefined") {
     result.stats.includedFiles.forEach(includedFile => {
       const normalizedIncludedFile = _path.default.normalize(includedFile); // Custom `importer` can return only `contents` so includedFile will be relative
 
@@ -69,8 +97,9 @@ async function loader(content) {
         this.addDependency(normalizedIncludedFile);
       }
     });
-    callback(null, result.css.toString(), map);
-  });
+  }
+
+  callback(null, result.css.toString(), map);
 }
 
 var _default = loader;

package/dist/options.json

@@ -14,6 +14,11 @@
         }
       ]
     },
+    "api": {
+      "description": "Switch between old and modern API for `sass` (`Dart Sass`) and `Sass Embedded` implementations.",
+      "link": "https://github.com/webpack-contrib/sass-loader#sassoptions",
+      "enum": ["legacy", "modern"]
+    },
     "sassOptions": {
       "description": "Options for `node-sass` or `sass` (`Dart Sass`) implementation.",
       "link": "https://github.com/webpack-contrib/sass-loader#sassoptions",
@@ -48,6 +53,11 @@
       "description": "Enables/Disables default `webpack` importer.",
       "link": "https://github.com/webpack-contrib/sass-loader#webpackimporter",
       "type": "boolean"
+    },
+    "warnRuleAsWarning": {
+      "description": "Treats the '@warn' rule as a webpack warning.",
+      "link": "https://github.com/webpack-contrib/sass-loader#warnruleaswarning",
+      "type": "boolean"
     }
   },
   "additionalProperties": false