gulp-retinate

Effortlessly scale and optimize images for retina and non-retina screens with this powerful Gulp plugin.

Automate the generation of multiple image resolutions (1x, 2x, 4x) for responsive web design, eliminating manual image duplication and ensuring pixel-perfect rendering across all devices.

Why gulp-retinate?

• Lightning-fast — Built on Sharp for superior performance
• Lightweight — Fewer dependencies than alternatives like GraphicsMagick
• Developer-friendly — Simple configuration with sensible defaults
• Flexible — Customize flags, placement, and scaling behavior
• Production-ready — Battle-tested with comprehensive test coverage

Related Projects: posthtml-retinate — HTML processing for retina images

Installation

npm install gulp gulp-retinate

Quick Start

Create a simple Gulp task to transform your images:

const gulp = require("gulp");
const retinate = require("gulp-retinate");

gulp.task("images", function () {
  return gulp
    .src("./src/**/*.{png,jpg,jpeg}")
    .pipe(retinate())
    .on("error", (e) => console.log(e.message))
    .pipe(gulp.dest("./dest/"));
});

That's it! Your [email protected] becomes [email protected] and image.png in the output.

Usage with Custom Options

For advanced image handling, configure the plugin to match your workflow:

const gulp = require("gulp");
const retinate = require("gulp-retinate");

const retinateOptions = {
  inputFlags: { 1: "@1x", 2: "@2x", 4: "@4x" },
  inputPlace: "endsWith",
  outputFlags: { 1: "", 2: "@2x", 4: "@4x" },
  outputPlace: "append",
  rounding: "ceil",
  scaleUp: false,
};

gulp.task("images", function () {
  return gulp
    .src("./src/**/*.{png,jpg,jpeg}")
    .pipe(retinate(retinateOptions))
    .on("error", (e) => console.log(e.message))
    .pipe(gulp.dest("./dest/"));
});

Configuration

All options are optional and come with sensible defaults. Customize them to match your image naming conventions.

inputFlags

Specifies how to identify different resolution versions in your source files.

| Property | Details | | ----------- | ---------------------------------- | | Type | Object<number, string> | | Default | { 1: '@1x', 2: '@2x', 4: '@4x' } | | Since | 1.0.0 | | Example | { 1: '', 2: '@2x', 4: '@4x' } |

The key is the output resolution (1, 2, or 4), and the value is the flag to detect in source filenames. For example, [email protected] or image-2x.png.

inputPlace

Determines where the input flag appears in your source filenames.

| Property | Details | | ----------- | ------------------------------ | | Type | string | | Default | 'endsWith' | | Options | 'startsWith' | 'endsWith' | | Since | 1.0.0 |

Examples:

• 'endsWith': [email protected] ✓
• 'startsWith': @2x-image.png ✓

outputFlags

Specifies the flags to add to destination filenames after scaling.

| Property | Details | | ----------- | ------------------------------- | | Type | Object<number, string> | | Default | { 1: '', 2: '@2x', 4: '@4x' } | | Since | 1.0.0 |

Similar to inputFlags. The key is the target resolution, and the value is what gets added to the output filename.

outputPlace

Determines where the output flag appears in destination filenames.

| Property | Details | | ----------- | ------------------------- | | Type | string | | Default | 'append' | | Options | 'prepend' | 'append' | | Since | 1.0.0 |

Examples:

• 'append': [email protected] ✓
• 'prepend': @2x-image.png ✓

rounding

Controls how fractional pixel dimensions are handled during scaling.

| Property | Details | | ----------- | --------------------- | | Type | string | | Default | 'ceil' | | Options | 'ceil' | 'floor' | | Since | 1.0.0 |

When scaling creates fractional dimensions, this option determines rounding behavior.

Example: A 35x35px image at @2x scaled to 1x resolution:

• 'ceil': Rounds to 18x18px (✓ slightly larger, safer)
• 'floor': Rounds to 17x17px (slightly smaller)

scaleUp

Whether to generate larger resolutions when only smaller source images exist.

| Property | Details | | ----------- | --------- | | Type | boolean | | Default | false | | Since | 1.0.0 |

If you only have [email protected], enabling this will generate [email protected] and [email protected] (upscaled).

Example: With scaleUp: true, a single [email protected] produces:

[email protected] (original)
[email protected] (upscaled 2x)
[email protected] (upscaled 4x)

Examples

Default Configuration

Source file: [email protected] (800x600px)

gulp
  .src("./src/**/*.{png,jpg,jpeg}")
  .pipe(retinate()) // Uses defaults
  .pipe(gulp.dest("./dest/"));

Output:

• hero.png (400x300px) — Standard resolution
• [email protected] (800x600px) — Retina resolution

Custom Naming Convention

If your sources use dashes instead of @:

gulp
  .src("./src/**/*.{png,jpg,jpeg}")
  .pipe(
    retinate({
      inputFlags: { 1: "-1x", 2: "-2x", 4: "-4x" },
      outputFlags: { 1: "", 2: "-2x", 4: "-4x" },
    }),
  )
  .pipe(gulp.dest("./dest/"));

Source: banner-2x.png → Output: banner.png, banner-2x.png

Related Projects

• posthtml-retinate — Process HTML files with retina image attributes
• gulp-retinize — Original inspiration for this project
• Sharp — The powerful image processing library powering gulp-retinate