@localnerve/gulp-responsive

gulp-responsive

This is mostly the same as the original except with updated dependencies and code.

Generates images at different sizes

Exposes a postprocess option to allow you to capture the work of this transform and use it in other build operations.

Installation

gulp-responsive depends on sharp. Sharp is one of the fastest Node.js modules for resizing JPEG, PNG, WebP and TIFF images.

If you are using Mac OS then before installing gulp-responsive you should install the libvips library. Further information and instructions can be found in the sharp installation guide.

$ npm install --save-dev gulp-responsive

Usage

import gulp from 'gulp'
import responsive from 'gulp-responsive'

gulp.task('default', function () {
  return gulp
    .src('src/*.{png,jpg}')
    .pipe(
      responsive({
        'background-*.jpg': {
          width: 700,
          quality: 50
        },
        'cover.png': {
          width: '50%',
          // convert to jpeg format
          format: 'jpeg',
          rename: 'cover.jpg'
        },
        // produce multiple images from one source
        'logo.png': [
          {
            width: 200
          },
          {
            width: 200 * 2,
            rename: '[e-mail]'
          }
        ]
      })
    )
    .pipe(gulp.dest('dist'))
})

Examples

• Simple example
• Multiple resolutions
• Advanced example

Integration

• HTML srcset attribute
• HTML <picture> element
• CSS image-set method

All together :fireworks:

• gulp-responsive config generation example

API

responsive(config, options)

config

Configuration can be provided in one of the following formats:

1. Array of unique configurations

;[
  {
    name: 'logo.png',
    width: 200,
    height: 100
  },
  {
    name: 'banner.png',
    width: 500
  }
]

2. Object of unique configurations. Keys are filenames.

{
  'logo.png': {
    width: 300,
    height: 200,
    rename: '[e-mail]'
  },
  'background-*.png': {
    width: 1400,
    withoutEnlargement: true
  }
}

3. Object of arrays of unique configurations. Keys are filenames.

{
  'logo.png': [{
      width: 200,
      rename: '[e-mail]'
    },{
      width: 400,
      rename: '[e-mail]'
    }],
  'background-*': [{
    height: 400
  }]
}

Configuration unit

Configuration unit is an object:

• name: String — filename glob pattern.
• width: Number or String — width in pixels or percentage of the original, not set by default.
• height: Number or String — height in pixels or percentage of the original, not set by default.
• withoutEnlargement: Boolean — do not enlarge the output image, default true.
• skipOnEnlargement: Boolean — do not write an output image at all if the original image is smaller than the configured width or height, default false.
• min: Boolean — preserving aspect ratio, resize the image to be as small as possible while ensuring its dimensions are greater than or equal to the width and height specified.
• max: Boolean — resize to the max width or height the preserving aspect ratio (both width and height have to be defined), default false.
• quality: Number — output quality for JPEG, WebP and TIFF, default 80.
• progressive: Boolean — progressive (interlace) scan for JPEG and PNG output, default false.
• withMetadata: Boolean — include image metadata, default false.
• compressionLevel: Number — zlib compression level for PNG, default 6.
• rename: String, Object or Function — renaming options, file will not be renamed by default. When extname is specified, output format is parsed from extension. You can override this autodetection with format option.
• format: String — output format jpeg, png, webp or raw, default is null.
• crop: Crop the resized image to the exact size specified, default is false.
• embed: Preserving aspect ratio, resize the image to the maximum width or height specified then embed on a background of the exact width and height specified, default is false.
• ignoreAspectRatio: Boolean — Ignoring the aspect ratio of the input, stretch the image to the exact width and/or height provided via resize, default is false.
• kernel: String — The kernel to use for image reduction, defaulting to lanczos3.
• background: Color — Set the background for the embed and flatten operations, '#default is fff'.
• flatten: Boolean — Merge alpha transparency channel, if any, with background, default is false.
• negate: Boolean — Produces the "negative" of the image, default is false.
• rotate: Boolean — Rotate the output image by either an explicit angle or auto-orient based on the EXIF Orientation tag, default is false.
• flip: Boolean — Flip the image about the vertical Y axis. This always occurs after rotation, if any. The use of flip implies the removal of the EXIF Orientation tag, if any. Default is false.
• flop: Boolean — Flop the image about the horizontal X axis. This always occurs after rotation, if any. The use of flop implies the removal of the EXIF Orientation tag, if any. Default is false.
• blur: Boolean — When used without parameters, performs a fast, mild blur of the output image. This typically reduces performance by 10%. Default is false.
• sharpen: Boolean — When used without parameters, performs a fast, mild sharpen of the output image. This typically reduces performance by 10%. Default is false.
• threshold: Number or Boolean — Converts all pixels in the image to greyscale white or black, default is false.
• gamma: Boolean — Apply a gamma correction by reducing the encoding (darken) pre-resize at a factor of 1/gamma then increasing the encoding (brighten) post-resize at a factor of gamma. Default is false.
• grayscale: Boolean — Convert to 8-bit greyscale; 256 shades of grey, default is false.
• normalize: Boolean — Enhance output image contrast by stretching its luminance to cover the full dynamic range. This typically reduces performance by 30%. Default is false.
• trim: Boolean or Number — Trim "boring" pixels from all edges that contain values within a percentage similarity of the top-left pixel. Default is false.
• tile: Boolean or Object — The size and overlap, in pixels, of square Deep Zoom image pyramid tiles, default is false.
• withoutChromaSubsampling: Boolean — Disable the use of chroma subsampling with JPEG output (4:4:4), default is false.

Detailed description of each option can be found in the sharp API documentation.

Renaming

Renaming is implemented by the rename module. Options correspond with options of gulp-rename.

options

errorOnUnusedConfig

Type: Boolean
Default: true

Emit the error when configuration is not used.

errorOnUnusedImage

Type: Boolean
Default: true

Emit the error when image is not used.

passThroughUnused

Type: Boolean
Default: false

Keep unmatched images in the stream. To use this option errorOnUnusedImage should be false.

errorOnEnlargement

Type: Boolean
Default: true

Emit the error when image is enlarged.

stats

Type: Boolean
Default: true

Show statistics after the run — how many images were created, how many were matched and how many were in the run in total.

silent

Type: Boolean
Default: false

Silence messages and stats if 0 images were created. If you wish to supress all messages and stats, set the options.stats to false as well.

postprocess

Type: Function
Default: undefined

If you supply a postprocess function, it will be called after every successfully processed file. It receives a vinyl object of the original file, the config used to process it, and a vinyl object of the new file. For Vinyl object details, see vinyl.

Signature: function postprocess (originalVinylFile, config, newVinylFile)

Global Configuration Options

You can specify global default value for any of the configuration options.

gulp.task('default', function () {
  return gulp
    .src('src/*.png')
    .pipe(
      responsive(config, {
        // global quality for all images
        quality: 50,
        errorOnUnusedImage: false
      })
    )
    .pipe(gulp.dest('dist'))
})

License

MIT © Evgeny Vlasenko