eleventy-plugin-sass

An Eleventy plugin for processing SCSS files with Dart Sass.

Usage

First, add the plugin as a development dependency to your project's package.json file:

npm install --save-dev @jgarber/eleventy-plugin-sass

Next, add the plugin to your project's Eleventy configuration file (e.g. eleventy.config.js):

module.exports = function(eleventyConfig) {
  eleventyConfig.addPlugin(require('@jgarber/eleventy-plugin-sass'));
};

With no additional configuration, eleventy-plugin-sass will process SCSS files in your Eleventy project's input directory (dir.input) and generate CSS files in the output directory (dir.output).

Generated CSS files' permalinks will mimic the input directory's file structure. For example, ./src/assets/stylesheets/app.scss will generate a CSS file at ./_site/assets/stylesheets/app.css. Sass partials (files whose name begins with an underscore) will not generate a corresponding CSS file.

Options

eleventy-plugin-sass supports the following options:

| Name | Type(s) | Default | |:------------------|:--------------------------|:----------------------------------| | sassOptions | Object | { loadPaths: ['node_modules'] } | | templateFormats | Array<String>, String | ['sass', 'scss'] |

module.exports = function(eleventyConfig) {
  eleventyConfig.addPlugin(require('@jgarber/eleventy-plugin-sass'), {
    sassOptions: {
      sourceMap: true,
      style: 'compressed'
    },
    templateFormats: 'scss'
  });
};

Refer to the Sass JavaScript API documentation (specifically, the Options documentation) for details.

[!NOTE] Enabling source maps with sourceMap: true will also automatically set sourceMapIncludeSources: true. Currently, this plugin supports inlined source maps only.

Custom Functions

eleventy-plugin-sass supports configuring Custom Functions through Sass' JavaScript API with one notable caveat. User-supplied configuration must use the same instance of the Sass parser that this plugin uses. The standard Object-based options argument will not have a reference to this instance.

To bridge this gap, eleventy-plugin-sass accepts a function as a second argument to Eleventy's addPlugin function:

eleventyConfig.addPlugin(require('@jgarber/eleventy-plugin-sass'), function(sass) {
  return {
    sassOptions: {
      functions: {
        'font-url($path)': function(args) {
          const path = args[0].assertString('path').text;

          return new sass.SassString(`url("/assets/fonts/${path}")`, {
            quotes: false
          });
        }
      }
    },
    templateFormats: 'scss'
  };
});

[!WARNING] In the usage above, your configuration function must accept a single argument (sass, in the example above). Declaring Custom Functions using this plugin's default Object options style will result in hard-to-debug errors.

A configuration function like the one above should return an Object conforming to this plugin's available options (noted in the table above!).

ESM Support

Eleventy v3.0.0 added bundler-free ESM support. This plugin works with either ESM or CommonJS projects!

import sassPlugin from '@jgarber/eleventy-plugin-sass';

export default async function(eleventyConfig) {
  eleventyConfig.addPlugin(sassPlugin);
}

Acknowledgments

First and foremost, eleventy-plugin-sass wouldn't be possible without Zach Leatherman's incredible work creating Eleventy and his stewardship of its community.

eleventy-plugin-sass is written and maintained by Jason Garber.