@financial-times/dotcom-build-sass

@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.