Sass Plugin for Theme Tools

> Theme core plugins let you easily pass in configuration and get a set of Gulp-ready task functions back that have sensible defaults and work well together.

Features

- Scss compiling via gulp-sass & libsass
- Sourcemaps
- Handy PostCSS plugins:
- Autoprefixer
- URL to inline or copy assets
- Discard Duplicates to remove duplicated rules
- Flexbox bug fixes
- CSS Nano for minification if NODE_ENV=production
- Documentation generation via SassDoc
- Linting via Stylelint
- Native OS Notifications for Errors
- Better Sass @import Globbing that allows nested globbed imports

Getting Started

Requirements

- Gulp 4 installed with npm install --save gulp@4

Install

``bash
npm install @theme-tools/plugin-sass --save
`

Configure

The config that is passed in is merged with config.default.js. We suggest starting with config.simple.js to get started:

`bash
cp node_modules/@theme-tools/plugin-sass/config.simple.js config.sass.js
`

See details on configuration below.

Basic Setup

Add this to your gulpfile.js:

`js
const gulp = require('gulp');
const config = {};
config.sass = require('./config.sass.js');
const sassTasks = require('@theme-tools/plugin-sass')(config.sass);

gulp.task('sass', sassTasks.compile);
gulp.task('watch:sass', sassTasks.watch);
gulp.task('validate:sass', sassTasks.validate);
gulp.task('clean:sass', sassTasks.clean);
gulp.task('docs:sass', sassTasks.docs);
`

- See Task Details below
- See Setting up SassDoc below
- See Setting up Stylelint below

Details

Tasks

These tasks are methods inside sassTasks from the above code example. You can run them anyway you can run a function, though they are often ran via Gulp. All tasks take a callback function as the first and only parameter that will run when the task is done - exactly how gulp.task(), gulp.parallel(), and gulp.series() want.

$3

The main task that takes Sass files and turns them into CSS files after passing them through AutoPrefixer.

$3

If you have a Stylelint config present next to your Gulpfile, then this will run that for you. Disabled by default.

$3

Deletes files that are made by the other tasks.

$3

Creates SassDoc documentation for you.

$3

The watch task that will fire off the compile, validate, and docs tasks (if enabled).

Configuration

All configuration is deep merged with config.default.js.

$3

Type: Array Default: [ 'scss/*/.scss' ]

The collection of files to compile, watch, validate, and document. This is passed to gulp.src. Supports globbing.

$3

Type: String Default: 'dest/'

Where to output the compiled files: CSS files, SourceMaps, and SassDoc output ends up here.

$3

Type: Array Default: []

Extra collection of files to watch; when these change the enabled tasks (compile, validate, docs) will run (but not with these added to their src). Supports globbing.

$3

Type: Boolean Default: true

If true, no folders will be made in the dest folder, and all files will be one level deep. If false, then the folders will be made; so for example:

- This scss/path/to/file.scss
- Compiles to dest/path/to/file.css

$3

Type: Boolean Default: false

Enables additional debugging information in the output file as CSS comments. Shouldn't need to use unless SourceMaps isn't working for you. Passed to node-sass's sourceComments.

$3

Type: Boolean Default: false

Embed SourceMaps in CSS file or in own .css.map file? Passed to node-sass's sourceMapEmbed.

$3

Type: String Default: 'expanded' Values: nested, expanded, compact, compressed

Determines the output format of the final CSS style. Passed to node-sass's outputStyle.

$3

Type: Array Default: [ 'last 2 versions', 'IE >= 10' ] Values: see list.

Based on the browsers you want to support, this adds the vendor prefixes you'll need. It's recommended to have Stylelint check to make sure you don't write vendor prefixes in your source code as well.

$3

Type: Array Default: [ './node_modules' ]

An array of paths that LibSass can look in to attempt to resolve your @import declarations. Useful for importing libraries you install via npm. Passed to node-sass's includePaths.

$3

Type: Object

Config for Stylelint; see below for properties.

#### lint.enabled

Type: Boolean Default: false

Uses Stylelint. If enabled, this will export out a sassTasks.validate task, and lint the most recently changed file on watch triggers. Requires Stylelint configuration to be set up.

#### lint.onWatch

Type: Boolean Default: true

If true, lint the files that just changed after each save. If false, then it is not ran on watch, but you still have the full lint task of sassTasks.validate().

$3

Type: Object

Configuration for SassDoc; see below for properties.

#### sassdoc.enabled

Type: Boolean Default: false

If enabled, you'll have a sassTasks.docs() task and it'll trigger on watch.

#### sassdoc.dest

Type: String Default: 'dest/sassdoc'

Where to compile SassDoc to.

#### sassdoc.verbose

Type: Boolean Default: false

Show more debugging information.

#### sassdoc.basePath

Type: String Default: ''

Allows you to have a "View Source" link next to code documentation to it's GitHub/Bitbucket view. Set it to https://github.com/USERNAME/REPOSITORY/tree/master (or /blob/). Passed to SassDoc's basePath.

#### sassdoc.exclude

Type: Array Default: []

Doesn't document these files. Passed to SassDoc's exclude.

$3

Type: String Default: 'default'

Theme for SassDoc. Passed to SassDoc's theme.

#### sassdoc.sort

Type: Array Default: [ 'file', 'group', 'line>' ]

Passed to SassDoc's sort.

$3

Type: Object

Uses postcss-url to take assets found in the url()s of the sass and will inline or copy them to the destination directory (dest option) and rewrite what's found in the url().

$3

Type: Boolean Default: false

Turn this behavior on or off.

$3

Type: Array Default: []

Path or array of absolute paths to search for assets. Passes to the basePath option.

$3

Type: Number Default: 14

Max filesize, in kilobytes, to inline via Base64. If bigger, it copies the file. Passes to maxSize option

$3

Type: Regex, String, or Function Default: All files

A regular expression e.g. /\.svg$/, a minimatch string e.g. '*/.svg' or a custom filter function to determine whether a file should be inlined. Example: url => !url.pathname.startsWith('icons').

$3

Type: String Default: ''

If used, assets are placed in this directory inside the dest directory where CSS is compiled to.

$3

Type: Object

Uses @theme-tools/sass-export-data to export Sass Maps and other vars as JSON. All options in this variable are passed directly to that module, please see it for docs & details.

#### exportData.enabled

Type: Boolean Default: false

$3

Type: Object Default: {}

Add your own custom Sass functions by passing in an object of functions according to those docs.

$3

Type: Array Default: []

Add your own custom Sass importer by passing in an array of functions according to those docs.

---

Setup Details

$3

This uses Stylelint via gulp-stylelint - see those pages for further docs.

1. Set lint.enabled to true.
2. Run npm install --save-dev stylelint-scss
3. Create these files: .stylelintignore (for ignored files) and a config file, .stylelintrc.js with this:

`js
// Docs: http://stylelint.io
// Style lint rule detail: https://github.com/stylelint/stylelint/tree/master/src/rules/RULE-NAME

module.exports = {
plugins: [
"stylelint-scss"
],
rules: {
// Just some sample rules to get you started.
"declaration-no-important": true,
"indentation": 2,
"max-nesting-depth": 3,
"selector-max-specificity": "0,3,3",
"selector-no-id": true,
"scss/at-extend-no-missing-placeholder": true,
"at-rule-no-vendor-prefix": true,
"media-feature-name-no-vendor-prefix": true,
"property-no-vendor-prefix": true,
"selector-no-vendor-prefix": true,
"value-no-vendor-prefix": true
}
};
`

You can disable rules for a single place using this, or other, approaches:

`scss
.utility--spacing-down {
margin-bottom: $spacing !important; // stylelint-disable-line declaration-no-important
}
`

Sometimes !important is ok; most of the time it's not.

$3

1. Set sassdoc.enabled to true
2. Use SassDoc comment annotations in your Sass. These all use comments like /// instead of the regular //. See below for examples.
3. Open sassdoc.dest (defaults to dest/sassdoc/) to view SassDoc.

`scss
/// Link Color
$color--link: blue;

/// Center an element vertically and/or horizontally in its container.
/// @param $horizontally [true] - center horizontally
/// @param $vertically [true] - center vertically
@mixin center($horizontally: true, $vertically: true) {
position: relative;
@if ($horizontally == true and $vertically == true) {
left: 50%;
top: 50%;
transform: translateX(-50%) translateY(-50%);
}
@if ($vertically == true and $horizontally == false) {
top: 50%;
transform: translateY(-50%);
}
@if ($horizontally == true and $vertically == false) {
left: 50%;
transform: translateX(-50%);
}
}
``

Theme Core Events

This is only info for other Theme Core plugin developers.

$3

This event is emmited when files are done compiling. The first paramater is a String of the files changed.