Image

Parcel has built in support for resizing, converting, and optimizing images. Images can be referenced from HTML, CSS, JavaScript, or any other file type.

Resizing and converting images

#

Parcel includes an image transformer out of the box, which allows you to resize images, convert them to a different format, or adjust the quality to reduce file size. This can be done using query parameters when referencing the image, or using a configuration file.

The image transformer relies on the Sharp image transformation library, which will be automatically installed as a dev dependency into your project when needed.

The query parameters you can use are:

Image formats

#

The following image formats are supported, both as input and as output via the as query parameter:

The following formats are also supported as inputs, but are not generally supported by browsers: tiff, heic / heif, and raw.

GIFs are also supported if you setup a custom libvips build, however, using GIFs is discouraged due to their large file sizes. Use a video format instead.

For more guidance on choosing the right image formats, see the guide on web.dev.

JavaScript

#

To reference an image from JavaScript, use the URL constructor. For more details, see URL dependencies in the JavaScript docs.

main.js: 
const imageUrl = new URL(
  'image.jpeg?as=webp&width=250',
  import.meta.url
);

HTML

#

To reference an image from HTML, use the <img> or <picture> element. The same image can be referenced multiple times with different query parameters to create multiple versions in different formats or sizes. See the HTML docs for more details.

index.html: 
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>HTML Example</title>
  </head>
  <body>
    <picture>
      <source srcset="image.jpeg?as=avif&width=800" type="image/avif" />
      <source srcset="image.jpeg?as=webp&width=800" type="image/webp" />
      <source srcset="image.jpeg?as=jxl&width=800" type="image/jxl" />
      <source srcset="image.jpeg?width=800" type="image/jpeg" />
      <img src="image.jpeg?width=200" alt="test image" />
    </picture>
  </body>
</html>

Configuration

#

In addition to query parameters, Parcel also supports using a configuration file to define options that apply to all of the images in your project. For example, you could re-encode all images at a certain quality setting to reduce file size, or define more advanced options for each output format.

To set the quality across all images in your project, create a sharp.config.json file in your project and define the quality field. This will re-encode every image, not just ones referenced with query params.

sharp.config.json: 
{
  "quality": 80
}

You can also define more advanced options per format. All images in formats with options defined in sharp.config.json will be re-encoded. See the full list of supported options here.

sharp.config.json: 
{
  "jpeg": {
    "quality": 75,
    "chromaSubsampling": "4:4:4"
  },
  "webp": {
    "nearLossless": true
  },
  "png": {
    "palette": true
  }
}

Image optimization

#

Parcel also includes lossless image optimization for JPEGs and PNGs by default in production mode, which reduces the size of images without affecting their quality. This does not require any query parameters or configuration to use. However, since the optimization is lossless, the size reduction possible may be less than if you use the quality query param, or use a modern format such as WebP or AVIF.

Disabling image optimization

#

To disable the default image optimization for JPEGs and PNGs in production mode, add the following to your .parcelrc configuration file:

.parcelrc: 
{
  "extends": "@parcel/config-default",
  "optimizers": {
    "*.{jpg,jpeg,png}": []
  }
}