Writing

Troubleshooting Client-Side HTML-to-Image Conversion in Safari and In-App Browsers

While developing a client-side thumbnail generator, exporting styled DOM nodes into high-resolution PNG images emerged as the core engineering bottleneck.

Under Chromium desktop browsers, standard libraries like html-to-image perform reliably. However, WebKit engines (desktop and iOS Safari) and mobile in-app webviews (KakaoTalk, Instagram, Line) introduce race conditions, asset stripping, and broken download behaviors.

Here is how we debugged and resolved these cross-browser export issues.

Problem 1: WebKit Resource Dropping in Safari

When using html-to-image, Safari frequently renders blank spaces where custom fonts or CSS background images should appear.

[DOM Element] ──(SVG ForeignObject)──> [Canvas rasterization]
                                             ▲
                     Safari prematurely terminates resource fetches

Safari isolates SVG foreignObject contexts aggressively. If external web fonts or base64 images take even a few milliseconds to resolve, WebKit aborts resource loading and rasterizes the canvas with missing text and blank backgrounds.

The Fix: Migrating to modern-screenshot

We switched to modern-screenshot, a maintained fork of html-to-image that includes pre-flight asset caching, font embedding workarounds, and better foreignObject lifecycle management.

import { domToPng } from 'modern-screenshot';

async function exportNodeToPng(element) {
  return await domToPng(element, {
    scale: 2, // Retina scale
    fetch: {
      busting: true,
    },
  });
}

The Safari Warm-Up Pass

On certain mobile Safari versions, WebKit's font rendering cache fails on the initial snapshot even when fonts are technically preloaded via document.fonts.ready.

Triggering a silent preliminary pass primes the internal WebKit glyph cache:

const isSafari = /^((?!chrome|android).)*safari/i.test(navigator.userAgent);

let dataUrl = "";
// Safari requires a warm-up cycle on cold DOM structures
const attempts = isSafari ? 2 : 1;

for (let i = 0; i < attempts; i++) {
  dataUrl = await domToPng(node, { scale: 2 });
}

Problem 2: Mobile Downloads (<a> download vs. Photo Library)

On desktop browsers, triggering an automatic download is straightforward:

const link = document.createElement('a');
link.download = 'thumbnail.png';
link.href = dataUrl;
link.click();

However, on iOS Safari and mobile in-app webviews:

  1. Synthetic clicks on <a download> open the blob as a generic document or prompt a save dialog into the iOS "Files" app rather than the Camera Roll / Photos app.
  2. Inside in-app browsers (like KakaoTalk or Instagram), download attributes are often completely suppressed by the native container webview.

The Solution: Long-Press Modal Fallback

Detect mobile WebKit and webview user agents. Instead of triggering an anchor download, present the rendered PNG inside an overlay modal with instructions to long-press and tap "Save to Photos":

async function handleDownload(node) {
  const dataUrl = await exportNodeToPng(node);

  const isIos = /iPad|iPhone|iPod/.test(navigator.userAgent);
  const isInAppWebview = /KAKAOTALK|Instagram|Line|FB/i.test(navigator.userAgent);

  if (isIos || isInAppWebview) {
    // Render the image into an overlay modal
    openPhotoSaveModal(dataUrl);
  } else {
    // Desktop / Android browser direct file download
    const link = document.createElement('a');
    link.download = 'thumbnail.png';
    link.href = dataUrl;
    link.click();
    link.remove();
  }
}

Takeaways

  • Treat client-side canvas rasterization as asynchronous and race-condition prone under WebKit.
  • Prefer modern-screenshot over unmaintained html-to-image forks.
  • Always provide fallback modal UIs for mobile browsers where native <a download> behavior is restricted.