Capture HTML to PNG in Next.js

1. Install

npm install @zumer/snapdom

The client pattern works in both the App Router and Pages Router. A server-controlled capture also needs Playwright or Puppeteer and browser infrastructure available to the deployment.

2. App Router: client component

Create a Client Component that owns the ref and the capture handler. The 'use client' directive is required because this component uses useRef and an onClick handler. Importing the module is not the failure boundary; invoking a capture without a browser DOM is.

// app/capture/CaptureCard.tsx
'use client';

import { useRef } from 'react';
import { snapdom } from '@zumer/snapdom';

export default function CaptureCard() {
  const cardRef = useRef<HTMLDivElement>(null);

  async function handleCapture() {
    if (!cardRef.current) return;
    const img = await snapdom.toPng(cardRef.current, { scale: 2 });
    document.body.appendChild(img);
  }

  return (
    <div>
      <div ref={cardRef} className="card">
        <h3>Hello SnapDOM</h3>
        <p>Captured from a Next.js client component.</p>
      </div>
      <button onClick={handleCapture}>Capture</button>
    </div>
  );
}

Try it live

This is what CaptureCard does after hydration, running on this page. The button fires snapdom.toPng(cardRef.current) and the captured PNG appears below, all client-side, exactly like it will in your Next.js app.

3. Use it from a server page

Server Components can render this Client Component as a child. Next.js may prerender its initial HTML, but the click handler and SnapDOM capture run only after hydration in the browser:

// app/capture/page.tsx
import CaptureCard from './CaptureCard';

export default function Page() {
  return (
    <main>
      <h1>SnapDOM in Next.js</h1>
      <CaptureCard />
    </main>
  );
}

4. Lazy-load SnapDOM on the first capture

If capture is an occasional action, dynamically import the library inside the Client Component handler. This creates a separate client chunk without wrapping the whole component in next/dynamic or disabling its prerendered HTML:

'use client'

import { useRef } from 'react'

export default function CaptureCard() {
  const cardRef = useRef<HTMLDivElement>(null)

  async function handleCapture() {
    if (!cardRef.current) return
    const { snapdom } = await import('@zumer/snapdom')
    const image = await snapdom.toPng(cardRef.current)
    document.body.appendChild(image)
  }

  return (
    <>
      <article ref={cardRef}>Rendered report</article>
      <button onClick={handleCapture}>Capture</button>
    </>
  )
}

Use next/dynamic({ ssr: false }) only when the entire child component must skip prerendering. Next.js requires that option to live in a Client Component.

5. Run a capture from a Server Action

A Server Action cannot call SnapDOM against raw HTML in its own Node process. It can be the coordinator: launch a browser, load the real page, inject the installed IIFE bundle, run SnapDOM in the page context and return a serializable result.

npm install playwright
npx playwright install chromium

// app/actions/capture-report.ts
'use server'

import { createRequire } from 'node:module'
import { chromium } from 'playwright'

const require = createRequire(import.meta.url)
const snapdomBundlePath = require.resolve('@zumer/snapdom')

export async function captureReport() {
  // Authenticate and authorize the caller here.
  // Apply app-specific rate and concurrency limits before launch.
  const browser = await chromium.launch()

  try {
    const context = await browser.newContext({ bypassCSP: true })
    const page = await context.newPage()
    await page.goto('https://app.example.com/report', { waitUntil: 'domcontentloaded' })
    await page.locator('#report[data-export-ready="true"]').waitFor()
    await page.evaluate(async () => { await document.fonts.ready })
    await page.addScriptTag({ path: snapdomBundlePath })

    return await page.locator('#report').evaluate(async (element) => {
      const pageWindow = window as typeof window & {
        snapdom: typeof import('@zumer/snapdom').snapdom
      }
      const image = await pageWindow.snapdom.toPng(element, { dpr: 1 })
      return image.src
    })
  } finally {
    await browser.close()
  }
}

Keep this path on the Node runtime. Set export const runtime = 'nodejs' and, when your host supports it, an adequate maxDuration on the page, layout or route that owns the action. The deployment must install Chromium during its build or connect to a browser service.

A fresh browser context has no user session. Authenticate explicitly with narrowly scoped credentials or a one-time signed URL. Validate or allowlist every target, never forward caller cookies to an untrusted URL, and enforce authorization plus rate and concurrency limits before launching the browser. For large images, store the bytes and return an asset URL instead of sending a long data URL through the action.

The DOM capture boundaries post has the complete installed-bundle recipe, readiness checks and Puppeteer equivalent. For a single direct bitmap with no SVG, plugins or reusable exports, page.screenshot() is usually simpler.

6. Dynamic OG / share images

SnapDOM is great for generating share cards on the fly when the user clicks "share". Capture the rendered card to a Blob, upload it to your CDN, and use that URL as the og:image for the share link:

async function share() {
  if (!cardRef.current) return;
  const blob = await snapdom.toBlob(cardRef.current, { scale: 2, type: 'png' });

  const form = new FormData();
  form.append('file', blob, 'share.png');

  await fetch('/api/upload', { method: 'POST', body: form });
}

For server-rendered OG images that do not need a real browser, Vercel's @vercel/og is a different tool. If the card must match a real page, the Server Action pattern above can capture it in a controlled browser.