sass-include-paths

Generates include paths for node-sass for packages from popular package managers like npm, bower, ruby gem, ruby bundler.



The generated array with the include paths can be passed to node-sass.

Allows interoperability between sass variants, ruby sass, libsass and sass-eyeglass (libsass + eyeglass)

Async/Sync
----------
This module offers an async and a sync version of each function.
The async version returns a thenable (Promise based) for easier chaining.
The sync version is intended for being used in tools like Gulp where this doesn't matter in a task.

Methods
-------

$3

For node modules that contain SCSS/SASS files.

#### nodeModulesSync()
Sync version, returns the array directly.

#### nodeModules()
Async version, returns a theneable.

$3

For bower components that contain SCSS/SASS files.

#### bowerComponentsSync()
Sync version, returns the array directly.

#### bowerComponents()
Async version, returns a theneable.

$3

For bundled ruby gems installed in folder by bundler (default is ./vendor/bundle) that contain SCSS/SASS files.

#### rubyGemsBundleSync()
Sync version, returns the array directly.

#### rubyGemsBundle()
Async version, returns a theneable.

$3

For ruby gems installed on current (activated/available) ruby environment (system/globally installed gems) that contain SCSS/SASS files.

#### rubyGemsSync()
Sync version, returns the array directly.

#### rubyGems()
Async version, returns a theneable.

Usage
-----

Require this module and optionally define an array of include paths,
either empty or already with some paths to include:
``javascript
var sassIncl = require('sass-include-paths'),
scssIncludePaths = [];
``

When the module functions are invoked outside the task scope,
the scan is run only once when gulp is started, notably when using gulp-watch.
This spares extra scans each time workspace files are changed.
When packages, gems or bower components are changed, gulp watch has to be restarted for a rescan.


For importing sass/scss files from sass/eyeglass npm packages...
#### using gulp-ruby-sass (ruby sass)
`javascript
[...]
scssIncludePaths = [] // additional include paths
.concat(sassIncl.nodeModulesSync());
[...]
rubySass(srcAssets.scss + '/*.scss', {
loadPath: scssIncludePaths
})
[...]
``
As gulp-ruby-sass (ruby-sass) already imports sass/scss files from ruby gems
(autorequired by Gemfile or explicitly required in compass config.rb or elsewhere),
there is no need to pass paths to these, too.


For importing sass/scss files from plain or eyeglass npm packges and from ruby gems and local bundle...
#### using gulp-sass (plain libsass)
`javascript
[...]
scssIncludePaths = [] // additional include paths
.concat(sassIncl.nodeModulesSync())
.concat(sassIncl.rubyGemsSync())
.concat(sassIncl.rubyGemsBundleSync());
[...]
.pipe(plugins.sass({
includePaths: scssIncludePaths
}))
[...]
``
One could argue using a custom importer for node-sass instead, but currently there are no custom importers
that scan node_modules/ because in most opinions this should be handled by eyeglass (libsass + eyeglass) instead,
however, even using eyeglass, there is still an use case (see further below).


For importing sass/scss files from plain npm packages and from ruby gems and local bundle...
#### using eyeglass (libsass + eyeglass)
`javascript
[...]
// Outside the gulp task
scssIncludePaths = [] // additional include paths
.concat(sassIncl.nodeModulesSync())
.concat(sassIncl.rubyGemsSync())
.concat(sassIncl.rubyGemsBundleSync()):
[...]
var eyeglass = new Eyeglass({
includePaths: scssIncludePaths
});
[...]
``
One use case to also add node_module paths when using eyeglass
is to be able to import npm packages that haven't been made eyeglass-ready yet.
Though it may work fine using this module, please still consider creating an issue
to inform the package creator that eyeglass metadata is still missing for the package.




$3


A cli wrapper comes with this module which can generate the list of include paths to be used on cli.
For sassc-compatible options output, pass the --sassc switch.
Example:
``
$ npm install -g sass-include-paths
$ sassc $(sassIncludePaths --sassc --node_modules --bower_components) [...]
``
Note: $(...) executes the command and re-uses its stdout.

Development
-----------
In order to run the tests, npm, bower and ruby gem/bundler have to be available.
bower will be installed as development dependency of this package.
For consistent tests, the ruby and node versions have been locked using rvm/nvm config files,
so both or similar tools have to be installed to ensure the right versions and isolation.

./test/prepare.sh can be run after npm install` for quickly installing the bower dependencies and ruby bundle.