What does Gulp's includePaths do?

Question

I am attempting to start using Bourbon and Neat Sass libraries in my project. I want to compile Sass with Gulp. This is a simple styles task setup that I've found in one of the tutorials:

var gulp = require('gulp'),
    sass = require('gulp-sass'),
    neat = require('node-neat').includePaths;

var paths = {
    scss: './assets/styles/*.scss'
};

gulp.task('styles', function () {
    return gulp.src(paths.scss)
        .pipe(sass({
            includePaths: ['styles'].concat(neat)
        }))
        .pipe(gulp.dest('./dist/styles'));
});

gulp.task('default', function () {
    gulp.start('styles');
});

Then in the main .scss file I place the imports:

@import "bourbon";
@import "base/base";
@import "neat";

This task executes correctly.

What puzzles me here is what includePaths does exactly? Base on the example above, can somebody explain to me what includePath's role is?

Frenchy

Answer 1

The SASS compiler uses each path in loadPaths when resolving SASS @imports.

loadPaths: ['styles/foo', 'styles/bar']

@import "x"; // found via ./styles/foo/_x.scss
@import "y"; // found via ./styles/bar/_y.scss

Note that the compiler resolves each @import by considering each path in loadPaths from left-to-right (similar to $PATH in a UNIX environment). An example scenario could be:

loadPaths: ['styles/i', 'styles/ii', 'styles/iii', 'styles/iv']

@import "x"; // no file at ./styles/i/_x.scss
             // no file  at ./styles/ii/_x.scss
             // found a file  at ./styles/iii/_x.scss ...
             //     ... this file will be used as the import
             //     ... terminate lookup
             // the file ./styles/iv/_x.scss will be ignored

There was no _x.scss file in styles/i, so it moved on to look inside styles/ii. Eventually it found an _x.scss file in styles/iii and finished the lookup. It looks at each folder in loadPaths starting from the first element in the array and moving right. After attempting all paths, if we can't find the file, then we declare that this @import statement is invalid.

Load paths is useful if you have a external library (like bournon/neat). The external library is large and will use lots of @import statements. However they won't match your project folder structure and so won't resolve. However, you can add an extra folders to the loadPaths so that the @imports inside the external library do resolve.

Swashbuckler

This is very clear explanation. What still puzzles me is this syntax: neat = require('node-neat').includePaths;, includePaths: ['styles'].concat(neat) – Frenchy

['styles'] is the folder used for your project ... to resolve @import statements in your SASS files. The neat variable contains an array of extra paths to resolve paths in the neat's SASS files. Try adding a gutil.log(neat) to gulp see what paths are being added (see https://mcmap.net/q/206305/-console-log-to-stdout-on-gulp-events for how to add gutil). We use concat to merge them together to get ['styles', <folder1 for neat>, <folder2 for neat>, <folder3 for neat>, ... <last folder for neat>]. – Swashbuckler

If you are confused about the syntax of require, you should read about 'Common JS Modules', specfically the meaning of 'module.exports'. NPM packages like (node-neat) uses this notation. The node-neat module is exporting includePaths. – Swashbuckler

Talking about loadPaths when the question only mentioned includePaths. Classic StackOverflow. – Rimmer

Answer 2

includePaths

Type: Array Default: []

An array of paths that libsass can look in to attempt to resolve your @import declarations. When using data, it is recommended that you use this.

in sass, you can orginize your sass files in multiple folders, but you want your main.sass to be able to import them when it compiles, so you can specify the includePaths, so that sass knows where to find the @import sass file, here you use node-neat, if you want to import some styles from it, by default, sass don't know where to look, so you need to tell sass where to find the file to import

Pretrice