feat: add api "auto" and use it by default (#1319)

Author: alexander-akait

.changeset/auto-api-default.md

@@ -0,0 +1,5 @@
+---
+"sass-loader": major
+---
+
+Add `"auto"` to the `api` option and make it the default. When the Sass implementation supports the modern compiler, `"auto"` enables it and reuses a single long-running compiler across files, which significantly improves build performance; otherwise it falls back to the `modern` API.

README.md

@@ -657,16 +657,18 @@ module.exports = {
 Type:
 
 ```ts
-type api = "modern" | "modern-compiler";
+type api = "auto" | "modern" | "modern-compiler";
 ```
 
-Default: `"modern"` for `sass` (`dart-sass`) and `sass-embedded`
+Default: `"auto"` for `sass` (`dart-sass`) and `sass-embedded`
 
 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.
 
 > [!NOTE]
 >

src/index.js

@@ -35,7 +35,6 @@ async function loader(content) {
 
   const useSourceMap =
     typeof options.sourceMap === "boolean" ? options.sourceMap : this.sourceMap;
-  const apiType = typeof options.api === "undefined" ? "modern" : options.api;
   const sassOptions = await getSassOptions(
     this,
     options,
@@ -59,7 +58,7 @@ async function loader(content) {
   let compile;
 
   try {
-    compile = getCompileFn(this, implementation, apiType);
+    compile = getCompileFn(this, implementation, options.api);
   } catch (error) {
     callback(error);
     return;

src/options.json

@@ -15,9 +15,9 @@
       ]
     },
     "api": {
-      "description": "Switch between `modern` and `modern-compiler` 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": ["modern", "modern-compiler"]
+      "enum": ["auto", "modern", "modern-compiler"]
     },
     "sassOptions": {
       "description": "Options for `sass` (`Dart Sass`) or `sass-embedded` implementation.",

src/utils.js

@@ -585,11 +585,15 @@ const sassModernCompilers = new WeakMap();
  * Verifies that the implementation and version of Sass is supported by this loader.
  * @param {LoaderContext} loaderContext loader context
  * @param {SassImplementation} implementation sass implementation
- * @param {"modern" | "modern-compiler"} apiType api type
+ * @param {"auto" | "modern" | "modern-compiler" | undefined} apiType api type
  * @returns {SassCompileFunction} compile function
  */
-function getCompileFn(loaderContext, implementation, apiType) {
-  if (apiType === "modern-compiler") {
+function getCompileFn(loaderContext, implementation, apiType = "auto") {
+  if (
+    apiType === "modern-compiler" ||
+    (apiType === "auto" &&
+      typeof implementation.initAsyncCompiler === "function")
+  ) {
     return async (sassOptions) => {
       const webpackCompiler = loaderContext._compiler;
       const { data, ...rest } = sassOptions;

test/__snapshots__/implementation-option.test.js.snap

@@ -20,6 +20,14 @@ exports[`implementation option 'sass-embedded', 'modern-compiler' API: errors 1`
 
 exports[`implementation option 'sass-embedded', 'modern-compiler' API: warnings 1`] = `[]`;
 
+exports[`implementation option auto API falls back to modern when initAsyncCompiler is absent: errors 1`] = `[]`;
+
+exports[`implementation option auto API falls back to modern when initAsyncCompiler is absent: warnings 1`] = `[]`;
+
+exports[`implementation option not specify with auto API: errors 1`] = `[]`;
+
+exports[`implementation option not specify with auto API: warnings 1`] = `[]`;
+
 exports[`implementation option not specify with modern API: errors 1`] = `[]`;
 
 exports[`implementation option not specify with modern API: warnings 1`] = `[]`;

test/__snapshots__/validate-options.test.js.snap

@@ -14,24 +14,24 @@ exports[`validate options should throw an error on the "additionalData" option w
 exports[`validate options should throw an error on the "api" option with "legacy" value 1`] = `
 "Invalid options object. Sass Loader has been initialized using an options object that does not match the API schema.
  - options.api should be one of these:
-   "modern" | "modern-compiler"
-   -> Switch between \`modern\` and \`modern-compiler\` API for \`sass\` (\`Dart Sass\`) and \`Sass Embedded\` implementations.
+   "auto" | "modern" | "modern-compiler"
+   -> Switch between \`auto\`, \`modern\` and \`modern-compiler\` API for \`sass\` (\`Dart Sass\`) and \`Sass Embedded\` implementations.
    -> Read more at https://github.com/webpack/sass-loader#sassoptions"
 `;
 
 exports[`validate options should throw an error on the "api" option with "string" value 1`] = `
 "Invalid options object. Sass Loader has been initialized using an options object that does not match the API schema.
  - options.api should be one of these:
-   "modern" | "modern-compiler"
-   -> Switch between \`modern\` and \`modern-compiler\` API for \`sass\` (\`Dart Sass\`) and \`Sass Embedded\` implementations.
+   "auto" | "modern" | "modern-compiler"
+   -> Switch between \`auto\`, \`modern\` and \`modern-compiler\` API for \`sass\` (\`Dart Sass\`) and \`Sass Embedded\` implementations.
    -> Read more at https://github.com/webpack/sass-loader#sassoptions"
 `;
 
 exports[`validate options should throw an error on the "api" option with "true" value 1`] = `
 "Invalid options object. Sass Loader has been initialized using an options object that does not match the API schema.
  - options.api should be one of these:
-   "modern" | "modern-compiler"
-   -> Switch between \`modern\` and \`modern-compiler\` API for \`sass\` (\`Dart Sass\`) and \`Sass Embedded\` implementations.
+   "auto" | "modern" | "modern-compiler"
+   -> Switch between \`auto\`, \`modern\` and \`modern-compiler\` API for \`sass\` (\`Dart Sass\`) and \`Sass Embedded\` implementations.
    -> Read more at https://github.com/webpack/sass-loader#sassoptions"
 `;
 

test/implementation-option.test.js

@@ -149,15 +149,77 @@ describe("implementation option", () => {
     expect(getWarnings(stats)).toMatchSnapshot("warnings");
     expect(getErrors(stats)).toMatchSnapshot("errors");
 
-    expect(sassEmbeddedSpyModernAPI).toHaveBeenCalledTimes(1);
+    // Default is `auto`, which prefers `modern-compiler` when the
+    // implementation exposes `initAsyncCompiler` (sass-embedded does).
+    expect(sassEmbeddedCompilerSpies.compileStringSpy).toHaveBeenCalledTimes(1);
+    expect(sassEmbeddedSpyModernAPI).not.toHaveBeenCalled();
+    expect(dartSassSpyModernAPI).not.toHaveBeenCalled();
+    expect(dartSassCompilerSpies.compileStringSpy).not.toHaveBeenCalled();
+
+    sassEmbeddedCompilerSpies.mockClear();
+    sassEmbeddedSpyModernAPI.mockClear();
+    dartSassSpyModernAPI.mockClear();
+
+    await close(compiler);
+  });
+
+  it("not specify with auto API", async () => {
+    const testId = getTestId("language", "scss");
+    const options = {
+      api: "auto",
+    };
+    const compiler = getCompiler(testId, { loader: { options } });
+    const stats = await compile(compiler);
+    const { css, sourceMap } = getCodeFromBundle(stats, compiler);
+
+    expect(css).toBeDefined();
+    expect(sourceMap).toBeUndefined();
+
+    expect(getWarnings(stats)).toMatchSnapshot("warnings");
+    expect(getErrors(stats)).toMatchSnapshot("errors");
+
+    expect(sassEmbeddedCompilerSpies.compileStringSpy).toHaveBeenCalledTimes(1);
+    expect(sassEmbeddedSpyModernAPI).not.toHaveBeenCalled();
     expect(dartSassSpyModernAPI).not.toHaveBeenCalled();
+    expect(dartSassCompilerSpies.compileStringSpy).not.toHaveBeenCalled();
 
+    sassEmbeddedCompilerSpies.mockClear();
     sassEmbeddedSpyModernAPI.mockClear();
     dartSassSpyModernAPI.mockClear();
 
     await close(compiler);
   });
 
+  it("auto API falls back to modern when initAsyncCompiler is absent", async () => {
+    const testId = getTestId("language", "scss");
+    const fakeImplementation = {
+      ...dartSass,
+      initAsyncCompiler: undefined,
+    };
+    const options = {
+      api: "auto",
+      implementation: fakeImplementation,
+    };
+    const compiler = getCompiler(testId, { loader: { options } });
+    const stats = await compile(compiler);
+    const { css, sourceMap } = getCodeFromBundle(stats, compiler);
+
+    expect(css).toBeDefined();
+    expect(sourceMap).toBeUndefined();
+
+    expect(getWarnings(stats)).toMatchSnapshot("warnings");
+    expect(getErrors(stats)).toMatchSnapshot("errors");
+
+    expect(dartSassSpyModernAPI).toHaveBeenCalledTimes(1);
+    expect(dartSassCompilerSpies.compileStringSpy).not.toHaveBeenCalled();
+    expect(sassEmbeddedSpyModernAPI).not.toHaveBeenCalled();
+    expect(sassEmbeddedCompilerSpies.compileStringSpy).not.toHaveBeenCalled();
+
+    dartSassSpyModernAPI.mockClear();
+
+    await close(compiler);
+  });
+
   it("not specify with modern API", async () => {
     const testId = getTestId("language", "scss");
     const options = {

test/validate-options.test.js

@@ -37,7 +37,7 @@ describe("validate options", () => {
       failure: ["string"],
     },
     api: {
-      success: ["modern", "modern-compiler"],
+      success: ["auto", "modern", "modern-compiler"],
       failure: ["legacy", "string", true],
     },
     unknown: {