sass-loader 16.0.7 → 17.0.0

package/README.md

@@ -43,7 +43,7 @@ pnpm add -D sass-loader sass webpack
 >
 > To enable CSS processing in your project, you need to install [style-loader](https://webpack.js.org/loaders/style-loader/) and [css-loader](https://webpack.js.org/loaders/css-loader/) via `npm i style-loader css-loader`.
 
-`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).
+`sass-loader` requires you to install either [Dart Sass](https://github.com/sass/dart-sass) or [Sass Embedded](https://github.com/sass/embedded-host-node) on your own (more documentation can be found below).
 
 This allows you to control the versions of all your dependencies and to choose which Sass implementation to use.
 
@@ -51,10 +51,6 @@ This allows you to control the versions of all your dependencies and to choose w
 >
 > We highly recommend using [Sass Embedded](https://github.com/sass/embedded-host-node) or [Dart Sass](https://github.com/sass/dart-sass).
 
-> [!WARNING]
->
-> [Node Sass](https://github.com/sass/node-sass) does not work with [Yarn PnP](https://classic.yarnpkg.com/en/docs/pnp/) and doesn't support [@use rule](https://sass-lang.com/documentation/at-rules/use).
-
 Chain the `sass-loader` with the [css-loader](https://github.com/webpack/css-loader) and the [style-loader](https://github.com/webpack/style-loader) to immediately apply all styles to the DOM, or with the [mini-css-extract-plugin](https://github.com/webpack/mini-css-extract-plugin) to extract it into a separate file.
 
 Then add the loader to your webpack configuration. For example:
@@ -99,9 +95,9 @@ module.exports = {
 
 Finally run `webpack` via your preferred method (e.g., via CLI or an npm script).
 
-### The `style` (new API, by default since 16 version) and `outputStyle` (old API) options in `production` mode
+### The `style` option in `production` mode
 
-For `production` mode, the `style` (new API, by default since 16 version) and `outputStyle` (old API) options default to `compressed` unless otherwise specified in `sassOptions`.
+For `production` mode, the `style` option defaults to `compressed` unless otherwise specified in `sassOptions`.
 
 ### Resolving `import` and `use` at-rules
 
@@ -167,7 +163,7 @@ Default: `sass`
 The special `implementation` option determines which implementation of Sass to use.
 
 By default, the loader resolves the implementation based on your dependencies.
-Just add the desired implementation to your `package.json` (`sass`, `sass-embedded`, or `node-sass` package) and install dependencies.
+Just add the desired implementation to your `package.json` (`sass` or `sass-embedded` package) and install dependencies.
 
 Example where the `sass-loader` uses the `sass` (`dart-sass`) implementation:
 
@@ -182,19 +178,6 @@ Example where the `sass-loader` uses the `sass` (`dart-sass`) implementation:
 }
 ```
 
-Example where the `sass-loader` uses the `node-sass` implementation:
-
-**package.json**
-
-```json
-{
-  "devDependencies": {
-    "sass-loader": "^7.2.0",
-    "node-sass": "^5.0.0"
-  }
-}
-```
-
 Example where the `sass-loader` uses the `sass-embedded` implementation:
 
 **package.json**
@@ -219,7 +202,6 @@ Be aware of the order that `sass-loader` will resolve the implementation:
 
 1. `sass-embedded`
 2. `sass`
-3. `node-sass`
 
 You can specify a specific implementation by using the `implementation` option, which accepts one of the above values.
 
@@ -283,17 +265,17 @@ Type:
 
 ```ts
 type sassOptions =
-  | import("sass").LegacyOptions<"async">
+  | import("sass").StringOptionsWithImporter<"async">
   | ((
       content: string | Buffer,
       loaderContext: LoaderContext,
       meta: any,
-    ) => import("sass").LegacyOptions<"async">);
+    ) => import("sass").StringOptionsWithImporter<"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.
+Options for [Dart Sass](http://sass-lang.com/dart-sass) or [Sass Embedded](https://github.com/sass/embedded-host-node) implementation.
 
 > [!NOTE]
 >
@@ -301,25 +283,18 @@ Options for [Dart Sass](http://sass-lang.com/dart-sass) or [Node Sass](https://g
 
 > [!NOTE]
 >
-> The `syntax` (new API, by default since 16 version) and `indentedSyntax` (old API) option is `scss` for the `scss` extension, `indented` for the `sass` extension, and `css` for the `css` extension.
-
-> [!NOTE]
->
-> Options such as `data` and `file` are unavailable and will be ignored.
-
-> ℹ We strongly discourage changing the `sourceMap` (new API, by default since 16 version), `outFile` (old API), `sourceMapContents` (old API), `sourceMapEmbed` (old API), and `sourceMapRoot` (old API) options because `sass-loader` sets these automatically when the `sourceMap` option is `true`.
+> The `syntax` option is `scss` for the `scss` extension, `indented` for the `sass` extension, and `css` for the `css` extension.
 
 > [!NOTE]
 >
-> Access to the [loader context](https://webpack.js.org/api/loaders/#the-loader-context) inside the custom importer can be done using the `this.webpackLoaderContext` property.
+> Options such as `data` and `url` are unavailable and will be ignored.
 
-There is a slight difference between the options for `sass` (`dart-sass`) and `node-sass`.
+> ℹ We strongly discourage changing the `sourceMap` option because `sass-loader` sets it automatically when the `sourceMap` option is `true`.
 
 Please consult their respective documentation before using them:
 
 - [Dart Sass documentation](https://sass-lang.com/documentation/js-api/interfaces/Options) for all available `sass` options.
-- [Sass Embedded documentation](https://github.com/sass/embedded-host-node) for all available `sass` options.
-- [Node Sass documentation](https://github.com/sass/node-sass/#options) for all available `node-sass` options.
+- [Sass Embedded documentation](https://github.com/sass/embedded-host-node) for all available `sass-embedded` options.
 
 #### `object`
 
@@ -407,7 +382,7 @@ Enables/disables generation of source maps.
 By default generation of source maps depends on the [`devtool`](https://webpack.js.org/configuration/devtool/) option.
 All values enable source map generation except `eval` and `false`.
 
-> ℹ If `true`, the `sourceMap` (new API, by default since 16 version), `outFile` (old API), `sourceMapContents` (old API), `sourceMapEmbed` (old API), and `sourceMapRoot` (old API) from `sassOptions` will be ignored.
+> ℹ If `true`, the `sourceMap` option from `sassOptions` will be ignored.
 
 **webpack.config.js**
 
@@ -438,10 +413,6 @@ module.exports = {
 };
 ```
 
-> ℹ In some rare cases `node-sass` can output invalid source maps (this is a `node-sass` bug).
->
-> In order to avoid this, you can try to update `node-sass` to the latest version, or you can try to set within `sassOptions` the `outputStyle` option to `compressed`.
-
 **webpack.config.js**
 
 ```js
@@ -458,7 +429,7 @@ module.exports = {
             options: {
               sourceMap: true,
               sassOptions: {
-                outputStyle: "compressed",
+                style: "compressed",
               },
             },
           },
@@ -593,7 +564,7 @@ Default: `true`
 Enables/disables the default webpack importer.
 
 This can improve performance in some cases, though use it with caution because aliases and `@import` at-rules starting with `~` will not work.
-You can pass your own `importer` to solve this (see [`importer` docs](https://github.com/sass/node-sass#importer--v200---experimental)).
+You can pass your own `importer` to solve this (see [Sass importer documentation](https://sass-lang.com/documentation/js-api/interfaces/LegacyImporter)).
 
 **webpack.config.js**
 
@@ -686,20 +657,22 @@ module.exports = {
 Type:
 
 ```ts
-type api = "legacy" | "modern" | "modern-compiler";
+type api = "auto" | "modern" | "modern-compiler";
 ```
 
-Default: `"modern"` for `sass` (`dart-sass`) and `sass-embedded`, or `"legacy"` for `node-sass`
+Default: `"auto"` for `sass` (`dart-sass`) and `sass-embedded`
 
-Allows you to switch between the `legacy` and `modern` APIs. You can find more information [here](https://sass-lang.com/documentation/js-api). The `modern-compiler` option enables the modern API with support for [Shared Resources](https://github.com/sass/sass/blob/main/accepted/shared-resources.d.ts.md).
+Allows you to switch between the `modern` and `modern-compiler` APIs. You can find more information [here](https://sass-lang.com/documentation/js-api). The `modern-compiler` option enables the modern API with support for [Shared Resources](https://github.com/sass/sass/blob/main/accepted/shared-resources.d.ts.md).
+
+When `"auto"` is used, the loader picks `"modern-compiler"` whenever the implementation exposes `initAsyncCompiler` (i.e. recent versions of `sass` and `sass-embedded`) and falls back to `"modern"` otherwise. Combined with `sass-embedded`, this yields the best build performance out of the box.
 
 > [!NOTE]
 >
-> Using `modern-compiler` and `sass-embedded` together significantly improves performance and decreases build time. We strongly recommend their use. We will enable them by default in a future major release.
+> Using `modern-compiler` and `sass-embedded` together significantly improves performance and decreases build time. They are now selected automatically by the default `"auto"` API.
 
-> [!WARNING]
+> [!NOTE]
 >
-> The Sass options are different for the `legacy` and `modern` APIs. Please look at [docs](https://sass-lang.com/documentation/js-api) to learn how to migrate to the modern options.
+> The legacy Sass JS API is no longer supported. If you were using `api: "legacy"`, please migrate to the modern API. See the [Sass JS API docs](https://sass-lang.com/documentation/js-api) to learn how to migrate.
 
 **webpack.config.js**
 

package/dist/cjs/index.js

@@ -0,0 +1,78 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _nodePath = _interopRequireDefault(require("node:path"));
+var _nodeUrl = _interopRequireDefault(require("node:url"));
+var _options = _interopRequireDefault(require("./options.json"));
+var _utils = require("./utils.js");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/** @typedef {import("webpack").LoaderContext<LoaderOptions>} LoaderContext */
+/** @typedef {import("schema-utils/declarations/validate").Schema} Schema */
+/** @typedef {import("./utils.js").LoaderOptions} LoaderOptions */
+/** @typedef {import("./utils.js").SassError} SassError */
+
+/**
+ * The sass-loader makes dart-sass and sass-embedded available to webpack modules.
+ * @this {LoaderContext}
+ * @param {string} content content
+ * @returns {Promise<void>} loader result
+ */
+async function loader(content) {
+  const options = this.getOptions(/** @type {Schema} */_options.default);
+  const callback = this.async();
+  let implementation;
+  try {
+    implementation = await (0, _utils.getSassImplementation)(options.implementation);
+  } catch (error) {
+    callback(/** @type {Error} */error);
+    return;
+  }
+  const useSourceMap = typeof options.sourceMap === "boolean" ? options.sourceMap : this.sourceMap === true;
+  const sassOptions = await (0, _utils.getSassOptions)(this, options, content, useSourceMap);
+  const shouldUseWebpackImporter = typeof options.webpackImporter === "boolean" ? options.webpackImporter : true;
+  if (shouldUseWebpackImporter) {
+    sassOptions.importers.push((0, _utils.getModernWebpackImporter)(this));
+  }
+  let compile;
+  try {
+    compile = (0, _utils.getCompileFn)(this, implementation, options.api);
+  } catch (error) {
+    callback(/** @type {Error} */error);
+    return;
+  }
+  let result;
+  try {
+    result = await compile(sassOptions);
+  } catch (error) {
+    const sassError = /** @type {SassError} */error;
+
+    // There are situations when the `span.url` property does not exist
+    if (sassError.span && typeof sassError.span.url !== "undefined") {
+      this.addDependency(_nodeUrl.default.fileURLToPath(sassError.span.url));
+    }
+    callback((0, _utils.errorFactory)(sassError));
+    return;
+  }
+  let map = result.sourceMap || undefined;
+
+  // Modify source paths only for webpack, otherwise we do nothing
+  if (map && useSourceMap) {
+    map = (0, _utils.normalizeSourceMap)(map, this.rootContext);
+  }
+  if (typeof result.loadedUrls !== "undefined") {
+    for (const includedFile of result.loadedUrls.filter(loadedUrl => loadedUrl.protocol === "file:")) {
+      const normalizedIncludedFile = _nodeUrl.default.fileURLToPath(includedFile);
+
+      // Custom `importer` can return only `contents` so includedFile will be relative
+      if (_nodePath.default.isAbsolute(normalizedIncludedFile)) {
+        this.addDependency(normalizedIncludedFile);
+      }
+    }
+  }
+  callback(null, result.css.toString(), map || undefined);
+}
+var _default = exports.default = loader;module.exports = exports.default;
+module.exports.default = exports.default;

package/dist/{options.json → cjs/options.json}

@@ -15,12 +15,12 @@
       ]
     },
     "api": {
-      "description": "Switch between old and modern API for `sass` (`Dart Sass`) and `Sass Embedded` implementations.",
+      "description": "Switch between `auto`, `modern` and `modern-compiler` API for `sass` (`Dart Sass`) and `Sass Embedded` implementations.",
       "link": "https://github.com/webpack/sass-loader#sassoptions",
-      "enum": ["legacy", "modern", "modern-compiler"]
+      "enum": ["auto", "modern", "modern-compiler"]
     },
     "sassOptions": {
-      "description": "Options for `node-sass` or `sass` (`Dart Sass`) implementation.",
+      "description": "Options for `sass` (`Dart Sass`) or `sass-embedded` implementation.",
       "link": "https://github.com/webpack/sass-loader#sassoptions",
       "anyOf": [
         {

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}