# :sunrise: next-optimized-images [![npm version](https://badgen.net/npm/v/next-optimized-images)](https://www.npmjs.com/package/next-optimized-images) [![license](https://badgen.net/github/license/cyrilwanner/next-optimized-images)](https://github.com/cyrilwanner/next-optimized-images/blob/master/LICENSE) [![downloads](https://badgen.net/npm/dt/next-optimized-images)](https://www.npmjs.com/package/next-optimized-images) **:bulb: Version 3 is coming!** It introduces a complete rewrite with many new features and bugfixes. If you want to help developing and testing the upcoming major version, please check out the [canary branch](https://github.com/cyrilwanner/next-optimized-images/tree/canary) for installation instructions and more information about the new features. ([RFC issue](https://github.com/cyrilwanner/next-optimized-images/issues/120)) --- Automatically optimize images used in [next.js](https://github.com/zeit/next.js) projects (`jpeg`, `png`, `svg`, `webp` and `gif`). Image sizes can often get reduced between 20-60%, but this is not the only thing `next-optimized-images` does: * **Reduces image size** by optimizing images during build * Improves loading speed by providing **progressive images** (for formats that support it) * **Inlines small images** to save HTTP requests and additional roundtrips * Adds a content hash to the file name so images can get cached on CDN level and in the browser for a long time * Same image URLs over multiple builds for long time caching * Provides **[query params](#query-params)** for file-specific handling/settings * jpeg/png images can be **converted to [`webp` on the fly](#webp)** for an even smaller size * Provides the possibility to use **[`SVG sprites`](#sprite)** for a better performance when using the same icons multiple times (e.g. in a list) * Can **[resize](#resize)** images or generate different **placeholders while lazy loading** images: [low quality images](#lqip), [dominant colors](#lqip-colors) or [image outlines](#trace) ## Table of contents - [Installation](#installation) - [Optimization Packages](#optimization-packages) - [Usage](#usage) - [Query Params](#query-params) - [Configuration](#configuration) - [Example](#example) - [See also](#see-also) - [License](#license) ## Installation ``` npm install next-optimized-images ``` *Node >= 8 is required for version 2. If you need to support older node versions, you can still use [version 1](https://github.com/cyrilwanner/next-optimized-images/tree/v1#readme) of next-optimized-images.* Enable the plugin in your Next.js configuration file: ```javascript // next.config.js const withPlugins = require('next-compose-plugins'); const optimizedImages = require('next-optimized-images'); module.exports = withPlugins([ [optimizedImages, { /* config for next-optimized-images */ }], // your other plugins here ]); ``` See the [configuration](#configuration) section for all available options. :warning: **From version 2 on, images won't get optimized out of the box anymore. You have to install the optimization packages you really need in addition to this plugin.** This doesn't force you to download big optimization libraries you don't even use. Please check out the table of all [optional optimization packages](#optimization-packages). The example above uses [next-compose-plugins](https://github.com/cyrilwanner/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: ```javascript // next.config.js const withOptimizedImages = require('next-optimized-images'); module.exports = withOptimizedImages({ /* config for next-optimized-images */ // your config for other plugins or the general next.js here... }); ``` ## Optimization Packages Starting from version 2, you have to install the optimization packages you need in your project in addition to this plugin. `next-optimized-images` then detects all the supported packages and uses them. **So you only have to install these packages with npm, there is no additional step needed after that.** The following optimization packages are available and supported: | Optimization Package | Description | Project Link | | -------------------- | ----------- | ------------ | | `imagemin-mozjpeg` | Optimizes JPEG images. | [Link](https://www.npmjs.com/package/imagemin-mozjpeg) | `imagemin-optipng` | Optimizes PNG images. | [Link](https://www.npmjs.com/package/imagemin-optipng) | `imagemin-pngquant` | Alternative for optimizing PNG images. | [Link](https://www.npmjs.com/package/imagemin-pngquant) | `imagemin-gifsicle` | Optimizes GIF images. | [Link](https://www.npmjs.com/package/imagemin-gifsicle) | `imagemin-svgo` | Optimizes SVG images and icons. | [Link](https://www.npmjs.com/package/imagemin-svgo) | `svg-sprite-loader` | Adds the possibility to use svg sprites for a better performance. Read the [sprite](#sprite) section for more information. | [Link](https://www.npmjs.com/package/svg-sprite-loader) | `webp-loader` | Optimizes WebP images and can convert JPEG/PNG images to WebP on the fly ([webp resource query](#webp)). | [Link](https://www.npmjs.com/package/webp-loader) | `lqip-loader` | Generates low quality image placeholders and can extract the dominant colors of an image ([lqip resource query](#lqip)) | [Link](https://www.npmjs.com/package/lqip-loader) | `responsive-loader` | Can resize images on the fly and create multiple versions of it for a `srcset`.
**Important**: You need to additionally install either `jimp` (node implementation, slower) or `sharp` (binary, faster) | [Link](https://www.npmjs.com/package/responsive-loader) | `image-trace-loader` | Generates SVG image [outlines](https://twitter.com/mikaelainalem/status/918213244954861569) which can be used as a placeholder while loading the original image ([trace resource query](#trace)). | [Link](https://www.npmjs.com/package/image-trace-loader) > Example: If you have JPG, PNG, and SVG images in your project, you would then need to run > ```bash > npm install imagemin-mozjpeg imagemin-optipng imagemin-svgo > ``` To install *all* optional packages, run: ```bash npm install imagemin-mozjpeg imagemin-optipng imagemin-gifsicle imagemin-svgo svg-sprite-loader webp-loader lqip-loader responsive-loader jimp image-trace-loader ``` :warning: Please note that by default, images are only optimized for **production builds, not development builds**. However, this can get changed with the [`optimizeImagesInDev` config](#optimizeimagesindev). :bulb: Depending on your build/deployment setup, it is also possibile to install these as devDependencies. Just make sure that the packages are available when you build your project. :information_source: Since version 2.5, `ico` files are also optionally supported but need to be enabled in the [`handleImages` config](#handleimages). ## Usage You can now import or require your images directly in your react components: ```javascript import React from 'react'; export default () => (

); /** * Results in: * *

*/ ``` Please be aware that images only get optimized [in production by default](#optimizeimagesindev) to reduce the build time in your development environment. If you are using CSS modules, this package also detects images and optimized them in `url()` values in your css/sass/less files: ```scss .Header { background-image: url('./images/my-image.jpg'); } /** * Results in: * * .Header { * background-image: url('/_next/static/images/my-image-5216de428a8e8bd01a4aa3673d2d1391.jpg'); * } */ ``` If the file is below the [limit for inlining images](#inlineimagelimit), 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/images/my-image-5216de428a8e8bd01a4aa3673d2d1391.jpg`). You can use both variants directly on an image in the `src` attribute or in your CSS file inside an `url()` value. ### Query params > *If you are using flow or eslint-plugin-import and are experiencing some issues with query params, check out the [solution posted by @eleith](https://github.com/cyrilwanner/next-optimized-images/issues/23).* There are some cases where you don't want to reference a file or get a base64 data-uri but you actually want to include the raw file directly into your HTML. Especially for SVGs because you can't style them with CSS if they are in an `src` attribute on an image. So there are additional options you can specify as query params when you import the images. * [`?include`](#include): Include the raw file directly (useful for SVG icons) * [`?webp`](#webp): Convert a JPEG/PNG image to WebP on the fly * [`?inline`](#inline): Force inlining an image (data-uri) * [`?url`](#url): Force an URL for a small image (instead of data-uri) * [`?original`](#original): Use the original image and do not optimize it * [`?lqip`](#lqip): Generate a low quality image placeholder * [`?lqip-colors`](#lqip-colors): Extract the dominant colors of an image * [`?trace`](#trace): Use traced outlines as loading placeholder * [`?resize`](#resize): Resize an image * [`?sprite`](#sprite): Use SVG sprites #### ?include The image will now directly be included in your HTML without a data-uri or a reference to your file. As described above, this is useful for SVGs so you can style them with CSS. ```javascript import React from 'react'; export default () => (

); /** * Results in: * *

* *

*/ ``` The image will still get optimized, even if it is directly included in your content (but by [default only in production](#optimizeimagesindev)). #### ?webp > Requires the optional optimization package `webp-loader` (`npm install webp-loader`) WebP is an even better and smaller image format but it is still not that common yet and developers often only receive jpeg/png images. If this `?webp` query parameter is specified, `next-optimized-images` automatically converts a JPEG/PNG image to the new WebP format. For browsers that don't yet support WebP, you can also provide a fallback using the `

パッケージ	ダウンロード数	Stars	サイズ	Issues	公開日時	ライセンス

next-optimized-images	12,978	2,240	-	134	5年前	MIT