gulp-transform

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

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, whose return value will replace the file's contents. The return value may be a string, a Buffer, or a Promise resolvable to a string or Buffer. 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–2017 Akim McMath. Licensed under the MIT License.