Optimize images during next build

[elitan]

Edit: This post has been updated by @leerob to include the current solutions and related issues.

---

Overview

next/image does not currently perform image optimization during next build, and instead optimizes images on-demand. This was done to prevent long build times when optimizing many images. Build time optimization is one of the top requests from the community and is something we're exploring solutions for. In the meantime, here are the current solutions.

Current Solutions

Static Exports

Image Optimization through next/image can still be used with a static export by defining a custom image loader in next.config.js. For example, you can optimize images with a service like Cloudinary:

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  images: {
    loader: 'custom',
    loaderFile: './app/image.ts',
  }
};

module.exports = nextConfig;

This custom loader will define how to fetch images from a remote source. For example, the following loader will construct the URL for Cloudinary:

export default function cloudinaryLoader({
  src,
  width,
  quality,
}: {
  src: string;
  width: number;
  quality?: number;
}) {
  const params = ['f_auto', 'c_limit', `w_${width}`, `q_${quality || 'auto'}`];
  return `https://res.cloudinary.com/demo/image/upload/${params.join(
    ','
  )}${src}`;
}

You can then use next/image in your application, defining relative paths to the image in Cloudinary:

import Image from 'next/image';

export default function Page() {
  return <Image alt="turtles" src="/turtles.jpg" width={300} height={300} />;
}

Disabling Optimization

If you want to use next/image (for maintaining aspect ratio, etc) but don't want any image optimization, you can opt-out as of 12.3:

module.exports = {
  images: {
    unoptimized: true,
  },
}

Checking optimized images into git

You optimize your images are part of a separate pipeline and check those files into git for consumption in your public folder. This is a good solution if you are worried about build times, as they compute and run on your local machine pre-commit. This ensures there's no build time overhead.

Related Issues

#18356

[AlexThomas90210]

I actually expected this functionality when I tried out next/image. Then when it didn't work I couldn't find anything about it in the docs. Would be really great if next/image worked with export

[elitan]

Why was this issue moved to discussion?

What's the difference between "Feature request" label under issues and the "Ideas" label under discussion?

[timneutkens]

Feature requests are generally always converted to discussions "ideas" section, we'd have people create them directly in the ideas section but discussions does not have templates support yet unfortunately so we're using this as a workaround.

Added a note here: 14aa838

[elitan]

Ok, understood. 👍

[leerob]

@elitan FYI, I updated the original discussion with more information (and made sure to call out I edited your post 😄 )

[sasivarnan]

Any plans of supporting this feature in near future?

• As many users pointed out everyone won't have billions of images that will slow down the build process.
• People who using Next.js for building small apps and content sites like blog or documentation sites that are updated less often, will really get benefitted.
• Not having support for this feature stops people who want to migrate from Gatsby.
• It would be helpful to make offline usable PWA apps.

cc: @leerob @timneutkens

[timneutkens]

So far there's only 7 👍's on this feature request

[sasivarnan]

There were many people looking for this feature in the issue that @elitan mentioned. 👀

#18356 (comment)

[elitan]

@timneutkens There's now 141 👍 's (second most upvoted feature right now). Any update on your position of supporting this feature in the near future?

[connormcwood]

@timneutkens There is now 345 👍 , 137 ⬆️ , and 15 😆

[tobiasBora]

@timneutkens this continues

[ccssmnn]

Next is claiming that it supports static side generation. It is also proud of providing image optimization. Now I had to learn the hard way after converting my code from Gatsby to Next, that we cannot have both even though it is part of the core library. That is a real bummer.

@timneutkens I have found this idea here only after I started writing a feature request and started looking for a similar request at this place (didn't find one on the issues). So please don't take the 👍 too serious.

Also, maintainers are closing related issues because this functionality is intended, which makes them and this discussion thread harder to find and reduces the interactions with these.

There are several issues pointing to this missing feature:

#18356
#18507
#19104
#18547

... just to name a few I was able to find without investing too much time.

Generating these images during export should be provided by Next. Resizing images using NodeJS is already implemented (used by next start) and we only need to generate resolution sensitive image tags in the static HTML plus the image files.

Since this is OSS: Can I help somehow?

[eloquentmack]

Yup, it's a problem, especially when it's not being handled at all. Not only it does not optimize images, but actually brakes the generated static site.

I'm really surprised there's still no huge red warning in the docs (1, 2) that using Image breaks next export. I'm not even sure if there's any mention of it at all.

Did anybody try using Netlify with next-on-netlify or Vercel? I'm assuming it should work, since they both have compatibility layers that make Next use lambdas, but I didn't get a chance to test them and to work out how much lambda usage it takes to serve cached images.

[m-sterspace]

The docs seem to forget (or predate) the fact that next.js is a static site generator:

Instead of optimizing images at build time, Next.js optimizes images on-demand, as users request them. Unlike static site generators and static-only solutions, your build times aren't increased, whether shipping 10 images or 10 million images.

This was the only thing that tipped me off that using this component might not work. I just assumed it would work like Gatsby and do it during Next Export.

[VWSCoronaDashboard]

We've got a naive but workable workaround in https://github.com/minvws/nl-covid19-data-dashboard/pull/1434/files#diff-f9318ad2bcfcfdc021518b7d9f7c102c4b32461be1c838a624595d100c6ef5c5

This would be easier if this was built-in, for sure.

[jlarmstrongiv]

That’s great! There was one particularly hacky workaround I’ve thought about.

Back in next@10.0.0, running the export command with an Image component wouldn’t cause the build process to fail. Rather, 404 runtime errors would appear in the browser. The build would still output components like this:

<img
  data-src="/_next/image?url=%2Fgiant-rubber-duck.jpg&amp;w=1200&amp;q=75"
  data-srcset="/_next/image?url=%2Fgiant-rubber-duck.jpg&amp;w=320&amp;q=75 320w, /_next/image?url=%2Fgiant-rubber-duck.jpg&amp;w=420&amp;q=75 420w, /_next/image?url=%2Fgiant-rubber-duck.jpg&amp;w=768&amp;q=75 768w, /_next/image?url=%2Fgiant-rubber-duck.jpg&amp;w=1024&amp;q=75 1024w, /_next/image?url=%2Fgiant-rubber-duck.jpg&amp;w=1200&amp;q=75 1200w"
  class="__lazy"
  style="
    visibility: hidden;
    height: 100%;
    left: 0;
    position: absolute;
    top: 0;
    width: 100%;
  "
/>

I always thought that if I were desperate enough, I could write a script to scrape those urls, generate images from the next start server, save them to the out folder, and rewrite the urls. Fortunately or not, this workaround is patched now that the build process errors. I’d be curious if anyone has other workarounds 😄 no matter how hacky

[jlarmstrongiv]

Has anyone tried making a custom loader using https://nextjs.org/docs/api-reference/next/image#loader? It may even be possible to generate images serverside.

import Image from 'next/image'

const myLoader = ({ src, width, quality }) => {
  return `https://example.com/${src}?w=${width}&q=${quality || 75}`
}

const MyImage = (props) => {
  return (
    <Image
      loader={myLoader}
      src="/me.png"
      alt="Picture of the author"
      width={500}
      height={500}
    />
  )
}

[drothmaler]

Same here... for us the whole point of choosing Next.js was the ability to next export a static site, to be served at any classical webserver (without the need of Node). The fact that export capabilities seem to be somewhat abandoned is very disappointing to me.

[MurphyAdam]

The issues is still open and no possible fixes yet. I only used Next.js for it's image optimization, but had to learn myself that it won't work on export

[leerob]

@MurphyAdam Please see the latest comment for current solutions.

[cortopy]

On the one hand, next.js docs say:

We recommend using Static Generation over Server-side Rendering for performance reasons. Statically generated pages can be cached by CDN with no extra configuration to boost performance. However, in some cases, Server-side Rendering might be the only option.

And then, on the other,

Images are optimized dynamically upon request and stored in the /cache/images directory.

It seems to me it only works this way because Vercel offers a premium image optimisation service. If next.js optimised images at build time, then they fear losing customers.

This is mind boggling. I've been thinking for a few days whether to go with next.js or gatsby for a new project. This settles it.

[leerob]

We recommend using Static Generation over Server-side Rendering for performance reasons. Statically generated pages can be cached by CDN with no extra configuration to boost performance. However, in some cases, Server-side Rendering might be the only option.

This statement is not referring to image optimization.

It seems to me it only works this way because Vercel offers a premium image optimisation service. If next.js optimised images at build time, then they fear losing customers.

Image optimization is not tied to Vercel. It works out of the box using next start. Many users of image optimization host their own server and use it outside of Vercel. Also, Vercel does have a free tier where image optimization is included.

---

We are tracking this discussion and hear you all!

[hippotastic]

Based on the number of upvotes and thumbs up on this idea, this is the 2nd most requested feature on Next.js right now. Come on, please give us some sort of announcement that this feature is coming and when we can expect it.

I was ready to switch from Gatsby to Next.js, and was completely baffled that the seemingly simple requirement to have next export generate a static set of optimized images (and keep it up to date in case the source images change) is not supported, not even with a config flag.

I don't want to completely change my hosting provider and webserver configuration just for an on-demand image optimization feature that I don't need, and I don't like the security implications of having a Node.js app run permanently on a public server. What if a security flaw is discovered in some Node.js networking functionality? To me, one of the huge benefits of having an entirely static site is not having to worry about security updates anymore. Requiring a permanently running Node.js app for an essential web feature like images completely defeats this benefit.

[IvaKop]

I recently bumped into this issue as well and was surprised to find out that next/image does not work with next export. I found a workaround using next-optimized-images instead. Here is a short article about it, it may be useful for those still searching for a solution: https://blog.whereisthemouse.com/image-optimization-for-static-nextjs-sites

Despite there being a workaround, it would be great to have the ability to optimize images during build out of the box and without having to jump through additional hoops.

Also, highlighting the limitations of next\image clearly in the docs could help prevent unpleasant surprises.

[m-sterspace]

It really feels there should be a giant red "Next Image does not support static site generation" on the static site generation page. Image optimization is a pretty critical part of literally every single web site I've ever worked on, it's a pretty glaring hole for virtually any developer who's trying to decide between Next and Gatsby.

[leerob]

@m-sterspace Please see the latest comment for current solutions.

[leerob]

Edit: I've updated the main discussion with the latest updates 🚀

[krystof-k]

I'm using next-compose-plugins. You have to use canary version of next-optimized-images.

next.config.js:

const withOptimizedImages = require('next-optimized-images');

module.exports = withPlugins([[withOptimizedImages]], {
  webpack(config) {
    …
    return config;
  },
});

Any component:

import OptimizedImage from 'react-optimized-image';

…

return (
  <StyledImage
    src={require(`images/${image}.png`)}
    loading={lazy ? 'lazy' : null}
    sizes={[400, 600, 800, 1023, 800, 1023]}
    breakpoints={[400, 600, 800, 1023, 1535, 2400]}
    densities={[1, 2]}
    webp
    alt={alt}
    width={width}
    height={height}
  />
);

[jrub]

Thanks @krystof-k! So, there is no way of just adding the config and get it working without modifying the current components (I'm using a react template), right?. Would sth like https://github.com/twopluszero/next-images work "out-of-the-box"?

[krystof-k]

Well, I guess the require may work even without the component, but you'll lose the responsivity, which makes no sense to me.

[leerob]

Update: https://twitter.com/rauchg/status/1402613436081528836

I've updated the main discussion with the latest updates!

[viglucci]

@leerob with the latest update about 9 months ago, is there anything more recent that can be shared?

Unfortunately I can be added to the list of people that didn't realize this was going to be a problem.

[timmysmalls]

I've only recently switched to using Next/Image, but I bumped into this rather quickly. It's not just next export, it would be nice to be able to generate optimized images during build time in general, so that users don't have to wait 2-3 seconds for important images to load the first time they visit the site. Similar to how we can statically generate pages during build time, optimizing images seems like a reasonable next step. Some people rely quite heavily on static generation, with frequent rebuilds, and the images need to be recreated after every build, so they experience this initial delay quite regularly. The easy way to deal with this is to just open the important pages once after each rebuild and scroll through them, and screw around with your browser width so that all the important images get generated at different sizes, but there has to be a more elegant way.

[peec]

I would love this future, currently i am stuck as I need all images to be bundled into the build.

Reason why i would need this feature for this current project:
I am working with an Next.js application which is going to run on a Ship (on a server on the Ship), it has limited internet connection and the internet connection far into the sea is really slow and a huge resource hog would happen if users was to reach a CDN every time we present an image. An option to build images into the build on npm run build e.g. configured in next.config.js or just an option on the Image Component it self, would be really awesome.

Do anyone know of any workarounds?

[dc7290]

We have built a solution to optimize images at build time and released it under the MIT license!
For a detailed explanation, please visit the documentation site, but here is a brief introduction as well.
Document Site

Using this repository, you can get the full benefits of next/image even when using next export by doing image optimization at build time.

This makes it possible to build a high performance website with this solution, whether you want to build a simple website or a completely static output.

As a special note,

• Optimize images at build time.
• All options for next/image available
• Using sharp, so it's fast.
• Cache prevents repeating the same optimization
• Support TypeScript

This solution was inspired by @jkjustjoshing's suggestion.
Thank you so much!

[jkjustjoshing]

Nice work!

One not-trivial missing piece that I’ve since noticed from my suggestion above is this doesn’t use AVIF/WEBP formats.

Next Image works this way: when the browser requests a PNG image, it includes in the Accepts header a list of image mime types that it accepts. The next/image server looks at that header, and if the browser accepts a modern image format it returns an AVIF/WEBP image instead, at the PNG’s URL.

With a static site, we can’t do that, so this method misses this significant optimization opportunity. An ideal solution would modify the next/image component to also add additional <source> elements to next/image’s rendered <picture> element, causing this post-build optimization script to create multiple formats and sizes of the input images, not just multiple sizes.

[dc7290]

Thanks for getting back to me!

You are right about webp and avif 😭
next/image does not support the picture tag and only accepts a single extension on static sites.
I'm not sure if this is a spec that affects the priority props, but I hope it will be adopted as an opt-in.

Also, we are not currently considering re-implementing next/image with a picture element.
This is because it is a painstaking task to keep up with the latest updates and we believe that we need to prevent bugs from occurring due to this.

[druvisc]

sharp.js script I use to resize images for my static sites: https://github.com/druvisc/terezemedne/blob/main/scripts/sharp.js. Creates responsive images for the used file-format (hardcoded png and jpeg) and webp.

Image.ts component using picture element: https://github.com/druvisc/terezemedne/blob/main/components/Image.tsx (contains a few Tailwind classes). Responsive, lazy-loaded, animated and w/o layout shift (invisible placeholder). Supports a pseudo 'full-height' prop (containHeight).

More info in README.md, site available here: https://www.terezemedne.com/

[abaco]

We've just released sidepix, a picture (as in <picture>, not <img>) React component that does image processing in the background, as a side effect of rendering on the backend. It uses sharp and supports different image formats and cropping around a focal point. It's framework agnostic but was developed for a Next.js project. There's an example in the repo that does next export.

At Neugelb we've been using a version of sidepix in production, but the open source version is rather different, arguably improved but also less tested. We'll be adding documentation and minor features in the next weeks. Of course, any feedback is welcome!

[abaco]

Since I guess most people here want to use next/image, I've added an example that triggers image optimization from a custom loader. The nice thing is that it also works with next dev.

[vgorloff]

Ended up by writing JS script (gulp task) which searches for project images (using globby), then resizes them using imagemagick and builds JSON with srcSet and src.

module.exports = {
  "Products": {
    "decode": {
      "images": {
        "main01Open": {
          "srcSet": "/generated/pages/products/decode/images/main-01-open-e9e51a84-300.png 300w,/generated/pages/products/decode/images/main-01-open-e9e51a84-320.png 320w,/generated/pages/products/decode/images/main-01-open-e9e51a84-640.png 640w,/generated/pages/products/decode/images/main-01-open-e9e51a84-960.png 960w,/generated/pages/products/decode/images/main-01-open-e9e51a84-1200.png 1200w",
          "src": "/generated/pages/products/decode/images/main-01-open-e9e51a84-640.png"
        },
        ....
      }
    }
  }
}

Usage:

<img
  src={Assets.Products.decode.images.main01Open.src}
  srcSet={Assets.Products.decode.images.main01Open.srcSet}
  alt="Opening Xib or Storyboard."
 />

[Noibisjunior]

I actually finds this thread helpful.A big thanks to the Next.js Team

[leerob]

I've updated the main message with more details - also:

1. We hear you this is something a lot of people are interested in – upvoting the issue is the best way for us to track that
2. There are solutions in the main message that allows you to skip optimization or use other providers
3. You do not need to use Vercel for optimizing images. It works using next start or any loader of your choice.

Please keep the conversation on topic, upvoting current solutions or options for build-time image optimization. Thank you!

[benedictjohannes]

Looking at the props for next/image, I'd say the next/image component currently has all the information that is required to perform optimization at export time from its props.

As such next export can find the linked image (local) or download it (remote) and either:

1. Execute the image "loader function" and download the returned URL
2. Execute Next.js built-in Image Optimization API

Afterwards, both the original (and optimized) images would be cached and also exported in the out folder (file name should be prefixed/suffixed with checksum for file matching strategy).

I'm planning to port a client website to Next.js from Gatsby, and the lack of static image optimization is holding me off (SSR/DSG is out of question for this project). I prefer not to use external libraries for image optimization. I'm not familiar with Next.js internals, but I imagine this isn't very hard to achieve.

Has anyone work with this? I'd like to contribute if no one is working on this (yet).

[mkrn]

It seems that the loaderFile is just being added to webpack, unfortunately, it's only executed while building as far as rendering code (browser based) to pre-render built pages. I could get console.log the file urls, but no way to use 'sharp', 'fs' or anything like that to download, resize add them to /dist during build time..

I believe this is a serious shortcoming of next.js, and something Gatsby and others support out of the box. It shouldn't be too hard to implement additional loader function or a step in build to achieve that.

[benedictjohannes]

I think long build time would NOT be a problem with static image optimization for all occurrences of next/image, because:

1. Image optimization should NOT happen at next build
2. Image processing only occur on next export (or even behind a flag such as --process-images). Large projects with potentially thousands/millions of images should not be running next export in the first place, right?

[stx-chris]

Dear team! As indicated above, this is - so far - the top-voted discussion item and, from a practical point of view, our current obstacle as well. It is always tough to tell our customers why their images are loaded so slowly from our CMS, although they are known and accessible at build time. Runtime optimization is important, but seeing something right away is even more important.

A flag to generate cached (and optimized) images would indeed come in handy on the final build. There is no need to include this routine in every single build. For what it's worth, this logic could alternatively be applied when starting the app on the deployed server. During build a list of image urls can be generated which could then be pre-fetched on boot.

Any thoughts/updates on this?

[Niels-IO]

Have you seen the package next-image-export-optimizer, I created as a feasible workaround. You can find all details in this npm package: https://www.npmjs.com/package/next-image-export-optimizer

[stx-chris]

@Niels-IO Wow, sounds great! Will give it a try, thanks.

[webdev4422]

Big appreciation to Next.js team for doing great work!

Still there is a lot of possibilities to enhance further. Static image export is one of them.
Posting my experience about SSG images in Next.js.

Purpose: fully static, provider agnostic, secure and solid SSG website.

First trying recommendations from here #36431 (comment)
Was not able to serve static images with appropriate srcset attributes.

Then this: https://www.npmjs.com/package/next-image-export-optimizer
Very good solution but still got some issues: Niels-IO/next-image-export-optimizer#191

Then trying each option from here: https://stackoverflow.com/questions/70500084/how-to-export-static-images-on-nextjs
Tested 3 modules, each was not able to produce results that I expect.

Then thoroughly reading this: https://nextjs.org/docs/app/api-reference/components/image
Also general sources here:
https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images
https://web.dev/learn/design/responsive-images
https://www.youtube.com/watch?v=DtV_2zXtuiU

After all this steps I still don't have a clue how to properly (automatically) make static images that can output this html:

<img
        alt="Main hero image that optimized for LCP on first load"
        width="640"
        height="480"
        fetchPriority="high"
        loading="eager"
        decoding="async"
        sizes="100vw"
        srcSet="
          /images/optimized/main-opt-480.WEBP 480w,
          /images/optimized/main-opt-640.WEBP 640w,
          /images/optimized/main-opt-750.WEBP 750w,
          /images/optimized/main-opt-828.WEBP 828w,
          /images/optimized/main-opt-1080.WEBP 1080w,
          /images/optimized/main-opt-1200.WEBP 1200w
        "
        src="/images/main.jpg"
      />

At least it's possible to manually write this for each image.

[dc7290]

While Next.js does not officially support image optimisation at build time, a workaround is possible by using the following library.
https://github.com/dc7290/next-export-optimize-images

The library supports basic use cases, as well as functionality similar to Next.js getImageProps and components using the Picture element.
Please try it out.