:sunrise: next-optimized-images

:heavy_exclamation_mark: Canary disclaimer :heavy_exclamation_mark:

Any feedback, ideas, bugs, or anything else about this new version is very much appreciated, either in the RFC issue or in a separate issue.

This is a canary version of next-optimized-images. If you want to use a non-canary version, please switch to the master branch.

This version is a complete rewrite and so has introduced breaking changes. If you want to update next-optimized-images in an existing project from version 2 to this canary version, please read the upgrading guide.

Compared to version 2, the following features are currently missing in the canary version:

• ?trace query param
• ?sprite query param

If your project depends on them, you have to wait a little more, but those features will get added again soon.

New features compared to the current version which are already in the canary version:

• Image optimization is performed either in node or WebAssembly - there is no need for imagemin plugins anymore and so no native binaries are required
• Build cache for images - results in way faster builds and images are also optimized in the dev environment by default
• Image components are provided for even easier use - there shouldn't be a need to use query params anymore normally (a babel plugin does that now for you)
• images.config.js for global configuration and definition and re-use of image types and their options
• Full typescript support thanks to the provided image components
• Query params can be chained now - for example ?webp&width=400
• ...and more. Read this readme file for an overview of all features.

---

Table of contents

• Installation
• Usage
  • Image components
  • Query params
• Configuration
  • next.config.js
  • images.config.js
• License

Installation

npm install next-optimized-images@canary

Requirements:

• Node >= 10
• Next.js >= 9

Enable the plugin in your Next.js configuration file:

1// next.config.js
2const withPlugins = require('next-compose-plugins');
3const optimizedImages = require('next-optimized-images');
4
5module.exports = withPlugins([
6  [optimizedImages, {
7    /* config for next-optimized-images */
8  }],
9
10  // your other plugins here
11
12]);

And add the react-optimized-image/plugin babel plugin to your .babelrc file. If you don't yet have a .babelrc file, create one with the following content:

1{
2  "presets": ["next/babel"],
3  "plugins": ["react-optimized-image/plugin"]
4}

If you are using typescript, add the following line to your next-env.d.ts file:

1/// <reference types="next-optimized-images-loader" />

See the configuration section for all available options.

The example above uses next-compose-plugins for a cleaner API when using many plugins, see its readme for a more detailed example. next-optimized-images also works with the standard plugin api:

1// next.config.js
2const withOptimizedImages = require('next-optimized-images');
3
4module.exports = withOptimizedImages({
5  /* config for next-optimized-images */
6
7  // your config for other plugins or the general next.js here...
8});

Usage

You can now import or require your images directly in your react components:

1import React from 'react';
2import Img from 'react-optimized-image';
3import MyImage from './images/my-image.jpg';
4
5export default () => (
6  <div>
7    {/* with import statement ..*/}
8    <Img src={MyImage} />
9
10    {/* ..or an inline require */}
11    <Img src={require('./images/my-small-image.png')} />
12  </div>
13);
14
15/**
16 * Results in:
17 *
18 * <div>
19 *   <img src="/_next/static/chunks/images/my-image-5216de428a8e8bd01a4aa3673d2d1391.jpg" />
20 *   <img src="data:image/png;base64,..." />
21 * </div>
22 */

If you are using CSS modules, this package also detects images and optimized them in url() values in your css/sass/less files:

1.Header {
2  background-image: url('./images/my-image.jpg');
3}

If the file is below the limit for inlining images, the require(...) will return a base64 data-uri (data:image/jpeg;base64,...).

Otherwise, next-optimized-images will copy your image into the static folder of next.js and the require(...) returns the path to your image in this case (/_next/static/chunks/images/my-image-5216de428a8e8bd01a4aa3673d2d1391.jpg).

Image components

For easier use and full typescript support, this plugin provides some image components.

Please note that all components need to be imported from the react-optimized-image package instead of next-optimized-images.

• Img
• Svg

Img

The Img component can be used to include a normal image. Additionally, it can create a WebP fallback and provide different sizes for different viewports.

Usage

1import Img from 'react-optimized-image';
2import MyImage from './images/my-image.jpg';
3
4export default () => (
5  <>
6    <h1>Normal optimized image</h1>
7    <Img src={MyImage} />
8
9    <h1>Image will be resized to 400px width</h1>
10    <Img src={MyImage} sizes={[400]} />
11
12    <h1>A WebP image will be served in two sizes: 400px and 800px</h1>
13    <h2>As a fallback, a jpeg image will be provided (also in both sizes)</h2>
14    <Img src={MyImage} webp sizes={[400, 800]} />
15  </>
16);
17
18/**
19 * Results in:
20 *
21 * <h1>Normal optimized image</h1>
22 * <img src="/_next/static/chunks/images/my-image-5216de428a8e8bd01a4aa3673d2d1391.jpg" />
23 *
24 * <h1>Image will be resized to 400px width</h1>
25 * <img src="/_next/static/chunks/images/my-image-572812a2b04ed76f93f05bf57563c35d.jpg" />
26 *
27 * <h1>A WebP image will be served in two sizes: 400px and 800px</h1>
28 * <h2>As a fallback, a jpeg image will be provided (also in both sizes)</h2>
29 * <picture>
30 *  <source type="image/webp" srcset="/_next/static/chunks/images/image-0cc3dc9faff2e36867d4db3de15a7b32.webp" media="(max-width: 400px)">
31 *  <source type="image/webp" srcset="/_next/static/chunks/images/image-08ce4cc7914a4d75ca48e9ba0d5c65da.webp" media="(min-width: 401px)">
32 *  <source type="image/jpeg" srcset="/_next/static/chunks/images/image-132d7f8860bcb758e97e54686fa0e240.jpg" media="(max-width: 400px)">
33 *  <source type="image/jpeg" srcset="/_next/static/chunks/images/image-9df4a476716a33461114a459e64301df.jpg" media="(min-width: 401px)">
34 *  <img src="/_next/static/chunks/images/image-0f5726efb3915365a877921f93f004cd.jpg"></picture>
35 * </picture>
36 */

Properties

Prop	Required	Type	Description
src	yes	string	Source image.
webp		boolean	If true, the image will get converted to WebP. For browsers which don't support WebP, an image in the original format will be served.
sizes		number[]	Resize the image to the given width. If only one size is present, an <img> tag will get generated, otherwise a <picture> tag for multiple sizes.
densities		number[]	Default: [1] Specifies the supported pixel densities. For example, to generate images for retina displays, set this value to [1, 2].
breakpoints		number[]	Specifies the breakpoints used to decide which image size to use (when the size property is present). If no breakpoints are specified, they will automatically be set to match the image sizes which is good for full-width images but result in too big images in other cases. The breakpoints should have the same order as the image sizes. Example for this query: sizes={[400, 800, 1200]} breakpoints={[600, 1000]} For widths 0px-600px the 400px image will be used, for 601px-1000px the 800px image will be used and for everything larger than 1001px, the 1200px image will be used.
inline		boolean	If true, the image will get forced to an inline data-uri (e.g. data:image/png;base64,...).
url		boolean	If true, the image will get forced to be referenced with an url, even if it is a small image and would get inlined by default.
original		boolean	If true, the image will not get optimized (but still resized if the sizes property is present).
type		string	So you don't have to repeat yourself by setting the same sizes or other properties on many images, specify the image type which equals to one in your global image config.
anything else		ImgHTMLAttributes	All other properties will be directly passed to the <img> tag. So it would for example be possible to use native lazy-loading with loading="lazy".

Svg

The Svg includes an svg file directly into the HTML so it can be styled by CSS. If you don't want to include them directly in the HTML, you can also use svg images together with the Img component which will reference it by the URL.

Usage

1import { Svg } from 'react-optimized-image';
2import Icon from './icons/my-icon.svg';
3
4export default () => (
5  <>
6    <h1>SVG will be directly included in the HTML</h1>
7    <Svg src={Icon} className="fill-red" />
8  </>
9);
10
11/**
12 * Results in:
13 *
14 * <span><svg class="fill-red" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="280" height="330"><g><path>...</path></g></svg></span>
15 */

Properties

Prop	Required	Type	Description
src	yes	string	Source image.
className		string	Class to apply to the <svg> tag.

Query params

Although it is suggested to use image components, query params directly within the import or require statement are also possible.

• ?include: Include the raw file directly (useful for SVG icons)
• ?webp: Convert an image to WebP on the fly
• ?inline: Force inlining an image (data-uri)
• ?url: Force an URL for a small image (instead of data-uri)
• ?original: Use the original image and do not optimize it
• ?lqip: Generate a low quality image placeholder
• ?colors: Extract the dominant colors of an image
• ?width: Resize an image to the given width
• ?height: Resize an image to the given height
• ?trace: Use traced outlines as loading placeholder (currently not supported)
• ?sprite: Use SVG sprites (currently not supported)

?include

The image will now directly be included in your HTML without a data-uri or a reference to your file.

?webp

If this ?webp query parameter is specified, next-optimized-images automatically converts the image to the new WebP format.

For browsers that don't yet support WebP, you may want to also provide a fallback using the <picture> tag or use the Img component which does this out of the box:

?inline

You can specify a limit for inlining images which will include it as a data-uri directly in your content instead of referencing a file if the file size is below that limit.

You usually don't want to specify a too high limit but there may be cases where you still want to inline larger images.

In this case, you don't have to set the global limit to a higher value but you can add an exception for a single image using the ?inline query options.

?url

When you have an image smaller than your defined limit for inlining, it normally gets inlined automatically. If you don't want a specific small file to get inlined, you can use the ?url query param to always get back an image URL, regardless of the inline limit.

?original

The image won't get optimized and used as it is. It makes sense to use this query param if you know an image already got optimized (e.g. during export) so it doesn't get optimized again a second time.

?lqip

When using this resource query, a very small (about 10x10 pixel) image gets created. You can then display this image as a placeholder until the real (big) image has loaded.

?colors

This resource query returns you an array with hex values of the dominant colors of an image. You can also use this as a placeholder until the real image has loaded (e.g. as a background) like the Google Picture Search does.

The number of colors returned can vary and depends on how many different colors your image has.

1import React from 'react';
2
3export default () => (
4  <div style={{ backgroundColor: require('./images/my-image.jpg?colors')[0] }}>...</div>
5);
6
7/**
8 * require('./images/my-image.jpg?colors')
9 *
10 * returns for example
11 *
12 * ['#0e648d', '#5f94b5', '#a7bbcb', '#223240', '#a4c3dc', '#1b6c9c']
13 */

?trace

Currently not supported

With the ?trace resource query, you can generate SVG image outlines which can be used as a placeholder while loading the original image.

?width

Resizes the source image to the given width. If a height is additionally specified, it ensures the image covers both sizes and crops the remaining parts. If no height is specified, it will be automatically calculated to preserve the image aspect ratio.

1import React from 'react';
2import Image from './images/my-image.jpg?width=800';
3import Thumbnail from './images/my-image.jpg?width=300&height=300';
4
5export default () => (
6  <div>
7    <img src={Image} />
8    <img src={Thumbnail} />
9  </div>
10);

?height

Resizes the source image to the given height. If a width is additionally specified, it ensures the image covers both sizes and crops the remaining parts. If no width is specified, it will be automatically calculated to preserve the image aspect ratio.

1import React from 'react';
2import Image from './images/my-image.jpg?height=800';
3import Thumbnail from './images/my-image.jpg?width=300&height=300';
4
5export default () => (
6  <div>
7    <img src={Image} />
8    <img src={Thumbnail} />
9  </div>
10);

?sprite

Currently not supported

If you need to style or animate your SVGs ?include might be the wrong option, because that ends up in a lot of DOM elements, especially when using the SVG in list-items etc.

1import React from 'react';
2import MyIcon from './icons/my-icon.svg?sprite';
3
4export default () => (
5  <div>
6    my page..
7    <MyIcon />
8  </div>
9);

To also make this work for server-side rendering, you need to add these changes to your _document.jsx file (read here if you don't have this file yet):

1// ./pages/_document.js
2import Document, { Head, Main, NextScript } from 'next/document';
3import sprite from 'svg-sprite-loader/runtime/sprite.build';
4
5export default class MyDocument extends Document {
6  static async getInitialProps(ctx) {
7    const initialProps = await Document.getInitialProps(ctx);
8    const spriteContent = sprite.stringify();
9
10    return {
11      spriteContent,
12      ...initialProps,
13    };
14  }
15
16  render() {
17    return (
18      <html>
19        <Head>{/* your head if needed */}</Head>
20        <body>
21          <div dangerouslySetInnerHTML={{ __html: this.props.spriteContent }} />
22          <Main />
23          <NextScript />
24        </body>
25      </html>
26    );
27  }
28}

Configuration

This plugin uses optimized-images-loader under the hood which is based on mozjpeg, oxipng, svgo, gifsicle and sharp.

The default options for these optimizers should be enough in most cases, but you can overwrite every available option if you want to.

next.config.js

All options listed above must be provided within the images object in your config file:

1// next.config.js
2const withPlugins = require('next-compose-plugins');
3const optimizedImages = require('next-optimized-images');
4
5module.exports = withPlugins([
6  [optimizedImages, {
7    images: {
8      // for example
9      handleImages: ['jpeg', 'png', 'svg', 'webp', 'gif', 'ico']
10    }
11  }],
12]);

Available options:

Option	Default	Type	Description
handleImages	['jpeg', 'png', 'svg', 'webp', 'gif']	string[]	next-optimized-images registers the webpack loader for all these file types. If you don't want one of these handled by next-optimized-images simply remove it from the array.
limit	8192	number	Images smaller than this number (in bytes) will get inlined with a data-uri.
optimize	true	boolean	If this plugin should not optimized images, set this to false. You can still resize images, convert them to WebP and use other features in that case.
cacheFolder	'node_modules/optimized-images-loader/.cache'	string	Images will be cached in this folder to avoid long build times.
name	'[name]-[contenthash].[ext]'	string	File name of the images after they got processed. Additionally to the default placeholders, [width] and [height] are also available.
outputPath	'static/chunks/images/'	string	Images will be saved in this directory within the .next folder.
publicPath	'/_next/static/chunks/images/'	string	The public path that should be used for image URLs. This can be used to serve the optimized image from a cloud storage service like S3. From version 2 on, next-optimized-images uses the assetPrefx config of next.js by default, but you can overwrite it with publicPath specially for images.
mozjpeg		MozjpegOptions	Specifies the options used to optimize jpeg images. All available options can be seen here.
oxipng		OxipngOptions	Specifies the options used to optimize png images. All available options can be seen here.
gifsicle		GifsicleOptions	Specifies the options used to optimize png images. All available options can be seen here.
webp		WebpOptions	Specifies the options used to optimize webp images. All available options can be seen here.
svgo		SvgoOptions	Specifies the options used to optimize svg images. All available options can be seen here.

images.config.js

This file contains default image optimization options and is located in the root of your project, next to the next.config.js file.

Available options:

Option	Type	Description
default	ImgProps	Properties specified within the default key will get applied to all usages of the Img components. All properties of the Img component can be set. For example, to convert all your images to WebP, set { webp: true }.
types	Record<string, ImgProps>	Instead of specifying options for all images with the default key, you can create as many image types as you want. Those can also contain all properties of the Img component. The options specified in the default key will also get applied here if they are not overwritten.

Example

1module.exports = {
2  default: {
3    webp: true,
4  },
5  types: {
6    thumbnail: {
7      sizes: [200, 400],
8      breakpoints: [800],
9      webp: false,
10    },
11  },
12};

Important: When you make changes on this config file, you have to manually remove the .next/cache folder and restart next in order to see the changes. This issue will get resolved in the next canary version.

This will convert all images to WebP. The images with the thumbnail type will be generated in two sizes (200, 400) but not converted to WebP. If webp: false would not be present, it would get inherited from the default key.

1import React from 'react';
2import Img from 'react-optimized-image';
3import MyImage from './images/my-image.jpg';
4
5export default () => (
6  <div>
7    {/* This will get converted into a WebP image (while still providing a fallback image). */}
8    <Img src={MyImage} />
9
10    {/* This will be provided in to sizes (200, 400) but not get converted to WebP. */}
11    <Img src={MyImage} type="thumbnail" />
12  </div>
13);

License

Licensed under the MIT license.

© Copyright Cyril Wanner