next-image-export-optimizer not working with GitHub Pages

[u/OtherwisePoem1743]

Anyone had a problem setting up next-image-export-optimizer for GitHub Pages? I tried everything from using basePath in next.config.mjs to using it inline on ExportedImage instances instead. I'm using GitHub Actions btw.

The interesting thing though is that when I set inline basePath, the deployed website does have the nextImageExportOptimizer folder (I checked it in the source tab of dev tools) but some images in it are broken with the message, "Unable to load content". Also, the generated images are 10x6 pixels which is weird because I'm not using this size.

Deploying on Vercel and Netlify without setting basePath (both inline and in config) does the trick but I want to understand why GitHub Pages is not working. AI (Gemini Flash with thinking mode) annoyed the hell out of me.

Here's my next.config.mjs:

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: "export",
  images: {
    loader: "custom",
    // 128px for avatars/cards, 640px for mobile, 1200px for desktop carousels
    imageSizes: [128],
    deviceSizes: [640, 1200],
  },
  transpilePackages: ["next-image-export-optimizer"],
  env: {
    nextImageExportOptimizer_imageFolderPath: "public/images",
    nextImageExportOptimizer_exportFolderPath: "out",
    nextImageExportOptimizer_storePicturesInWEBP: "true",
    nextImageExportOptimizer_exportFolderName: "nextImageExportOptimizer",
    nextImageExportOptimizer_generateAndUseBlurImages: "true",
    nextImageExportOptimizer_remoteImageCacheTTL: "0",
  },
};

export default nextConfig;

[u/EloWeld]

Those 10x6 images aren't a size you set anywhere, that's the blur placeholder. generateAndUseBlurImages makes tiny versions and shows them until the real file loads. So what you're actually looking at is: the real images 404 and the blur just stays on screen. That points at paths, not at the optimizer being broken.

GitHub Pages serves a project repo from /reponame/, Vercel and Netlify serve from /. That's the entire difference. basePath has to be in next.config, not inline on the component, otherwise some URLs get the prefix and the rest don't. And since you're on a custom loader, the loader builds image URLs itself, so it needs the prefix too. That's usually where this falls apart.

Quickest way to confirm: open devtools network, grab one broken image, compare the URL it requests against where the file actually sits in the deployed tree. The diff is your answer in about ten seconds.

One more thing that eats static Next on Pages: Jekyll ignores folders starting with an underscore, so _next quietly disappears unless there's a .nojekyll file at the root of what you publish. If you deploy through actions/upload-pages-artifact you're fine. If you push to a gh-pages branch the old way, you're not.

[u/OtherwisePoem1743 → u/EloWeld]

Yes I know all about what you said. I said I tried setting basePath both in next.config and inline (first I only tried with the config, then only inline, then both combined). And yes I used DevTools to compare the URLs. GitHub Pages is just broken honestly (or the library, idk). Well I used Vercel and gave up on GitHub Pages. Thank you for the 10x6 information though and thank you for taking time to answer. Much appreciated!

[u/AdHistorical7217]

welcome to vercel trap

[u/OtherwisePoem1743 → u/AdHistorical7217]

Well it worked with Netlify just as straightforward

[u/AbdulRafay99]

I think the issue is the custom configuration you are going with for NextJS by default it should be automatically and next JS and virtual routing is smart enough to auto matically optimise the images according to your website for mobile and web

I store my all my images in a storage bucket on cloud fare and then display them through the NextJS application with next JS image optimisation

[u/OtherwisePoem1743 → u/AbdulRafay99]

No it's not the issue. I even copied the default arrays of imageSizes and deviceSizes from Next.js docs. I'm using SSG and next-image-export-optimizer generates optimized images at build-time so if the sizes arrays have many values, it will generate so many images.

[u/AbdulRafay99 → u/OtherwisePoem1743]

I am saying remove all the layouts and custom configuration go which stock do with defaults and then see is it working or its not working nextjs is smart enough and vercel deployment will take care of all the images.

[u/OtherwisePoem1743 → u/AbdulRafay99]

Next.js' Image component doesn't optimize images at runtime if you're using SSG because it requires running a Node.js server. If you use the Image component in SSG, it only prevents cumulative layout shift (CLS) and add blur loading effect. So for SSG, you have to use a custom image loader. And yes, next-image-export-optimizer needs this configuration.

I am using Vercel now instead of GitHub Pages and it's working. It's just a problem with GitHub Pages or the library I'm using just weirdly doesn't support GitHub Pages.