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

node modules

For node modules that contain SCSS/SASS files.

nodeModulesSync()

Sync version, returns the array directly.

nodeModules()

Async version, returns a theneable.

bower components

For bower components that contain SCSS/SASS files.

bowerComponentsSync()

Sync version, returns the array directly.

bowerComponents()

Async version, returns a theneable.

bundled ruby gems

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.

system/global ruby gems

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:

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)

[...]
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)

[...]
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)

[...]
// 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.

CLI/sassc usage

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.