gulp-sass-globbing

Create an import map file with @import from a configured path

This plugin can be used with libsass.

The initial intent is to offer an alternative to grunt-sass-globbing.

Supported CSS preprocessors

libsass

libsass (and Ruby Sass) do not support globbing out-of-the-box. This plugin helps you migrating existing projects from Ruby Sass to libsass.

Getting Started

This plugin requires Gulp

If you haven't used Gulp before, be sure to check out the Getting Started guide, as it shares recipes for gulpfiles as well as how to install and use Gulp plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install gulp-sass-globbing --save-dev

Once the plugin has been installed, it may be enabled inside your gulpfile with this line of JavaScript:

gulp.require('gulp-sass-globbing');

The "glob:sass" task

Overview

In your project's gulpfile, add a task named glob:sass.

Usage Example

In this example, an import map from a defined path will be created. You might want to add an empty destination file to your version control: gulp-sass-globbing will overwrite it with the generated import statements.

Usage with all options

gulp.task('glob:sass', function() {
  var globSass = require('gulp-sass-globbing');

  gulp.src('components/**/*.scss', {cwd: 'sass/partials/global-styles'})
    .pipe(globSass(
      {
        path: '_components.scss'
      },
      {
        useSingleQuotes: true,
        signature: '// Hello, World!'
      }
    ))
    .pipe(gulp.dest('sass/partials/global-styles'));
});

In the gulp.src command, define the path where the files should be globbed from, based on the directory where the file with the globbed import statements will be located: this should be defined with the cwd key in the options for gulp.src, as well as in gulp.dest at the end of the task.

The globSass function takes two arguments:

• A Vinyl file object with the name of the file that should be created.
• An options object.

Options

useSingleQuotes

Type: Boolean Default: false

Determines whether single or double quotes are used around import statements.

• false - Double quotes are used.
• true - Single quotes are used.

signature

Type: string Default: /* generated with gulp-sass-globbing */\n\n

Sets the signature for the map files.

• false - Disables adding of signature.

Usage in SCSS file

In this example, your file is located in sass/global-styles.scss. This file imports the generated map files described in the example gulpfile above.

@import "partials/global-styles/components";
@import "partials/core";

// more imports or rules

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Gulp.

Acknowledgements

The initial goal of this project is to provide the same features as grunt-sass-globbing, from which this draws heavily. That project has a nice model of taking an import directory as its source and then creating a file that holds import statements.

A few sass globbing projects existed for Gulp, but with a different approach that required a file to define the location of the files that should be globbed:

• gulp-sass-glob-import
• gulp-sass-bulk-import
• gulp-sass-glob

I also reviewed the code for gulp-concat, which offered some helpful model code.

Thank you to the creators of all of these projects, and to all who contribute to these and other related projects.