A Metalsmith plugin to compile SASS/SCSS files

Compile SASS/SCSS source & lib files to CSS using dart-sass.

• Automatically compiles all .scss/.sass files in Metalsmith.source() and removes all _partial.scss/sass files from the output.
• Uses sensible defaults according to metalsmith.env('NODE_ENV').
• Add files from outside the source dir with the entries option. Specify 'relative/to/dir/style.scss': 'relative/to/destination/style.css' key-value pairs in the entries object for all root stylesheets.
• Provides sourcemaps and access to all advanced sass options except async.
• Compatible with @metalsmith/postcss (including sourcemaps)

NPM:

npm install @metalsmith/sass

Yarn:

yarn add @metalsmith/sass

Pass @metalsmith/sass to metalsmith.use :

import sass from '@metalsmith/sass'
const isDev = metalsmith.env('NODE_ENV') === 'development'

// compile all scss/sass files in metalsmith.source()
metalsmith.use(sass()) // defaults

metalsmith.use(sass({  // explicit defaults
  style:  isDev ? 'expanded' : 'compressed',
  sourceMap: isDev,
  sourceMapIncludeSources: isDev,
  loadPaths: ['node_modules']
  entries: {
    // add scss entry points from
   'lib/outside-source.scss': 'relative/to/dest.css'
  }
}))

If metalsmith.env('NODE_ENV') is explicitly set to development,@metalsmith/sass will automatically generate sourcemaps and will not minify the output.

If you had a blog project with 2 SCSS stylesheets, index.scss to be loaded everywhere, and blogposts.scss only on blog post pages:

my-blog
├── lib
|   ├── index.scss
│   └── _lib-partial.scss
└── src
    ├── blog.html
    ├── index.html
    └── css
        ├── _in-source-partial.scss
        └── blogposts.scss

...you could specify the following config:

metalsmith.use(
  sass({
    entries: {
      'lib/index.scss': 'css/index.css'
    }
  })
)

Note: the keys in the entries option are relative to Metalsmith.directory, while the values are relative to Metalsmith.destination.

With this setup metalsmith will generate the following build:

build
  ├── css
  │   ├── blogposts.css
  │   └── index.css
  ├── blog.html
  └── index.html

Partial _in-source-partial.scss is automatically removed from the build after compilation. When not explicitly specified in the config, in-source .scss/.sass files are added as entries '<source>/file.scss': <dest>/file.css. If you want to move or rename the in-source SCSS entries in the build, specify them explicitly in the entries config. For example let's write the blogpost.scss to css/blog/index.css instead, without touching our source dir structure:

metalsmith.use(
  sass({
    entries: {
      'lib/index.scss': 'css/index.css',
      'src/blogposts.scss': 'css/blog/index.css'
    }
  })
)

The result:

build
  ├── css
  │   ├── index.css
  │   └── blog
  │       └── index.css
  ├── blog.html
  └── index.html

Sass partials are processed by dart-sass. @metalsmith/sass will gracefully handle in-source partials, but they will be read into memory by Metalsmith. If you don't need to preprocess sass partials with any other metalsmith plugin you can save some disk reads by storing partials outside the source directory, eg:

my-blog
├── lib
│   ├── _partial1.scss
│   └── _partial2.scss
└── src
    └── css
        └── index.scss

You can pass metadata to SASS files inside Metalsmith.source() through front-matter in the file or global metadata. For example, let's pass metalsmith theme metadata to SASS and pre-compile with @metalsmith/in-place and jstransformer-handlebars (notice the final .hbs extension):

index.scss.hbs

---
fontfamily: 'Arial, sans-serif'
---
$color-primary: {{ theme.color.primary }};
$color-background: {{ theme.color.background }};

body {
  font-family: {{ fontfamily }};
  color: $color-primary;
  background-color: $color-background;
}

Just take care to run the in-place plugin before sass:

import Metalsmith from 'metalsmith'
import inPlace from '@metalsmith/in-place'
import sass from '@metalsmith/sass'
import { fileURLToPath } from 'url'
import { dirname } from 'path'

const __dirname = dirname(fileURLToPath(import.meta.url))

Metalsmith(__dirname)
  .metadata({
    theme: {
      color: {
        primary: '#333444',
        background: '#EEEFFF'
      }
    }
  })
  .use(inPlace('jstransformer-handlebars'))
  .use(sass())
  .build((err) => {
    if (err) throw err
    console.log('Success!')
  })

To enable debug logs, set the DEBUG environment variable to @metalsmith/sass*:

metalsmith.env('DEBUG', '@metalsmith/sass*')

Alternatively you can set DEBUG to @metalsmith/* to debug all Metalsmith core plugins.

To use this plugin with the Metalsmith CLI, add @metalsmith/sass to the plugins key in your metalsmith.json file:

{
  "plugins": [
    {
      "@metalsmith/sass": {
        "style": "compressed",
        "sourceMap": false,
        "sourceMapIncludeSources": false,
        "loadPaths": ["node_modules"],
        "entries": {
          "lib/scss/index.scss": "assets/styles.css"
        }
      }
    }
  ]
}

This plugin runs on Node >= 14.18.0. If you need to compile sass/scss on earier Node versions, use metalsmith-sass which uses the (no longer canonical) lib-sass.

LGPL-3.0