@financial-times/dotcom-build-sass v9.4.0

@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

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.