Rocket Logo Rocket Guides Docs Blog Toggle darkmode

Configuration: Images

Rocket does handle content images automatically by

  • producing multiple sizes so users download images that are meant for their resolution
  • outputting multiple formats so the device can choose the best image format it supports

And the best thing about is you don't need to do anything.

Usage

If you are using markdown images you are good to go.

![My Image](path/to/image.jpg)

will result in

<picture>
  <source
    type="image/avif"
    srcset="/images/5f03d82-300.avif 300w, /images/5f03d82-820.avif 820w"
    sizes="(min-width: 1024px) 820px, calc(100vw - 20px)"
  />
  <source
    type="image/jpeg"
    srcset="/images/5f03d82-300.jpeg 300w, /images/5f03d82-820.jpeg 820w"
    sizes="(min-width: 1024px) 820px, calc(100vw - 20px)"
  />
  <img
    alt="My Image"
    rocket-image="responsive"
    src="/images/5f03d82-300.jpeg"
    width="300"
    height="158"
    loading="lazy"
    decoding="async"
  />
</picture>

Benefits

The main benefit is that we can serve the correct size and optimal image format depending on the browser capabilities leading to optimal loading times on different systems.

  • Smaller images for smaller screens

    When providing srcset and sizes the browser can decide which image makes the most sense to download. This will lead to much faster websites especially on mobile where smaller images can be served. If you wanna know more check out The anatomy of responsive images.

  • Serve the best/smallest image format the browser understands

    There are currently ~3 formats you may want to consider avif, webp and jpg. The improvements are huge webp is ~30% and avif ~50% smaller then the original jpg.

Adding a caption

If you want to describe your image in more detail you can add a caption

![My Image](path/to/image.jpg 'My caption text')

will result in

<figure>
  <picture>
    <!-- picture code the same as above -->
  </picture>
  <figcaption>My caption text</figcaption>
</figure>

Adjusting options

Under the hood it is using 11ty/image and all it's options are available.

If you are using a layout preset like @rocket/launch then you probably don't want to touch/change these options as the preset will set it for you accordion to its layout needs.

The default preset for regular markdown content is available as responsive.

👉 rocket.config.js

export default {
  imagePresets: {
    responsive: {
      widths: [300, 820],
      formats: ['avif', 'jpeg'],
      sizes: '(min-width: 1024px) 820px, calc(100vw - 20px)',
    },
  },
};

Defining your own presets

You can add your own image preset like so

export default {
  imagePresets: {
    'my-image-preset': {
      widths: [30, 60],
      formats: ['avif', 'jpeg'],
      sizes: '(min-width: 1024px) 30px, 60px',
    },
  },
};

Once that imagePreset is defined you can use it by adding it to any img tag.

<img src="./path/to/image.jpg" alt="my alt" rocket-image="my-image-preset" />

How does it work?

  1. Each markdown image ![my image](path/to/image.jpg) gets rendered as <img src="path/to/image.jpg" alt="my image" rocket-image="responsive">
  2. We parse the html output and process every image which has rocket-image
  3. Get the image preset settings from the name e.g. rocket-image="my-image-preset" reads imagePreset['my-image-preset']
  4. Pass the settings onto @11ty/image to generate the image sizes and formats
  5. With the metadata we render the html

Default Formats

An image file format is a way of storing common image formats. Each format varies in capabilities like compression algorithm, availability, progressive rendering, encode and decode time, ... Ultimately newer formats are usually smaller while retaining image quality which leads to faster websites.

By default, we generate avif and jpg because

  • we only want to generate two versions to limit CI time and html size
  • avif is significantly smaller than webp
  • avif is available in
    • Chrome since August 2020
    • Firefox since June 2021
  • jpg as a fallback for Edge, Safari, IE11
  • webp would only help a small percentage of Edge & Safari on macOS 11 (Big Sur) users

This leads to the following situation:

  • Chrome, Firefox gets the small avif
  • Edge, Safari, IE11 gets the bigger jpg

To learn more about avif take a look at AVIF has landed.

If you want to add webp (or replace avif with it) you can do so by setting the formats

👉 rocket.config.js

export default {
  imagePresets: {
    responsive: {
      formats: ['avif', 'webp', 'jpeg'],
    },
  },
};

Default widths

In order to understand the need for having a single image in multiple resolutions we need to understand the our website is served to many different environments and each may come with its own specific device pixel ratio (DPR). The device pixel ratio is the ratio between physical pixels and logical pixels. For instance, the Galaxy S20 report a device pixel ratio of 3, because the physical linear resolution is triple the logical linear resolution.

Physical resolution: 1440 x 3200 Logical resolution: 480 x 1067

And 1440 / 480 = 3.

By default, we generate the following widths 600, 900 and 1640 because

  • we only want to generate a small amount of widths to limit CI time and service worker cache size
  • 600 is good for mobile with DRP 2
  • 900 is good for mobile with DRP 3 and desktop with DPR of 1
  • 1640 is good for desktop with DPR of 2

If you want to add more widths you can add them to widths.

👉 rocket.config.js

export default {
  imagePresets: {
    responsive: {
      widths: [300, 600, 900, 1200, 1640],
      sizes: '(min-width: 1024px) 820px, calc(100vw - 20px)',
    },
  },
};

As an end user in most cases you don't want to mess with this as a layout preset should set this for you. If you are building your own layout preset then be sure to set widths and sizes via adjustImagePresets

export function myPreset() {
  return {
    adjustImagePresets: imagePresets => ({
      ...imagePresets,
      responsive: {
        ...imagePresets.responsive,
        widths: [600, 900, 1640],
        sizes: '(min-width: 1024px) 820px, calc(100vw - 40px)',
      },
    }),
  };
}