@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, then sends the output through to the postcss-loader for optimisations, and finally the css-loader. 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 has been configured to find packages installed with npm by looking in the 'node_modules/@financial-times' directories. 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')] })

Please note that by default Sass will resolve all bare @import statements from the current working directory rather than relative to the file being processed. This means it will not find dependencies in nested node_modules directories.

PostCSS is configured with the Autoprefixer and cssnano transforms.

The CSS loader has @import and url() resolution disabled as these should be handled by Sass.

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	See https://webpack.js.org/loaders/sass-loader/#implementation

additionalData replaces prependData as of sass-loader v9. prependData is still supported in this package, but is deprecated.

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.