What problem does this address?

In the wp-scripts package the includePaths property for the sass-loader is difficult to modify, yet necessary for more complex SASS architecture that relies on dependent packages. The only solution I’ve found is to use webpack-merge to add the includePaths option and pass an array of paths to packages in my node_modules folder so that the SASS compiler can find sass partials we load from other packages.

A little background:
In our large multi-network, multi-site environment we build and maintain 100+ WP child themes for the thousands of sites in our university network. As a part of that structure we have a custom SASS based CSS framework that is loaded as a node package dependency into a child theme. This lets us then import sass partials for common structural components (grid, typography, various layout styles, etc) and compile them directly into the child theme’s stylesheet.

We try to avoid long absolute style paths such ../../node_modules/@bostonuniversity/burf-base/_config.scss. In our old build process we used grunt and node-sass. There was an option in the gruntfile to set the paths that node-sass would look at to find partials so that we could reference them like so in our scss files: @import "burf-base/config";

Example from a grunt config file:

sass: {
	options: {
		outputStyle: 'compressed',
		implementation: sass,
		sourceMap: true,
		indentType: 'space',
		indentWidth: 2,
		precision: '5',
		includePaths: [
			'node_modules/normalize-scss/sass',
			'node_modules/mathsass/dist/',
			'node_modules/@bostonuniversity',
		],
	},

We are evaluating migrating our build process to wp-scripts and our current SASS fails to compile because those sass partials loaded from node_modules can’t be found unless we put in a full path. That is not ideal and can lead to issues later.

The sass-loader in the webpack.config.js file can support an includePaths property under sassOptions for an array of paths to be checked for sass partials. See an example here.

I have managed to use webpack-merge to customize our webpack.config and build upon the default one provided by wp-scripts but it was quite challenging to figure out and could be a big roadblock for developers switching over to wp-scripts.

const customIncludePaths = [
	'./node_modules/normalize-scss/sass',
	'./node_modules/mathsass/dist/',
	'./node_modules/@bostonuniversity'
];

const themeConfig = {
    // Set devtool mode to sourcemap so we generate sourcemap files even for production builds.
    devtool: 'source-map',
    entry: {
        ...themeEntryPoints
    },
    output: {
        path: path.resolve(__dirname, 'css'), // Output theme assets to /css folder.
    },
    module: {
        rules: [
            {
                test: /\.(sc|sa)ss$/,
                use: [
                    {
                        loader: require.resolve( 'css-loader' ),
                        options: {
                            sourceMap: true, // Set sourceMap to true so we generate a map even for prod builds.
                        },
                    },
                    {
                        loader: require.resolve( 'sass-loader' ),
                        options: {
                            sassOptions: {
                                includePaths: customIncludePaths,
                            },
                            sourceMap: true, // Set sourceMap to true so we generate a map even for prod builds.
                        },
                    },
                ],
            }
        ],
    },
    plugins: [
        new RemoveEmptyScriptsPlugin(), // Removes empty script files for CSS only entries.
    ]
}

and then merged with webpack-merge:

mergeWithRules({
        entry: "merge",
        output: "replace",
        module: {
            rules: {
                test: "match",
                use: {
                    loader: "match",
                    options: "merge",
                },
            },
        },
        plugins: "append"
    })(defaultConfig, themeConfig),

What is your proposed solution?

Provide some mechanism in wp-scripts to pass an array of paths to the includePaths property of the sass-loader without the complexity of modifying the config file, or at least provide some documentation and code examples of how to do it by modifying the webpack config.