Merge pull request SharePoint#8732 from andrewconnell/new-sass-config

📜 add article on configuring SASS for spfx

Author: andrewconnell

docs/spfx/toolchain/configure-sass.md

@@ -0,0 +1,47 @@
+---
+title: Configure SASS processing during builds
+description: In this article, you'll learn how to configure the SASS processing during builds of your SharePoint Framework (SPFx) projects.
+ms.date: 01/27/2023
+ms.localizationpriority: high
+---
+
+# Configure SASS processing during builds
+
+In this article, you'll learn how to configure the SASS processing during builds of your SharePoint Framework (SPFx) projects.
+
+## Updating the toolchain to use a modern SASS processor
+
+The SPFx v1.15 changed the SASS processor the build toolchain used to transpile CSS files from the NPM package [node-sass](https://www.npmjs.com/package/node-sass) to [sass](https://www.npmjs.com/package/sass). The **sass** package is a pure JavaScript implementation of the now-deprecated **dart-sass** package.
+
+This change was primarily made because the [**node-sass** package was deprecated back in 2018](https://sass-lang.com/blog/libsass-is-deprecated), but the **sass** package is also much faster than the **node-sass** package it replaced.
+
+## Impacts of the change
+
+However, changes in the CSS Language required developers to rethink of some of the SASS language paradigms to make it clearer for developers, what a CSS definition is, and what needs to processed by SASS.
+
+When the SPFx toolchain was changed to use the new SASS processor, it required some changes to the SASS code in default SPFx projects as the new processor flagged some syntax errors to address some outdated SASS syntax. These changes introduced some deprecation warnings from the new SASS processor.
+
+Other developers had already dealt with these same deprecation warnings in their projects by getting the SASS package maintainers to add capability to suppress warnings caused by dependencies.
+
+In other words, they needed a way to silence warnings caused by dependencies you don’t own or code potentially that’s inside your SPFx web part. This also happens even to partial files in the same SPFx package.
+
+However, because the **sass** package is added as part of the toolchain, it wasn't easy to configure the processor to silence these deprecations.
+
+## How to silence deprecation warnings in the SASS processor
+
+To address this, all SPFx projects starting with v1.16.1 now include a new file: **./config/sass.json**.
+
+If you have deprecation warnings coming from SASS files you don't maintain in your project, and thus, you have no control over, you can add `"quietDeps": true` to this file to configure the **sass** processor to suppress all deprecation warnings.
+
+```json
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/heft/sass.schema.json",
+  "quietDeps": true
+}
+```
+
+## See also
+
+- [SharePoint Framework v1.16.1 release notes](../release-1.16.1.md)
+- [Stefan Bauer: What’s new with SASS in SPFx 1.16.0](https://n8d.at/whats-new-with-sass-in-spfx-1-16-0)\
+- [Andrew Connell: Unboxing the SharePoint Framework (SPFx) v1.16.1 release](https://www.voitanos.io/blog/sharepoint-framework-v1-16-1-whats-in-latest-update-of-spfx/)

docs/toc.yml

@@ -428,6 +428,8 @@
       href: spfx/toolchain/sharepoint-framework-toolchain.md
     - name: Yeoman generator for the SharePoint Framework
       href: spfx/yeoman-generator-for-spfx-intro.md
+    - name: Configure SASS processing during builds
+      href: spfx/toolchain/configure-sass.md
     - name: Microsoft Graph Toolkit
       href: spfx/use-microsoft-graph-toolkit.md
   - name: Debugging
@@ -455,7 +457,7 @@
     - name: SharePoint 2019 & SE support
       href: spfx/sharepoint-2019-support.md
     - name: SharePoint 2016 support
-      href: spfx/sharepoint-2016-support.md      
+      href: spfx/sharepoint-2016-support.md
   - name: Release notes & roadmap
     items:
     - name: Overview