@financial-times/dotcom-build-sass

This package exports a Webpack plugin to configure it with a way to load and generate CSS files from Sass source code.

Getting started

This package is compatible with Node 12+ and is distributed on npm.

npm install --save-dev @financial-times/dotcom-build-sass

After installing the package you must add it to the list of plugins in your project's webpack.config.js configuration file:

+ const { PageKitSassPlugin } = require('@financial-times/dotcom-build-sass')

module.exports = {
  plugins: [
+    new PageKitSassPlugin()
  ]
}

Once setup, this plugin will enable you to use Sass files (.scss and .sass) as entry points into your source code.

const { PageKitSassPlugin } = require('@financial-times/dotcom-build-sass')

module.exports = {
   entry: {
      styles: path/to/styles.scss
   },
   plugins: [new PageKitSassPlugin()]
}

Scope

This plugin adds a rule to the Webpack configuration to handle .scss files. It first uses the sass-loader to transpile Sass source code. It will then process the CSS using the same logic as @financial-times/dotcom-build-css. So we'll first call css-loader to handle the native CSS files that have been generated. The CSS is optimised using css-minimizer-webpack-plugin, which runs cssnano under the hood. The mini-css-extract-plugin is added to generate .css files and the webpack-fix-style-only-entries to clean up any empty JavaScript bundles.

Sass supports both relative paths and paths that can be resolved within your node_modules. It can be configured to look in additional locations by passing the relevant paths to the plugin as absolute paths.

new PageKitSassPlugin({ includePaths: [path.resolve('./path-to-sass-files')] })

The CSS loader has url() resolution disabled as we don't use, nor recommend, the function currently.

Options

Option	Type	Default	Description
`webpackImporter`	Boolean	`false`	See https://github.com/webpack-contrib/sass-loader#webpackimporter
`additionalData`	String	`''`	https://webpack.js.org/loaders/sass-loader/#additionaldata
`includePaths`	String[]	`[]`	See https://sass-lang.com/documentation/js-api#includepaths
`implementation`	`sass\|sass-embedded`	`sass-embedded`	See documentation (we'll `require` the passed string first)

Sass build monitoring

Sass build times are stored locally and remotely, where your project sets relevant API keys. Alternatively, you may turn both these features off using environment variable.

Local reporting: A running total of your local Sass build times are stored in a temporary file on your machine. This statistic is reported periodically for your interest, along with a prompt to support FT efforts to move away from Sass.
Alongside this, your local Sass build times are sent to the biz-ops metrics api, provided the below environment variables are set.

Environment Variable	Required	Default	Description
`FT_SASS_STATS_NOTICE`	no	`throttle`	How often to log Sass statistics out to terminal. One of `throttle`, `never`, `always`
`FT_SASS_STATS_NOTICE_THROTTLE_SECONDS`	no	`1800`	How many seconds to wait between logging Sass statistics out to terminal.
`FT_SASS_STATS_NOTICE_THROTTLE_PERCENTAGE`	no	`30`	A percentage increase in total Sass build time in which to log out statistics to the terminal regardless of time.
`FT_SASS_STATS_MONITOR`	no	`off`	Set to `on` to send Sass build time statistics to biz-ops metrics api Requires `FT_SASS_BIZ_OPS_API_KEY` and `FT_SASS_BIZ_OPS_SYSTEM_CODE`.
`FT_SASS_BIZ_OPS_API_KEY`	no	``	A Biz-Ops Metrics API Key for your system.
`FT_SASS_BIZ_OPS_SYSTEM_CODE`	no	``	The biz-ops system code of your project. Use `page-kit` if your system does not have a biz-ops code yet.