Next.js Image Component Caching Problem with html-to-image Library

[SuperJakov]

Expected Behavior

When rendering multiple next/image components with different source URLs, each image should be uniquely processed and displayed, even when captured by HTML-to-image libraries.

Current Behavior

HTML-to-image libraries incorrectly cache Next.js optimized images based only on the base URL path (http://localhost:3000/_next/image), ignoring the query parameters that make each image unique (?url=...&w=640&q=75).

This results in all images appearing identical in the captured output, despite having different source URLs in the original React components.

Root Cause Analysis

Next.js Image component works by:

1. Taking the original image source
2. Creating an optimized version via an internal API route (/_next/image)
3. Passing parameters as query strings to specify dimensions, quality, etc.

HTML-to-image libraries typically:

1. Fetch and cache external resources
2. Use the resource URL as the cache key
3. Fail to consider query parameters when determining uniqueness

The conflict occurs because the library treats all Next.js image URLs as identical since they share the same base path (/_next/image), ignoring the distinguishing query parameters.

Possible Solutions

1. Use unoptimized images (trade-off solution):

   <Image src={url} alt="..." unoptimized />

   This bypasses Next.js optimization but ensures correct rendering in HTML-to-image.

2. Use native HTML img elements for captured content:

   <img src={url} alt="..." />

   Loses Next.js optimization benefits but works reliably with HTML-to-image.

Library Enhancement Request

The HTML-to-image library should be updated to:

1. Consider full URLs including query parameters when caching resources
2. Provide an option to disable caching for specific URL patterns

Reproduction Steps

1. Go to the minimal reproduction: https://stackblitz.com/edit/stackblitz-starters-p8qimg5n?file=app%2Fpage.tsx
2. Wait for Stackblitz to install dependencies and run the preview
3. Press Download as PNG then observe how multiple distinct images are rendered identically when captured

If it fails to download, just refresh the Stackblitz container, it's an issue with Stackblitz.

Technical Environment

• Next.js version: >13
• HTML-to-image library: 1.11.13
• Browser: All modern browsers
• Platform: Cross-platform issue

Related Documentation

• Next.js Image Component Documentation

This issue highlights a fundamental incompatibility between Next.js image optimization and resource caching strategies in HTML-to-image

[biiibooo]

👋 @SuperJakov

Thanks for opening your first issue here! If you're reporting a 🐞 bug, please make sure you include steps to reproduce it.
To help make it easier for us to investigate your issue, please follow the contributing guidelines.

We get a lot of issues on this repo, so please be patient and we will get back to you as soon as we can.