react-optimized-images

A package to optimize images for React! It generates and uses responsive webp images with fallback to other formats, resulting in great performance on modern browsers and still supporting old browsers.

NOTE: If you created your app with CRA and it's not ejected or you don't have webpack as your bundler, you can use v1.

Table of contents

• Table of contents
• Features
• Requirements
• Installation
• Usage
  • Webpack plugin
  • Next.js plugin
  • Picture component
• License

Features

• Convert images to webp during build time.
• Create smaller versions of images based on breakpoints to avoid unnecessary load of big images on smaller devices.
• Lazy load images that are not in the viewport.
• React Component to make use of all the features with ease.

NOTE: Currently only images that are located within the project will be optimized.

TODO

• Add image optimization for external images.
• Add image optimization for CSS background images.
• Add support to older Node versions.
• Add unit tests.
• Add custom configuration at component level.

Requirements

• Node v14.0.0 or above installed.
• Webpack as your project bundler.

Installation

npm install react-optimized-images --save

or

yarn add react-optimized-images

Usage

Webpack plugin

This package generates images at build time, so you need to add the webpack plugin in your webpack.config.js.

1const OptimizedImagesPlugin = require('react-optimized-images/plugin');
2
3module.exports = {
4  // ... webpack config
5  plugins: [
6    // ... other plugins
7    new OptimizedImagesPlugin({ ...options }),
8  ],
9};

Options

Name	Type	Default value	Description
minWidth	number	200	Mininum image width to create smaller versions.
breakpoints	array	Default value	Specifies the breakpoints to generate responsive images. You can add as many breakpoints as you want.
enabled	boolean	true	If false, the images won't be generated and the component will render a regular image.
lazy	boolean	false	If true, all the images in the Picture component will be lazy loaded by default. It can be overriden by the lazy prop in the component.

Default breakpoints

1[
2  {
3    maxWidth: 576, // Max screen width in px
4    resizeTo: 50, // Percentage of original image to resize
5    // Example: An image with 1000px would be resized to 500px in a 576px or smaller screen
6  },
7  {
8    maxWidth: 992,
9    resizeTo: 70,
10  },
11];

Complete custom configuration example:

1const OptimizedImagesPlugin = require('react-optimized-images/plugin');
2
3module.exports = {
4  // ... webpack config
5  plugins: [
6    // ... other plugins
7    new OptimizedImagesPlugin({
8      minWidth: 300,
9      breakpoints: [
10        {
11          maxWidth: 576,
12          resizeTo: 50,
13        },
14        {
15          maxWidth: 992,
16          resizeTo: 80,
17        },
18      ],
19      enabled: process.env.NODE_ENV === 'production',
20      lazy: false,
21    }),
22  ],
23};

Next.js plugin

This package also has a plugin for Next.js projects. In your next.config.js add:

1const withOptimizedImages = require('react-optimized-images/next');
2
3module.exports = withOptimizedImages();

Example with custom configuration:

1const withOptimizedImages = require('react-optimized-images/next');
2
3module.exports = withOptimizedImages({
4  minWidth: 300,
5  breakpoints: [
6    {
7      maxWidth: 576,
8      resizeTo: 50,
9    },
10    {
11      maxWidth: 992,
12      resizeTo: 80,
13    },
14  ],
15});

Or if you use next-compose-plugins:

1const withPlugins = require('next-compose-plugins');
2const optimizedImages = require('react-optimized-images/next');
3
4module.exports = withPlugins([
5  // other plugins
6  [
7    optimizedImages,
8    /* Custom configuration
9    {
10       minWidth: 300
11    },
12    */
13  ],
14]);

Picture component

For an easier use of the generated images, you can use the Picture component, a wrapper for html <picture> tag. It looks for the optimized webp images and uses the default format as a fallback for older browsers, providing full support to all browsers.

Usage

1import React from 'react';
2import { Picture } from 'react-optimized-images';
3
4import CoffeeJpg from '../assets/coffee.jpg';
5
6export default function Home() {
7  return (
8    <div>
9      <Picture src={CoffeeJpg} />
10      {/* ..with Next v11.. */}
11      <Picture src={CoffeeJpg.src} />
12      {/* ..or if it comes from public folder */}
13      <Picture src="/coffee.jpg" />
14    </div>
15  );
16}

The output will be like

1<picture>
2  <source
3    srcset="/coffee@0.5x.webp"
4    media="(max-width: 576px)"
5    type="image/webp"
6  />
7  <source
8    srcset="/coffee@0.7x.webp"
9    media="(max-width: 992px)"
10    type="image/webp"
11  />
12  <source srcset="/coffee.webp" type="image/webp" />
13  <source
14    srcset="/coffee@0.5x.jpeg"
15    media="(max-width: 576px)"
16    type="image/jpeg"
17  />
18  <source
19    srcset="/coffee@0.7x.jpeg"
20    media="(max-width: 992px)"
21    type="image/jpeg"
22  />
23  <source srcset="/coffee.jpg" type="image/jpeg" />
24  <img src="/coffee.jpg" />
25</picture>

Properties

It uses the same properties from HTML <img> tag. Along with some specific properties as shown below:

Name	Type	Default value	Description
lazy	boolean	false	If true, the image will be loaded only when content is ready and the image is inside the viewport.
preview	ReactNode	undefined	A custom preview to be shown during image load if lazy is true. If preview is not set and height and width props are defined, a blurry version of the original image will be shown.

License

MIT © Marcelo Dornelles Junior