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?

Answer 1

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

Answer 2

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.