@flatbread/resolver-svimg 🖼️

Optimize images for specific fields in content

💾 Install

Use pnpm, npm, or yarn:

pnpm i @flatbread/resolver-svimg

👩‍🍳 Usage

update your flatbread.config.js to optimize images referenced in your content.

// flatbread.config.js
import defineConfig from '@flatbread/config';
import transformer from '@flatbread/transformer-markdown';
import filesystem from '@flatbread/source-filesystem';
import { createSvImgField } from '@flatbread/resolver-svimg';

const transformerConfig = {
  markdown: {
    gfm: true,
    externalLinks: true,
  },
};

export default defineConfig({
  source: filesystem({ extensions: ['.md', '.mdx', '.markdown'] }),
  transformer: transformer(transformerConfig),
  content: [
    {
      path: 'content/posts',
      collection: 'Post',
      refs: {
        authors: 'Author',
      },
    },
    {
      path: 'content/authors',
      collection: 'Author',
      refs: {
        friend: 'Author',
      },
      overrides: [
        createSvImgField('image', { // the field in your content that references your image
          inputDir: 'static/authorImages', // the base directory of your source images
          outputDir: 'static/g', // where to store your optimized images (these should be committed)
          publicPath: '/g', //the base path to add onto the urls in the query data
        }),
        })
      ]
    },
  ],
});

🧰 Options

Since we use rely on svimg for processing images we expose all of their config located here https://github.com/xiphux/svimg#preprocessor-options

for a better experience, here is a copy pasta of the relevent section of their readme

| Option | Default | | | ------------ | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | inputDir | required | The static asset directory where image urls are retrieved from | | outputDir | required | The output directory where resized image files should be written to. This should usually be a subdirectory within the normal static asset directory | | srcGenerator | | An optional function to override the logic of how src URLs are generated for the srcset. This is called once per generated image file, and can be used to customize the generated image URLs - for example, to add or remove path components or to specify a CDN domain.The expected callback signature is:(path: string, { src, inputDir, outputDir }?: SrcGeneratorInfo) => stringThe first parameter is the path to the generated image relative to the outputDir, with path separators already normalized to /. The second optional parameter provides the original image src and the inputDir/outputDir options, and the return value is the URL for the image to be used in the srcset.The default behavior without this parameter will work for common use cases, where the outputDir is a subdirectory of the inputDir static asset directory and the site is served from the root of the domain. | | publicPath | The outputDir relative to the inputDir static asset directory | DEPRECATED publicPath is deprecated and will be removed in the next major version. Use a srcGenerator function instead: (path) => '/my/public/path' + pathThe public path that images will be served from. This will be prepended to the src url during preprocessing. | | avif | true | Whether to generate AVIF versions of images in addition to the original image formats | | webp | true | Whether to generate WebP versions of images in addition to the original image formats |

Querying the data

When overriding a field, your image will be processed and the resulting type will be converted into an SvImg type, querying all of the fields would like this this in gql

image {
  srcset
  srcsetwebp
  srcsetavif
  placeholder
  aspectratio
}

we recommend querying all of the fields, and taking advantage of the fantastic web component exposed by svimg to handle these props -- again, we will copy pasta the relevant docs

when using this component in an framework that supports SSR, s-image needs to be imported client side only

In sveltekit this can be achieved with

if (browser) { import('svimg/dist/s-image'); }

<script>
  import 'svimg/dist/s-image';
</script>

<s-image
  srcset="images/splash-600.jpg 600w, images/splash-1200.jpg 1200w"
  srcsetavif="images/splash-600.avif 600w, images/splash-1200.avif 1200w"
  srcsetwebp="images/splash-600.webp 600w, images/splash-1200.webp 1200w"
/>

Configuration

Component Attributes

| Property | Default | | | --------- | --------------- | ------------------------------------------------------------------------------------------------------------------ | | src | required | Image url | | alt | | Alternate text for the image | | class | | CSS classes to apply to image | | width | | Resize image to specified width in pixels. If not specified, generates images of widths 480, 1024, 1920, and 2560. | | immediate | false | Set to true to disable lazy-loading | | blur | 40 | Amount of blur to apply to placeholder | | quality | sharp default | Quality of the resized images, defaults to sharp's default quality for each image format |

Things of note

The configuration provided in flatbread.config.js will affect what fields are populated when querying the related fields. Based on that provided configuration, specific fields will always return null, for example:

| configuration field | default | note | | ------------------- | ------- | ---------------------------------------------------- | | skipPlaceholder | false | setting to true placerholder will always be null | | srcsetavif | true | setting to false srcsetavif will always be null | | srcsetwebp | true | setting to false srcsetwebp will always be null |