metalsmith-dart-sass

Dart Sass plugin for Metalsmith.

Install

npm install metalsmith-dart-sass

CLI Usage

Install via npm and then add the metalsmith-dart-sass key to your metalsmith.json plugin, like so:

metalsmith.json

{
  "plugins": {
    "metalsmith-dart-sass": true
  }
}

If you need to specify an options, set the options to the value of the metalsmith-dart-sass key.

metalsmith.json

{
  "plugins": {
    "metalsmith-dart-sass": {
      "sassOptions": {
        "sourceMap": true
      }
    }
  }
}

Or, set the filepath of the script file that exports options to the value of the metalsmith-dart-sass key.

metalsmith.json

{
  "plugins": {
    "metalsmith-dart-sass": "./metalsmith-sass-options.js"
  }
}

metalsmith-sass-options.js

module.exports = {
  sassOptions: {
    sourceMap: true
  }
};

If you want to use the files variable or the default options value, you can specify the callback function that generates the options in script file.

metalsmith.json

{
  "plugins": {
    "metalsmith-dart-sass": "./metalsmith-sass-options.js"
  }
}

metalsmith-sass-options.js

module.exports = (files, metalsmith, defaultOptions) => {
  return {
    pattern: [...defaultOptions.pattern, '!**/_*/**'],
  };
};

See Metalsmith CLI for more details.

Javascript Usage

The simplest use is to omit the option.

const sass = require('metalsmith-dart-sass');

metalsmith
  .use(sass());

If you need to specify an options, set the options value.

const sass = require('metalsmith-dart-sass');

metalsmith
  .use(sass({
    sassOptions: {
      sourceMap: true
    }
  }));

If you want to use the files variable or the default options value, you can specify the callback function that generates the options.

const sass = require('metalsmith-dart-sass');

metalsmith
  .use(sass(
    (files, metalsmith, defaultOptions) => {
      return {
        pattern: [...defaultOptions.pattern, '!**/_*/**'],
      };
    }
  ));

TypeScript Usage

For compatibility with the Metalsmith CLI, this package exports single function in CommonJS style.
When using with TypeScript, it is better to use the import = require() statement.

import sass = require('metalsmith-dart-sass');

metalsmith
  .use(sass());

Options

The default value for options are defined like this:

const path = require('path');

{
  /**
   * Partial files whose names begin with an underscore should be excluded from conversion.
   * @see https://sass-lang.com/guide#topic-4
   */
  pattern: ['**/*.sass', '**/*.scss', '!**/_*'],
  sassOptions: {},
  renamer(filename) {
    const newFilename = path.basename(filename, path.extname(filename)) + '.css';
    return path.join(path.dirname(filename), newFilename);
  },
  dependenciesKey: false,
}

pattern

Only files that match this pattern will be processed. Specify a glob expression string or an array of glob expression strings as the pattern.

Pattern are verified using multimatch v4.0.0.

Default value (source):

['**/*.sass', '**/*.scss', '!**/_*']

Type definition (source line 36 / source line 82):

string | string[]

sassOptions

Specify Dart Sass options. There are three ways to specify options:

• Plain objects with SASS options defined
• Functions that return SASS options
• Filepath string of the script that exports objects and functions

Default value (source):

{}

Type definition (source line 37 - 47 / source line 83 - 86):

import Metalsmith from 'metalsmith'; // @types/[email protected]
import sass from 'sass'; // @types/[email protected]

type InputSassImporter =
    | string
    | Record<string, unknown>
    | sass.Importer;

type InputSassFunctionsValue =
    | string
    | Record<string, unknown>
    | Required<sass.Options>['functions'][string];

interface InputSassOptionsInterface
    extends Omit<
        sass.Options,
        'indentedSyntax' | 'sourceMap' | 'importer' | 'functions'
    > {
    indentedSyntax?: string | string[];
    sourceMap?: Exclude<
        Required<sass.Options>['sourceMap'],
        string
    >;
    importer?: InputSassImporter | InputSassImporter[];
    functions?: Record<string, InputSassFunctionsValue>;
}

type SassOptionsFunction = (context: {
    filename: string;
    filedata: object;
    sourceFileFullpath: string;
    destinationFileFullpath: string;
    metalsmith: Metalsmith;
    metalsmithFiles: Metalsmith.Files;
    pluginOptions: object;
}) => sass.Options | Promise<sass.Options>;

string | InputSassOptionsInterface | SassOptionsFunction;

plain object of SASS options

Specify Dart Sass options with an object. All options except the following properties are the same as Dart Sass.

• indentedSyntax

  Set the glob pattern of the file to be interpreted as the indented syntax (SASS syntax). Pattern are verified using multimatch v4.0.0.

  For example, if you want a file with extension .x-sass to be interpreted as SASS syntax, set as follows:

  const sass = require('metalsmith-dart-sass');
  
  metalsmith
    .use(sass({
      pattern: '**/*.x-sass',
      sassOptions: {
        indentedSyntax: '**/*.x-sass'
      }
    }));

  By default, it is enabled for files with the extension .sass. If you want to add an extension, also add a .sass pattern.

  const sass = require('metalsmith-dart-sass');
  
  metalsmith
    .use(sass(
      (files, metalsmith, defaultOptions) => {
        return {
          pattern: [...defaultOptions.pattern, '**/*.x-sass'],
          sassOptions: {
            indentedSyntax: ['**/*.sass', '**/*.x-sass']
          }
        };
      }
    ));

• sourceMap

  A string value cannot be specified. Only boolean values ​​can be specified. If you want to specify a string, specify it with the return value of the function.

• importer

  In addition to the function value, you can specify a module name string or a plain object with the module name and option value. For example, if you use the node-sass-once-importer and the node-sass-package-importer packages, you can specify this setting:

  const sass = require('metalsmith-dart-sass');
  
  metalsmith
    .use(sass({
      sassOptions: {
        importer: {
          'node-sass-once-importer': null, // equal to require('node-sass-once-importer')(null)
          'node-sass-package-importer': {} // equal to require('node-sass-package-importer')({})
        }
      }
    }));

  It is possible to specify at the same time with other importers.

  const sass = require('metalsmith-dart-sass');
  
  metalsmith
    .use(sass({
      sassOptions: {
        importer: [
          {
            'node-sass-once-importer': {} // equal to require('node-sass-once-importer')({})
          },
          './custom-importer', // equal to require('./custom-importer')
          {
            'node-sass-package-importer': {} // equal to require('node-sass-package-importer')({})
          },
          (url, prev) => { ... }
        ]
      }
    }));

• functions

  In addition to functions, the object value can be a script filepath or an object with a filepath and optional values.

  const sass = require('metalsmith-dart-sass');
  
  metalsmith
    .use(sass({
      sassOptions: {
        functions: {
          'pow($base, $exponent)': './sass-functions-pow', // equal to require('./sass-functions-pow')
          'sqrt($number)': { './sass-functions': { name: 'sqrt' } } // equal to require('./sass-functions')({ name: 'sqrt' })
        }
      }
    }));

Type definition (source line 24 - 33 / source line 60 - 78):

import sass from 'sass'; // @types/[email protected]

type InputSassImporter =
    | string
    | Record<string, unknown>
    | sass.Importer;

type InputSassFunctionsValue =
    | string
    | Record<string, unknown>
    | Required<sass.Options>['functions'][string];

interface InputSassOptionsInterface
    extends Omit<
        sass.Options,
        'indentedSyntax' | 'sourceMap' | 'importer' | 'functions'
    > {
    indentedSyntax?: string | string[];
    sourceMap?: Exclude<
        Required<sass.Options>['sourceMap'],
        string
    >;
    importer?: InputSassImporter | InputSassImporter[];
    functions?: Record<string, InputSassFunctionsValue>;
}

InputSassOptionsInterface

functions that return SASS options

Specifies a function that returns Dart Sass options. The function is called for each SASS / SCSS file. This can be used to generate options that require different values ​​for each file, such as indentedSyntax and sourceMap.

const path = require('path');
const sass = require('metalsmith-dart-sass');

metalsmith
  .use(sass({
    sassOptions({ filename }) {
      return {
        outputStyle: 'compressed',
        indentedSyntax: filename.startsWith(`sass${path.sep}`), // For example, enable SASS syntax for files in the sass directory
        sourceMap: `${filename}.source.map` // For example, specify the Source Map filename as the original filename with ".source.map" suffix added
      };
    }
  }));

Type definition (source):

import Metalsmith from 'metalsmith'; // @types/[email protected]
import sass from 'sass'; // @types/[email protected]

(context: {
    filename: string;
    filedata: object;
    sourceFileFullpath: string;
    destinationFileFullpath: string;
    metalsmith: Metalsmith;
    metalsmithFiles: Metalsmith.Files;
    pluginOptions: object;
}) => sass.Options | Promise<sass.Options>

filepath string

You can also specify the filepath of the script that exports the above values.

const sass = require('metalsmith-dart-sass');

metalsmith
  .use(sass({
    sassOptions: './sass-options.js'
  }));

sass-options.js

module.exports = {
  outputStyle: 'compressed',
  sourceMap: true
};

renamer

Specify a function to rename of processed SASS and SCSS files. By default, a function that replaces file extension with .css is setted.

If you specify a falsy value other than undefined, such as null or false, processed files will not be renamed.

// These values disable file renaming
false
0
-0
NaN
''
""
``
null

If undefined or a truthy value other than string and function is specified, use the default renamer.

// These values use the default renamer
undefined
true
42
-42
Infinity
-Infinity
{}
[]
/ab+c/i
new Date()
... // And other non-function objects

You can also specify the filepath of the script that exports the above values.

const sass = require('metalsmith-dart-sass');

metalsmith
  .use(sass({
    renamer: './sass-renamer.js'
  }));

sass-renamer.js

module.exports = filename => {
  return `${filename}.css`;
};

Default value (source):

const path = require('path');

filename => {
  const newFilename = path.basename(filename, path.extname(filename)) + '.css';
  return path.join(path.dirname(filename), newFilename);
}

Type definition (source line 48 / source line 87):

string | boolean | null | (filename: string) => (string | Promise<string>)

dependenciesKey

To understand the description of this option, knowledge of the Metalsmith plugin is required.

Specify the property name. The property specified by this option contains an object with the name and metadata of the before conversion files used in the SASS and SCSS conversion.

For example, if you convert the following files:

main.scss

@use 'foo';

body {
  background: black;
}

_foo.scss

.foo {
  font-weight: bold;
}

If value 'dependencies data' is specified in dependenciesKey option, the following "dependencies object" are inserted into the Metalsmith metadata:

// This object is the value that subsequent Metalsmith plugins read from the "files" argument
// see: https://github.com/segmentio/metalsmith#useplugin
{
  'main.css': {
    // ↓ Properties automatically added by Metalsmith
    contents: Buffer.from('.foo {\n  font-weight: bold;\n}\n\nbody {\n  background: black;\n}'), // Converted CSS contents
    mode: ...,
    stats: Stats { ... },
    // ↑ Properties automatically added by Metalsmith

    // ↓ dependencies object added by specifying "dependenciesKey" option
    'dependencies data': {
      // ↓ Metadata of main.scss before conversion
      'main.scss': {
        contents: Buffer.from('@use \'foo\';\n\nbody {\n  background: black;\n}\n'),
        mode: ...,
        stats: Stats { ... },
        ...
      },

      // ↓ Metadata of _foo.scss before conversion
      '_foo.scss': {
        contents: Buffer.from('.foo {\n  font-weight: bold;\n}\n'),
        mode: ...,
        stats: Stats { ... },
        ...
      }
    }
  },
  ...
}

If an empty string or a non-string value is specified in the dependenciesKey option, the dependencies object is not insert.

// These values not insert dependencies object
false
true
null
undefined
''
""
``

Default value (source):

false

Type definition (source):

string | false | null

Debug mode

This plugin supports debugging output.
To enable, use the following command when running your build script:

DEBUG=metalsmith-dart-sass node my-website-build.js

For more details, please check the description of debug v4.1.1.

Tests

To run the test suite, first install the dependencies, then run npm test:

npm install
npm test

Contributing

see CONTRIBUTING.md