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?

score 26 · Accepted Answer · answered Nov 07 '15 at 21:50

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.

This is very clear explanation. What still puzzles me is this syntax: `neat = require('node-neat').includePaths;`, `includePaths: ['styles'].concat(neat)` — luqo33, Nov 07 '15 at 22:24
`['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 http://stackoverflow.com/a/27975742/3649209 for how to add gutil). We use concat to merge them together to get `['styles', , , , ... ]`. — James Lawson, Nov 07 '15 at 22:36
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](https://github.com/lacroixdesign/node-neat/blob/master/index.js#L13). — James Lawson, Nov 07 '15 at 22:44
Talking about `loadPaths` when the question only mentioned `includePaths`. Classic StackOverflow. — Yeats, Jul 10 '20 at 02:36

score 7 · Answer 2 · edited Jun 20 '20 at 09:12

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

What does Gulp's includePaths do?

2 Answers2

Linked

Related