`@jcayzac/astro-image-service-ng`

Drop-in replacement for Astro's built-in image service, with support for cropping.

This module gives you a few things not provided by Astro's built-in image service:

Support for cropping.
A way to change the default output format to something other than WEBP.
Persistence through arbitrary stores, not just the Astro build cache.

Installation

Add astro-image-service-ng and sharp to your Astro project:

# pnpm
pnpm add @jcayzac/astro-image-service-ng sharp

# bun
bunx add @jcayzac/astro-image-service-ng sharp

# npm
npx add @jcayzac/astro-image-service-ng sharp

# yarn
yarn add @jcayzac/astro-image-service-ng sharp

# deno
deno add npm:@jcayzac/astro-image-service-ng npm:sharp

Then, just add the integration to your Astro configuration:

import { defineConfig } from 'astro/config'
import image from '@jcayzac/astro-image-service-ng'

export default defineConfig({
  integrations: [
    image({ /* options */ }),
  ],
  // …other options
})

Features

Cropping

Astro's built-in image service is great, but it lacks support for cropping. When the service receives a transformation request with both the width and height parameters provided, it ignores the height parameter and preserves the aspect ratio of the input image.

This is unfortunate for a number of use cases, including social images —for example for the Open Graph protocol or for an ImageObject inside JSON-LD embedded in your pages. Facebook recommends a 40:21 (aka 1.91:1) aspect ratio for the former while Google recommends 16:9, 4:3 and 1:1 for the latter.

Our image service does things differently: when both the width and height parameters are provided, the result image will have the requested dimensions. You can specify the fitting strategy using the fit parameter, which defaults to cover. Other values are contain, fill, inside and outside. When contain is used, bands around the image are filled with the dominant color (for opaque images) or left transparent (for images with an alpha channel). See here for more information.

Since this is all using Astro's image service API, you can continue using Astro's <Image /> component, the getImage() function from astro:assets or the _image API endpoint as usual. Note that you can now use the new fit parameter to specify the fitting strategy:

<Image src="/path/to/image.jpg" width={1200} height={630} fit="cover" />

const img = await getImage('/path/to/image.jpg', { width: 1200, height: 630, fit: 'cover' })

<img src={`/_image?href=http://localhost:4321/path/to/image.jpg&w=1200&h=630&fit=cover`} />

[!NOTE] I might implement an alternative band-filling method for the contain strategy in the future, where a blurred, low-resolution version of the image fills the background as if cover was used before the actual image is drawn on top of it. Yes, you've seen it elsewhere already, and it looks much nicer than a solid color or transparency. Let me know if you'd like that open and consider supporting my work!

Default output format

Astro doesn't let you change the default output format of the image service. It always outputs images in WEBP format, which used to be great but is now becoming obsolete as AVIF compresses much better and is supported in every major browser.

Using this image service, you can change the default image format in the options passed to the integration. The default format is already avif, but you can change it back to webp, or even use jpeg if you prefer.

import { defineConfig } from 'astro/config'
import image from '@jcayzac/astro-image-service-ng'

export default defineConfig({
  integrations: [
    image({
      // let's get retro!
      defaultFormat: 'jpeg',
    }),
  ],
  // …other options
})

Persistence

When you build your site, Astro's built-in image service generates images on the fly and caches them in the build cache that resides under node_modules/.astro. This folder is usually picked up by build pipelines and cached between runs, so that you don't have to rebuild the same variants of your images the next time.

It's great, except when the build cache gets invalidated for whatever reason. This sometimes happens when the build pipeline uses the current branch or the operating system it executes on as a key for the build cache. Invalidating the build cache manually may also be the only way to solve some completely unrelated issues. Lastly, some people like to just wipe out node_modules entirely before building something locally, just to make sure they have a "clean" install. All in all, tying your asset cache to your build cache might not be the best strategy for everybody.

And this is just for caching assets on the disk. But what if you want to cache them somewhere else, for instance in some S3 bucket? Or use some of the transform parameters in the file names, so that you know which file represents each variant? This may be useful if you want to migrate out of Astro at some point in the future and want to reuse those images without going through all the transforms again —there's no guarantee the software then will still support specific image transforms you did 10 years before.

This module supports peristence through arbitrary stores by leveraging @copepod/kv, which lets you configure named stores statically. For instance, using the built-in @copepod/kv/fs-composite store backend, it's trivial to implement an on-disk persistent store where file names include an image's dimensions:

// kv.config.ts
import { defineConfig } from '@copepod/kv/types'

export default defineConfig({
  stores: [
    {
      id: 'generated-images',
      use: '@copepod/kv/fs-composite',
      with: {
        path: 'generated',
        pattern: '{name}[{width}x{height}].{__hash}.{format}',
      },
    },
  ],
})

// astro.config.ts
import { defineConfig } from 'astro/config'
import image from '@jcayzac/astro-image-service-ng'

export default defineConfig({
  integrations: [
    image({
      // use whatever kv store is defined for this identifier
      kv: 'generated-images',
    }),
  ],
  // …other options
})

{name}, {width}, etc are interpolators. The image service passes a composite key with the following fields:

// All the parameters of the resolved transform are included
interface Key extends Omit<ResolvedTransform, 'src'> {
  // The base name of the image, without any extension.
  name: string

  // The source metadata.
  src: sharp.Metadata

  // The format of the image, detected from the source metadata.
  format: string

  // The digest of the entire key, excluding this field.
  digest: string
}

[!TIP] Creating and publishing new store backends for @copepod/kv is easy —you just need to implement a small interface. Have a look at the built-in fs-simple and fs-composite backends here for some example.

Like it? Buy me a coffee!

If you like anything here, consider buying me a coffee using one of the following platforms: