DEV Community: SnapshotFlow

Using a Node.js Screenshot API to Capture Screenshots, PDFs, and Visual Diffs

SnapshotFlow — Sun, 05 Jul 2026 19:50:09 +0000

If you have ever shipped a feature that takes screenshots from Node.js, you already know the trap.

The first version looks simple:

await page.goto(url);
await page.screenshot({ path: "page.png", fullPage: true });

Then production arrives.

You need Chromium installed in the right environment. Fonts differ between machines. Pages hang forever. Cookie banners cover half the viewport. Some captures need mobile emulation. Some need PDFs. Some need to run in batches. Eventually, your "take a screenshot" helper turns into browser infrastructure.

That is the point where a hosted screenshot API becomes useful.

This post walks through capturing screenshots from Node.js with the official SnapshotFlow TypeScript SDK. The goal is not to hide the API behind magic. It is to keep your app code focused on the job: request a render, get back an image, PDF, JSON payload, batch result, or visual diff.

Install the SDK

SnapshotFlow ships an official npm package:

npm install snapshotflow

It requires Node.js 18 or later.

Create an API key in the SnapshotFlow dashboard, then store it in your environment:

export SNAPSHOTFLOW_API_KEY="your_api_key"

The SDK is a typed wrapper around the HTTP API. Rendering still happens on the backend, so your Node process does not need Puppeteer, Playwright, a Chromium binary, or a browser pool.

For the full reference, see the Node.js screenshot API guide.

Capture a basic screenshot

Start with the smallest useful example:

import { SnapshotFlow } from "snapshotflow";

const client = new SnapshotFlow({
  apiKey: process.env.SNAPSHOTFLOW_API_KEY!,
});

const shot = await client.take({
  url: "https://example.com",
  fullPage: true,
  width: 1440,
});

await shot.save("example.png");

The take() method returns a binary ScreenshotResult. That result includes:

buffer
contentType
cached
etag
save(path)
toBase64()
blob()

So if you need to upload the image to S3, return it from an API route, or store it in a job artifact directory, you do not need to re-fetch anything.

Use TypeScript-friendly options

The HTTP API uses snake_case query parameters. The SDK lets you use camelCase options in Node.js:

const shot = await client.take({
  url: "https://github.com",
  width: 1440,
  height: 900,
  deviceScaleFactor: 2,
  fullPage: true,
  blockAds: true,
  blockCookieBanners: true,
  waitUntil: "networkidle2",
  delay: 1000,
});

await shot.save("github.png");

That gives you a high-resolution full-page capture, waits for the page to settle, and blocks common distractions before the screenshot is taken.

This is where using an API starts to feel different from owning the browser stack. Your code describes the capture. The service handles the rendering environment.

Dynamic OG Images for Next.js & Vercel (3 Production Patterns)

SnapshotFlow — Tue, 23 Jun 2026 19:00:38 +0000

Open Graph images are the first thing most people see when a link to your app gets shared - on Slack, Twitter, LinkedIn, iMessage, anywhere a URL gets unfurled into a preview card. A static OG image works fine for a marketing homepage. It falls apart for anything dynamic: blog posts, product pages, user profiles, dashboards, or any route where the content changes per-request. For those, you need OG images generated programmatically, per route, and that generation needs to be fast enough not to introduce noticeable latency.

There are three common production patterns for this in the Next.js and Vercel ecosystem, and they have meaningfully different trade-offs. This post walks through all three.

Pattern 1: Edge Runtime Generation with @vercel/og

The most common approach for new Next.js projects is generating OG images directly at the edge using @vercel/og, which wraps Satori - a library that converts JSX and CSS into SVG, then rasterizes to PNG.

// app/api/og/route.tsx
import { ImageResponse } from 'next/og';

export const runtime = 'edge';

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);
  const title = searchParams.get('title') ?? 'Default Title';

  return new ImageResponse(
    (
      <div
        style={{
          display: 'flex',
          height: '100%',
          width: '100%',
          alignItems: 'center',
          justifyContent: 'center',
          background: '#0f172a',
          color: '#ffffff',
          fontSize: 64,
        }}
      >
        {title}
      </div>
    ),
    { width: 1200, height: 630 }
  );
}

The advantage here is speed and integration. It runs at the edge, has no cold start in the traditional serverless sense, and stays entirely within your Next.js deployment - no external service, no additional API keys.

The limitation is the rendering engine itself. Satori implements a subset of CSS - flexbox layouts work well, but grid, certain pseudo-selectors, and complex visual effects are not supported. For straightforward card layouts with text, a background, and a logo, this is rarely a problem. For OG images that need to closely mirror your actual product UI - a chart, a live dashboard state, a complex component - you will hit the limits of what Satori can render.

Pattern 2: Screenshot-Based Generation via External API

The second pattern sidesteps rendering limitations entirely by capturing an actual screenshot of a dedicated visual route. You build a route specifically designed to look good as a 1200x630 card - /og/[slug] - and instead of reimplementing that layout in Satori's CSS subset, you screenshot the real rendered page using full browser rendering.

// Fetching a screenshot for use as an OG image source
async function getOgImageUrl(slug: string) {
  const targetUrl = `https://yourapp.com/og/${slug}`;

  const response = await fetch('https://api.snapshot-provider.com/v1/capture', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.SCREENSHOT_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      url: targetUrl,
      viewport: { width: 1200, height: 630 },
      format: 'png',
      wait_until: 'networkidle2',
    }),
  });

  const data = await response.json();
  return data.image_url;
}

This is the right approach when your card design needs full CSS - real grid layouts, web fonts that Satori does not support well, charts rendered with a JS charting library, or any visual complexity beyond what an SVG-based renderer handles cleanly. Using an Open Graph image API for this means you get a genuine browser rendering pipeline behind the capture rather than reimplementing your design twice - once in your app, once in Satori-compatible JSX.

The trade-off is latency and an external dependency. A real browser render-and-capture cycle takes longer than Satori's SVG-to-PNG path, and you are now relying on a third-party service's uptime for a piece of your social sharing pipeline. This is exactly why caching matters more here than in the edge-rendering pattern - more on that below.

Pattern 3: Hybrid Middleware-Triggered Generation

The third pattern combines the two: use edge generation as the default, fast path, and fall back to a screenshot-based render only for routes that genuinely need it. A middleware function inspects the request and routes accordingly.

This works well when most of your OG images are simple (text + background, handled fine by Satori) but a subset of routes - say, pages with embedded data visualizations - need full rendering fidelity. Middleware checks a route pattern or a flag in your CMS data and dispatches to the appropriate generation path, keeping the fast case fast and reserving the heavier screenshot path for where it is actually needed.

Performance Engineering

Cache by route slug, not by request. OG images for a given piece of content rarely change between requests. Generate once per slug, cache aggressively, and invalidate only when the underlying content changes - on publish or edit, not on every social platform's crawl request. A CDN cache key based on the slug (and any meaningful query parameters) turns most of your traffic into cache hits regardless of which generation pattern you use.

Always have a fallback graphic. Generation can fail - a timeout, a missing parameter, an external API hiccup. Social platforms that fail to load an og:image URL either show nothing or fall back to a generic favicon, both of which look broken. Configure a static fallback image and route any generation failure to it rather than returning a 500 or an empty response.

Manage cold starts deliberately. Edge functions for OG generation are typically fast, but serverless functions calling external screenshot APIs can have cold start overhead on infrequently hit routes. If your screenshot-based pattern serves low-traffic long-tail content, consider pre-generating OG images at build or publish time rather than generating on first request - this removes cold start latency from the user-facing path entirely, since the crawler hitting the link preview never triggers generation directly.

Choosing a Pattern

For most applications, start with edge generation - it covers the majority of OG image needs with minimal infrastructure and no external dependency. Reach for screenshot-based generation specifically when your card design requires rendering fidelity that Satori cannot provide. Use the hybrid pattern once you have enough routes in each category that maintaining both paths is worth the added complexity.

The decision is rarely all-or-nothing in practice - most production Next.js apps running at scale end up with some version of the hybrid model, even if it starts as a single edge-rendered template.