gulp-sort

What is gulp-sort?

The gulp-sort npm package is a Gulp plugin that allows you to sort files in a stream. This can be useful for ensuring that files are processed in a specific order, such as sorting JavaScript files alphabetically or by a custom comparator function.

What are gulp-sort's main functionalities?

Sort files alphabetically

This feature allows you to sort files alphabetically. The code sample demonstrates how to use gulp-sort to sort JavaScript files in the 'src' directory and output them to the 'dist' directory.

const gulp = require('gulp');
const sort = require('gulp-sort');

gulp.task('sort-files', function() {
  return gulp.src('src/**/*.js')
    .pipe(sort())
    .pipe(gulp.dest('dist'));
});

Sort files with a custom comparator

This feature allows you to sort files using a custom comparator function. The code sample demonstrates how to use gulp-sort with a custom comparator to sort JavaScript files in the 'src' directory and output them to the 'dist' directory.

const gulp = require('gulp');
const sort = require('gulp-sort');

gulp.task('sort-files-custom', function() {
  return gulp.src('src/**/*.js')
    .pipe(sort({
      comparator: function(file1, file2) {
        return file1.path.localeCompare(file2.path);
      }
    }))
    .pipe(gulp.dest('dist'));
});

Other packages similar to gulp-sort

gulp-order

The gulp-order package allows you to specify the order of files in a stream explicitly. Unlike gulp-sort, which sorts files based on a comparator function, gulp-order lets you define the exact order of files using glob patterns. This can be useful when you need precise control over the order of files.

gulp-concat

The gulp-concat package concatenates files into a single file. While it does not sort files, it is often used in conjunction with sorting plugins like gulp-sort or gulp-order to ensure that files are concatenated in the correct order. This package is useful for bundling multiple files into one.

README

gulp-sort

Sort files in stream by path or any custom sort comparator

Install

$ npm install gulp-sort --save-dev

Usage

var sort = require('gulp-sort');

// default sort
gulp.src('./src/js/**/*.js')
    .pipe(sort())
    .pipe(gulp.dest('./build/js'));

// pass in a custom comparator function
gulp.src('./src/js/**/*.js')
    .pipe(sort(customComparator))
    .pipe(gulp.dest('./build/js'));

// sort descending
gulp.src('./src/js/**/*.js')
    .pipe(sort({
         asc: false
    }))
    .pipe(gulp.dest('./build/js'));

// sort with a custom comparator
gulp.src('./src/js/**/*.js')
    .pipe(sort({
        comparator: function(file1, file2) {
            if (file1.path.indexOf('build') > -1) {
                return 1;
            }
            if (file2.path.indexOf('build') > -1) {
                return -1;
            }
            return 0;
        }
    }))
    .pipe(gulp.dest('./build/js'));

// sort with a custom sort function
var stable = require('stable');
gulp.src('./src/js/**/*.js')
    .pipe(sort({
        customSortFn: function(files, comparator) {
            return stable(files, comparator);
        }
    }))
    .pipe(gulp.dest('./build/js'));

Options

gulp-sort takes in an optional comparator function, or dictionary with following params:

asc

Sort ascending. Defaults to true. Specify false to sort descending.

comparator

Comparator function to use. comparator(file1, file2). Defaults to localeCompare of file paths.

customSortFn

Use customSortFn in order to control the sorting yourself (useful for stable sorts).

customSortFn signature is as follows:

customSortFn(<files>, <comparator>)

• files being the vinyl file objects that were passed in
• comparator is the default comparator used, or a custom one that was passed as param

This function is expected to return back the sorted list of files.

License

MIT ©Gilad Peleg