Complete Node.js screenshot API tutorial

This guide covers everything from your first screenshot to production patterns: error handling, retries, caching, and processing screenshots at scale in Node.js.

Installation and setup

npm install @sleywill/snapapi-js
# or use fetch directly — no dependencies required

Your first screenshot (3 lines)

import SnapAPI from '@sleywill/snapapi-js';
const client = new SnapAPI(process.env.SNAPAPI_KEY);
const { url: imageUrl } = await client.screenshot({ url: 'https://example.com' });
console.log(imageUrl); // https://storage.snapapi.pics/screenshots/abc123.jpeg

Full-page screenshot with custom options

const screenshot = await client.screenshot({
  url: 'https://example.com',
  format: 'png',           // png | jpeg | webp | avif
  full_page: true,         // capture entire scrollable page
  width: 1440,             // viewport width
  device: 'iphone_15',    // or any of 26 device presets
  wait_until: 'networkidle', // wait for all network requests
  delay: 1000,             // extra ms after load
  block_ads: true,         // block ads and cookie banners
  dark_mode: false,        // force dark/light mode
});

Express.js: Screenshot endpoint

import express from 'express';
import SnapAPI from '@sleywill/snapapi-js';

const app = express();
const snap = new SnapAPI(process.env.SNAPAPI_KEY);

app.get('/screenshot', async (req, res) => {
  const { url } = req.query;
  if (!url) return res.status(400).json({ error: 'url required' });
  
  try {
    const result = await snap.screenshot({
      url: decodeURIComponent(url),
      format: 'jpeg',
      full_page: false,
      width: 1200
    });
    // Redirect to screenshot URL or proxy it
    res.redirect(result.url);
  } catch (err) {
    res.status(500).json({ error: err.message });
  }
});

app.listen(3000);

Generating PDFs from HTML in Node.js

// Generate a PDF from any URL
const pdf = await snap.pdf({
  url: 'https://example.com/invoice/123',
  format: 'A4',          // A4 | A3 | Letter | Legal
  landscape: false,
  margin: { top: '20mm', right: '20mm', bottom: '20mm', left: '20mm' },
  print_background: true
});
console.log(pdf.url); // PDF URL ready to download or store

Batch screenshots with Promise.all

const urls = ['https://site1.com', 'https://site2.com', 'https://site3.com'];

// Parallel (faster, uses more quota simultaneously)
const results = await Promise.all(
  urls.map(url => snap.screenshot({ url, format: 'jpeg' }))
);

// Sequential with rate control (for large batches)
const screenshots = [];
for (const url of urls) {
  screenshots.push(await snap.screenshot({ url, format: 'jpeg' }));
  await new Promise(r => setTimeout(r, 100)); // 100ms between requests
}

Error handling and retries

async function screenshotWithRetry(url, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await snap.screenshot({ url, format: 'jpeg' });
    } catch (err) {
      if (attempt === maxRetries) throw err;
      // Exponential backoff: 1s, 2s, 4s
      await new Promise(r => setTimeout(r, 1000 * Math.pow(2, attempt - 1)));
    }
  }
}

OG image generation for Next.js apps

One of the most common Node.js use cases for screenshot APIs is generating Open Graph images for social sharing. Here's how to integrate SnapAPI into a Next.js API route:

// pages/api/og-image.js
import SnapAPI from '@sleywill/snapapi-js';
const snap = new SnapAPI(process.env.SNAPAPI_KEY);

export default async function handler(req, res) {
  const { url } = req.query;
  const screenshot = await snap.screenshot({
    url: decodeURIComponent(url),
    width: 1200,
    height: 630,        // Standard OG image dimensions
    format: 'jpeg',
    full_page: false,
    wait_until: 'networkidle'
  });
  // Cache for 1 hour
  res.setHeader('Cache-Control', 's-maxage=3600');
  res.setHeader('Location', screenshot.url);
  res.status(302).end();
}