@blaze-cms/image-cdn-react v0.3.0-alpha.6

Blaze image cdn React

This package uses an aws service that will reescale our images and will return us a batch of image urls ready to be render in a responsive way.

How to use this package

Config and sizeKey

The image sizes are defined in a config object similar to below. This defines sizes based on certain "size keys".

{
  "sizes": {
    "landscape": {
      "widths": {
        "300w": {
          "r": {
            "width": 300,
            "height": 200
          }
        },
        "600w": {
          "r": {
            "width": 600,
            "height": 400
          }
        }
      },
      "sizes": "(max-width: 300px) 100vw, 80vw"
    },
    "landscape:logo": {
      "disabled": true
    },
    "landscape:variation": {
      "widths": {
        "200w": {
          "r": {
            "width": 200,
            "height": 100
          }
        }
      },
      "sizes": "(max-width: 200px) 100vw, 80vw"
    },
    "portrait": {
      "widths": {
        "300w": {
          "r": {
            "width": 300,
            "height": 400
          }
        },
        "600w": {
          "r": {
            "width": 600,
            "height": 800
          }
        }
      },
      "sizes": "(max-width: 300px) 100vw, 80vw"
    },
    "card": {
      "widths": {
        "300w": {
          "r": {
            "width": 300,
            "height": 200
          }
        },
        "600w": {
          "r": {
            "width": 600,
            "height": 400
          }
        }
      },
      "sizes": "(max-width: 300px) 100vw, 80vw"
    },
    "social": {
      "single": {
        "r": {
          "width": 300,
          "height": 300
        }
      }
    }
  }
}

When rendering an image or getting a converted url the config and a certain sizeKey are used to get the dimensions specific for the sizeKey (examples below)

Size keys can be hierarchical so you can specify a sizeKey variation and if the key isn't present it will fall back on the parent.

For example for the sizeKey "hero:landscape:small" this would check the config for the following keys in order and use the first match

1. hero:landscape:small
2. hero:landscape
3. hero

So if no config had been set for 1 and 2 then the config for 3 would be returned.

Component will render an standard image tag using the provided src e.g

<img src="https://images.blazecms.app/logo.png" alt="Logo image" />

in following cases:

• there is no matching size key in config
• size key is disabled in config using disabled: true syntax
• image extension is disabled e.g. *.svg

React component

import { ResponsiveImageProvider, ResponsiveImage } from '@blaze-cms/@blaze-cms/image-cdn-react';
...
<ResponsiveImageProvider config={config}>
  <ResponsiveImage
    src="https://images.blazecms.app/logo.png"
    alt="Logo image"
    sizeKey="landscape"
  />
</ResponsiveImageProvider>

As you notice this package will export two react components:

• ResponsiveImageProvider: Will receive a config file that should match with the format defined in Config format example.
• ResponsiveImage: Will receive a src and alt attributes as regular img tag but also will receive a sizeKey that should be included as a key in our config file.

The ResponsiveImage will use the props and config to render a picture tag with webp and original format source tags. It sets the first webp image as the img src property to help optimise loading for browsers like safari which can load the responsive images inconsistently. So if you want the smallest image as the src put that key first, if a larger image put that key first.

Example

<picture>
    <source
      data-testid="responsive-image-webp"
      sizes="(max-width: 300px) 100vw, 80vw"
      srcset="https://images.blazecms.app/convert/files/2020/01/image-name.jpg/r%5Bwidth%5D=300&r%5Bheight%5D=200/image-name.webp 300w,https://images.blazecms.app/convert/files/2020/01/image-name.jpg/r%5Bwidth%5D=600/image-name.webp 600w"
      type="image/webp"
    />
    <source
      data-testid="responsive-image-original"
      sizes="(max-width: 300px) 100vw, 80vw"
      srcset="https://images.blazecms.app/convert/files/2020/01/image-name.jpg/r%5Bwidth%5D=300&r%5Bheight%5D=200/image-name.jpg 300w,https://images.blazecms.app/convert/files/2020/01/image-name.jpg/r%5Bwidth%5D=600/image-name.jpg 600w"
    />
    <img
      alt="Logo image"
      data-testid="responsive-image"
      src="https://images.blazecms.app/convert/files/2020/01/image-name.jpg/r%5Bwidth%5D=300&r%5Bheight%5D=200/image-name.webp"
      style="width: 100%;"
    />
  </picture>

Preloading images

It is possible to preload the responsive images by passing a HeadComponent to the the ResponsiveImage component. The HeadComponent should be something like react-helment or next/head that are able to render child components in the head of a page. The is component will have responsive image preload link tags added to it.

import Head from 'next/head';
...
<ResponsiveImageProvider config={config}>
  <ResponsiveImage
    src="https://images.blazecms.app/logo.png"
    alt="Logo image"
    sizeKey="landscape"
    HeadComponent={Head}
  />
</ResponsiveImageProvider>

This would add something like the following wrapped in the HeadComponent

<link
  rel="preload"
  href="https://images.blazecms.app/convert/files/2020/01/image-name.jpg/r%5Bwidth%5D=300&r%5Bheight%5D=200/image-name.webp"
  imagesizes="(max-width: 300px) 100vw, 80vw"
  imagesrcset="https://images.blazecms.app/convert/files/2020/01/image-name.jpg/r%5Bwidth%5D=300&r%5Bheight%5D=200/image-name.webp 300w,https://images.blazecms.app/convert/files/2020/01/image-name.jpg/r%5Bwidth%5D=600/image-name.webp 600w"
/>

Single image util - getSingleConvertedImagePath

The package also exports a helper function "getSingleConvertedImagePath" to get a single image path for use in places like social meta tags. For example

import { getSingleConvertedImagePath } from '@blaze-cms/image-cdn-react';

const convertedSrc = getSingleConvertedImagePath({ src, config, sizeKey: 'social' });
console.log(convertedSrc); // 'https://images.blazecms.app/convert/logo.png/r%5Bwidth%5D=300&r%5Bheight%5D=300/logo.png

This function will try and get the image config for the sizeKey from the one specified in size property then the single property (see social example below). If neither are found it will use the first entry from widths e.g

import { getSingleConvertedImagePath } from '@blaze-cms/image-cdn-react';

const convertedSrc = getSingleConvertedImagePath({ src, config, sizeKey: 'landscape' });
console.log(convertedSrc); // 'https://images.blazecms.app/convert/logo.png/r%5Bwidth%5D=300&r%5Bheight%5D=200/logo.png
...
const convertedSrc = getSingleConvertedImagePath({ src, config, sizeKey: 'landscape', size: '600w' });
console.log(convertedSrc); // 'https://images.blazecms.app/convert/logo.png/r%5Bwidth%5D=600/logo.png