metalsmith-img-sharp

A Metalsmith plugin to process images with Sharp.

This plugin is designed to be a modernized, grossly more performant, drop-in replacement for the outdated and unmaintained metalsmith-sharp plugin.

Installation

npm install --save metalsmith-img-sharp

JavaScript Usage

With one object of options:

import Metalsmith from 'metalsmith';
import sharp from 'metalsmith-img-sharp';

Metalsmith(__dirname)
    .use(sharp({
        src: '**/*.@(bmp|png)',
        namingPattern: '{dir}{name}.jpg',
        methods: [
          {
            name: 'resize',
            args: [200, 200]
          },
          {
            name: 'jpeg',
            args: { quality: 85 }
          }
        ],
        moveFile: true
        // other options here
    }))
    .build((err) => {
        if (err) {
            throw err;
        }
    });

or with an array of options:

import Metalsmith from 'metalsmith';
import sharp from 'metalsmith-img-sharp';

Metalsmith(__dirname)
    .use(sharp([
      {
        src: '**/*.jpg',
        methods: [{
          name: 'resize',
          args: [200, 200]
        }]
        // other options here
      },
      {
        src: '**/*.@(bmp|png)',
        namingPattern: '{dir}{name}.jpg',
        methods: [{
          name: 'jpeg',
          args: { quality: 85 }
        }],
        moveFile: true
        // other options here
      }
    ]))
    .build((err) => {
        if (err) {
            throw err;
        }
    });

Options

methods (required)

Type: { name: string, args: unknown}[]

An array of Sharp methods to apply to each file. See the full Sharp documentation on what resizing, compositing, color manipulation, and other functions are available.

args can be one of:

• A single value if the Sharp function only takes one argument
  • This can be an object if the Sharp function takes an object
• An array of values if the Sharp function takes multiple arguments
• A method that takes a Sharp metadata object and returns an array of values

Example:

sharp({
  src: '**/*.@(bmp|png)',
  methods: [
    {
      // Halve the size of the image
      name: 'resize',
      args: (metadata) => [
        Math.round(metadata.width / 2),
        Math.round(metadata.height / 2),
      ]
    },
    {
      // Flatten a transparent image with a solid background color
      name: 'flatten',
      args: { background: '#ffffff' }
    }
  ]
})

pattern (optional)

Type: string Default: **/*.@(avif|bmp|gif|heic|jpg|jpeg|png|svg|webp)

A micromatch glob pattern for image files to process.

namingPattern (optional)

Type: string Default: {dir}{base}

The output filename for every processed image. Placeholders available:

• {dir}: Directory of file followed by slash
• {base}: Full filename with extension
• {name}: Filename without extension
• {ext}: File extension with leading dot

moveFile (optional)

Type: boolean Default: false

If a new file was created because namingPattern, should the old file be deleted.

sharp (optional)

Type: object Default: {}

Options to pass to the Sharp constructor.

parallelism (optional)

Type: number Default: the number of logical CPU cores available

The maximum number of image files to process concurrently.

Changelog

Changelog