Gulp Sass Glob

Gulp Sass Glob is a Gulp plugin that extends gulp-sass functionality to support glob-style imports in Sass/SCSS files. It allows developers to use wildcard patterns like @import "vars/*" to automatically import all files from a directory, eliminating the need to manually list each import.

Package Information

• Package Name: gulp-sass-glob
• Package Type: npm
• Language: JavaScript
• Installation: npm install gulp-sass-glob --save-dev

Core Imports

const sassGlob = require('gulp-sass-glob');

Basic Usage

Sass/SCSS file with glob imports:

@import "vars/*";
@import "mixins/*";
@import "../views/*";
@import "../components/*";

Gulpfile configuration:

const gulp = require('gulp');
const sass = require('gulp-sass');
const sassGlob = require('gulp-sass-glob');

gulp.task('styles', function () {
    return gulp
        .src('src/styles/main.scss')
        .pipe(sassGlob())
        .pipe(sass())
        .pipe(gulp.dest('dist/styles'));
});

Capabilities

Main Export

The module exports a single function as the default CommonJS export that creates a Gulp plugin transform stream.

/**
 * Creates a Gulp plugin transform stream for processing glob imports in Sass/SCSS files
 * @returns {NodeJS.ReadWriteStream} through2 transform stream for Gulp pipeline
 */
function gulpSassGlobbing(): NodeJS.ReadWriteStream;

// Export pattern
module.exports = gulpSassGlobbing;

How it works:

1. Pattern Detection: Scans file contents for @import statements containing glob patterns (using * wildcards)
2. File Resolution: Uses the glob library to find all matching Sass/SCSS files based on the pattern
3. Import Expansion: Replaces glob patterns with individual @import statements for each matching file
4. Directory Processing: Recursively processes directories, ignoring those starting with underscore (_)
5. File Filtering: Only processes files with .sass or .scss extensions

Supported patterns:

• @import "directory/*" - Imports all Sass/SCSS files in the directory
• @import "../path/to/files/*" - Supports relative paths
• Any pattern with asterisk (*) wildcard within double quotes

Pattern matching details:

• Uses regex pattern: /@import\s+\"([^\"]*\*[^\"]*)\"/
• Requires double quotes around the import path
• Must contain at least one asterisk (*) wildcard
• Supports whitespace after @import keyword

File processing rules:

• Only .sass and .scss files are processed for import generation
• Directories starting with _ (underscore) are ignored
• Directories are processed recursively
• Import statements are generated with proper Sass syntax: @import "path/to/file";

Integration with Gulp:

The plugin integrates seamlessly with Gulp build pipelines and should be placed before the gulp-sass plugin in the pipeline to ensure glob patterns are expanded before Sass compilation.

Dependencies

• glob: ^5.0.14 - File globbing functionality
• through2: ^2.0.0 - Stream transform utilities for Gulp plugin architecture

Error Handling

The plugin handles common error scenarios:

• Invalid patterns: Malformed glob patterns are ignored
• Missing files: Non-existent paths in glob patterns result in no imports (graceful degradation)
• File access: Standard file system errors are passed through the Gulp pipeline

Limitations

• Only processes @import statements with double quotes containing glob patterns
• Requires files to have .sass or .scss extensions
• Does not support complex glob features beyond basic wildcard (*) patterns
• Synchronous file processing may impact build performance with large directory structures

Types

// Built-in Node.js stream type for Gulp plugin compatibility
interface NodeJS.ReadWriteStream extends NodeJS.ReadableStream, NodeJS.WritableStream {}