Docs: Make it clear that next/image is not compatible with SSG (next export) and improve the related docs

[adamerose]

What is the improvement or update you wish to see?

There is no mention in the NextJS image documentation that next/image does not work with next export.

It should be mentioned on these pages:
https://nextjs.org/docs/basic-features/image-optimization (main next/image docs)
https://nextjs.org/docs/messages/no-img-element (error page you're directed to when not using next/image)

This issue is just about improving the docs, but also there really should be improvements to the default config so that users can use images on their SSG site without having to follow docs to apply workarounds

Is there any context that might help us understand?

This has been my experience as a new NextJS user this week:

• Start my project with create-next-app and design all my pages (with images)
• See many @next/next/no-img-element ESLint warnings telling me to use next/image
• Refactor my project to use next/image (including fixing some broken CSS since it's actually an img inside a div not a direct image replacement)
• Try building and get the following message

Error: Image Optimization using Next.js' default loader is not compatible with `next export`.
  Possible solutions:
    - Use `next start` to run a server, which includes the Image Optimization API.
    - Use any provider which supports Image Optimization (like Vercel).
    - Configure a third-party loader in `next.config.js`.
    - Use the `loader` prop for `next/image`.
  Read more: https://nextjs.org/docs/messages/export-image-api

• The first two 'solutions' are just saying don't use SSG which is not really a solution, and the last 2 don't link to any examples or documentation on what to do, so I ended up having to browse google and read through a bunch of GitHub issues (1, 2, 3, 4)
• Tried using a custom loader as described here which again required refactoring all my Image components. This fixed my build errors but doesn't actually fix image optimization it just disables it.
• Try using next-optimized-images, which once again required refactoring all my images back into img components... only to find this doesn't work either - on build I get a bunch of errors from the various image packages like this and I didn't want to spend more time debugging dependencies of a dependency that is already an unoffocial workaround.
• Try instead using next-image-export-optimizer which once again requires refactoring every image component in my project. At this point I'm desperate and have read literally hundreds of GitHub comments, this is the last remaining solution I was able to find and is a repo with only 47 stars. It manages to build without errors but I find the result is a bunch of dead image links on my page.
• After many hours wasted I finally go back to the original workaround to disable image optimization completely.

I decided to use NextJS over CRA even though I don't need SSR because I saw people touting it as having a better DX and sane defaults, but that doesn't feel true at all for SSG so far

There are many highly upvoted comments requesting similar improvement to the documentation and saying it's misleading to market NextJS as an SSG in its current state (#18356 (comment), #19065 (comment), #19065 (comment), #19065 (comment), #19065 (comment))

Does the docs page already exist? Please link to it.

https://nextjs.org/docs/basic-features/image-optimization

_DX-1662

[PatrikTheDev]

That isn't necessarily true, next start still allows you to use SSG pages, but you also get a server runtime for API routes and in this case, Image Optimization.

I think it would be possible to create every variation of the optimized image at build-time. This solution wouldn't support dynamic domains or URLs, just static imports (which isn't always the case and likely why the team decided not to implement it this way)

[kaf-lamed-beyt]

@adamerose

There's an article here that shows how you can go about setting a custom loader and other alternatives too

[adamerose]

@adamerose

There's an article here that shows how you can go about setting a custom loader and other alternatives too

I don't want to put all my website's images put on a third party cloud provider, I need control of hosting and would like to just export a complete static website to host myself. This is especially true for anyone working on internal webapps which may include sensitive data.

Aside from cloud hosting, this article gives the same solution I mentioned in my OP - fiddle with config or custom loaders in order to opt out of image optimization so SSG will actually work. My request with this issue is that this requirement is made clear in the NextJS documentation not just external blogs and GitHub discussions.

I think it would be possible to create every variation of the optimized image at build-time.

Yes there is discussion of this and other possible ways to fix image optimization for SSG, but in the mean time my hope with this issue is to update the current documentation so that people understand this is currently not possible and can know what is needed to fix next export without digging through GitHub issues and blogs.

My understanding is users need to do at least one of these things before they can run next export without errors

1. Use img instead of next/image, and modify their .eslint.json to suppress the NextJS rule against using img
2. Add a custom dummy () =>{} loader to all their Image tags
3. Change their next.config.js to disable image optimization
4. Use some third party package like next-optimized-images (which will not work without also doing step 3, see here)

This is pretty simple when listed out, but as a new user took me many hours reading blogs and issues to understand what my options were, when all I wanted to do was export and serve a static HTML website. Many of those solutions also require refactoring code which wouldn't have been needed if I understood this ahead of time

[kaf-lamed-beyt]

Aside from cloud hosting, this article gives the same solution I mentioned in my OP - fiddle with config or custom loaders in order to opt out of image optimization so SSG will actually work. My request with this issue is that this requirement is made clear in the NextJS documentation not just external blogs and GitHub discussions.

Oh oh! That's fine then 😎

[richarddzk]

Any update about this issue with the 13 release ?

[Jaydeep189]

I was having similar issues, so I just disabled the image optimization in the next configuration file.
I only later realized that it doesn't support SSG, which was very important for my project's performance.
The images are unoptimized, hence its loading speed has increased.
And I can't change the whole project's images as there are so many images in my project.

[MertHaddad]

@adamerose
There's an article here that shows how you can go about setting a custom loader and other alternatives too

I don't want to put all my website's images put on a third party cloud provider, I need control of hosting and would like to just export a complete static website to host myself. This is especially true for anyone working on internal webapps which may include sensitive data.

Aside from cloud hosting, this article gives the same solution I mentioned in my OP - fiddle with config or custom loaders in order to opt out of image optimization so SSG will actually work. My request with this issue is that this requirement is made clear in the NextJS documentation not just external blogs and GitHub discussions.

I think it would be possible to create every variation of the optimized image at build-time.

Yes there is discussion of this and other possible ways to fix image optimization for SSG, but in the mean time my hope with this issue is to update the current documentation so that people understand this is currently not possible and can know what is needed to fix next export without digging through GitHub issues and blogs.

My understanding is users need to do at least one of these things before they can run next export without errors

1. Use img instead of next/image, and modify their .eslint.json to suppress the NextJS rule against using img
2. Add a custom dummy () =>{} loader to all their Image tags
3. Change their next.config.js to disable image optimization
4. Use some third party package like next-optimized-images (which will not work without also doing step 3, see here)

This is pretty simple when listed out, but as a new user took me many hours reading blogs and issues to understand what my options were, when all I wanted to do was export and serve a static HTML website. Many of those solutions also require refactoring code which wouldn't have been needed if I understood this ahead of time

100% agree with you!

[leerob]

It is possible to use next/image with a static export. We have added better documentation to outline this:

---

Image Optimization through next/image can 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} />
}

---

Source: https://nextjs.org/docs/app/building-your-application/deploying/static-exports#image-optimization

[leerob]

To discuss optimizing images during static export builds, please see this feature request: #19065