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 (https://github.com/vercel/next.js/issues/18356#issuecomment-718059371, https://github.com/vercel/next.js/discussions/19065#discussioncomment-127703, https://github.com/vercel/next.js/discussions/19065#discussioncomment-250617, https://github.com/vercel/next.js/discussions/19065#discussioncomment-479925, https://github.com/vercel/next.js/discussions/19065#discussioncomment-2708222)
Does the docs page already exist? Please link to it.
https://nextjs.org/docs/basic-features/image-optimization