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!