metalsmith@metalsmith/sass
A Metalsmith plugin to compile SASS/SCSS files
Compile SASS/SCSS source & lib files to CSS using dart-sass.
Features
- Automatically compiles all .scss/.sass files in
Metalsmith.source()and removes all_partial.scss/sassfiles from the output. - Uses sensible defaults according to
metalsmith.env('NODE_ENV'). - Add files from outside the source dir with the
entriesoption. Specify'relative/to/dir/style.scss': 'relative/to/destination/style.css'key-value pairs in theentriesobject for all root stylesheets. - Provides sourcemaps and access to all advanced sass options except async.
- Compatible with @metalsmith/postcss (including sourcemaps)
Installation
NPM:
npm install @metalsmith/sass
Yarn:
yarn add @metalsmith/sass
Usage
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.
Entries
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
@import/ @use partials
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
Passing metadata to SASS files
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!')
})
Debug
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.
CLI usage
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"
}
}
}
]
}
Node compatibility
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.