Transform Images

Image manipulation plugin using Sharp

Description

Use the transform_images plugin to process image files using the sharp library. With this plugin, you can resize, rotate, and convert any image to other formats.

The plugin reads the data assigned to the image files (specifically the transformImages key) to know how to transform the image.

Installation

Import this plugin in your _config.ts file to use it:

import lume from "lume/mod.ts";
import transformImages from "lume/plugins/transform_images.ts";

const site = lume();

site.use(transformImages(/* Options */));

export default site;

Example

Create a /img folder in your project to store the images and a _data.yml file inside this folder with the following code:

transformImages:
  resize: [200, 200]
  format: webp

This file assigns this data to all image pages in this folder and subfolders (see Shared data for more info about _data files). The plugin will read the data, resize all images to 200x200, and convert them to webp format.

The format value can be an array of values, in order to output the same file configuration to different formats:

transformImages:
  resize: [200, 200]
  format: [webp, jpg]

Multiple outputs

If you need to create multiple versions of the same image file (for responsive design, for example), use an array of transforms. Make sure to include the suffix key to generate different names for the output files:

transformImages:
  - resize: [200, 200]
    suffix: -small
    format: [webp, jpg]
  - resize: [1000, 1000]
    format: webp
  - resize: [2000, 2000]
    suffix: -big
    format: webp

This code generates 4 files for every image file (note the first transform with 2 formats). For example, if the input file is background.png, it will generate the files background.webp, background.jpg, background-small.webp and background-big.webp.

Matches

The property matches allows to set a regular expression so the transform is executed only to these files matching the pattern.

In the following example, the images containing -cover will be resized to 1000x1000, and the images containing -icon to 100x100.

transformImages:
  - resize: [1000, 1000]
    matches: -cover

  - resize: [100, 100]
    matches: -icon

The matches value must be a RegExp or a valid string that can be used to create a RegExp instance.

Custom functions

By default, the following functions are available:

resize: Accepts two numbers for width and height and optionally an object with the resize options. See sharp resize api for more info.
blur: Accepts a number for sigma.
rotate: Accepts a number for degrees.

You can add more custom functions in the _config file. For example:

import lume from "lume/mod.ts";
import transformImages from "lume/plugins/transform_images.ts";

const site = lume();

site.use(transformImages({
  functions: {
    resizeBlur(img, size) {
      img.resize(size, size);
      img.blur(10);
    },
  },
}));

export default site;

Now you can use this function in your _data files:

transformImages:
  resizeBlur: 20
  format: webp

Cache

This plugin saves the transformed images in the _cache folder to improve the build speed. If you want to disable the cache, set its option to false.

import lume from "lume/mod.ts";
import transformImages from "lume/plugins/transform_images.ts";

const site = lume();

site.use(transformImages({
  cache: false, // Disable cache
}));

export default site;

This option allows customizing the cache folder. For example: cache: "_image-cache".

Options See on deno.land