gulp-transform

gulp-transform

Gulp plugin for applying arbitrary transformations to the contents of files.

• Simple. Just pass a callback function that takes the current file contents and returns the desired contents.
• Flexible. Receive file contents as a Buffer or a string. Compatible with pipelines in both buffer mode and streaming mode.
• Economical. Reduce the need for gulp-specific plugins by pairing gulp-transform with ordinary node packages and functions.

Install

Install via npm:

npm install --save-dev gulp-transform

Examples

Simple transformation

Source file:

I am constant as the northern star.

Transform task:

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

gulp.task('quadruple', function() {
  return gulp.src('src/*.txt')
    .pipe(transform(contents => Array(4).fill(contents).join('\n')))
    .pipe(gulp.dest('dest'));
});

Destination file:

I am constant as the northern star.
I am constant as the northern star.
I am constant as the northern star.
I am constant as the northern star.

Pairing with non-gulp packages

We can pair gulp-transform with vanilla node packages to reduce our dependence on gulp-specific plugins. In this example, we use gulp-transform with cheerio to add a role="main" attribute to all <main> elements, thus ensuring accessibility in older versions of Internet Explorer.

const gulp = require('gulp');
const transform = require('gulp-transform');
const cheerio = require('cheerio');


function transformFn(contents) {
  var $ = cheerio.load(contents);
  $('main').attr('role', 'main');
  return $.html();
}

gulp.task('cheerio', function() {
  return gulp.src('src/**/*.html')
    .pipe(transform(transformFn, {encoding: 'utf8'}))
    .pipe(gulp.dest('dest'));
});

API

transform(transformFn, [options])

transformFn function

The callback responsible for the transformation. The return value must be a string or a Buffer, which will replace the file's contents. The callback is invoked once per file with the following arguments:

• contents Buffer | string
  The initial contents of the file. Contents are passed as a Buffer unless the encoding option is set, in which case they are passed as a string. Contents are normalized to ensure a consistent API regardless of whether files are in streaming or buffer mode.

• file File
  The Vinyl file object to which the contents belong. Useful for getting metadata about the file, such as its path. Making changes to file.contents is not recommended, however, as these contents are not normalized and will in any case be replaced by the return value of the callback.

options object (optional)

An object for configuring the behavior of the plugin. The following keys are accepted as options:

• encoding string
  Casts contents to a string with the specified encoding before it is passed to transformFn. If no encoding is specified, contents will be passed as a Buffer.

• thisArg *
  Determines the value of this within transformFn. If omitted, this will be undefined.

License

Copyright © 2016 Akim McMath. Licensed under the MIT License.