Official SDKv1.x

Node.js SDK

Official Node.js SDK for SnapSharp. Take screenshots, generate OG images, render HTML to PNG. npm install @snapsharp/sdk

Installation

Install the Node.js SDK using your package manager:

shell

npm install @snapsharp/sdk

Then import and initialise the client:

typescript

import { SnapSharp } from '@snapsharp/sdk';

const snap = new SnapSharp('sk_live_...');

Replace sk_live_... with your API key from the dashboard.

Quick Start

Three common use cases to get you up and running in minutes.

1. Take a Screenshot

Capture a full-page or viewport screenshot of any URL and save it to disk.

typescript

import { SnapSharp } from '@snapsharp/sdk';
import fs from 'fs';

const snap = new SnapSharp('sk_live_...');

const image = await snap.screenshot('https://example.com', {
  width: 1280,
  height: 720,
  format: 'png',
  fullPage: false,
});

fs.writeFileSync('screenshot.png', image);
console.log('Screenshot saved!');

2. Generate an OG Image

Create Open Graph images ready for social media sharing with built-in templates.

typescript

import { SnapSharp } from '@snapsharp/sdk';
import fs from 'fs';

const snap = new SnapSharp('sk_live_...');

const og = await snap.ogImage('https://example.com', {
  template: 'default',
  width: 1200,
  height: 630,
});

fs.writeFileSync('og-image.png', og);

3. Render HTML to Image

Pass raw HTML and CSS to render a pixel-perfect image without hosting a page.

typescript

import { SnapSharp } from '@snapsharp/sdk';
import fs from 'fs';

const snap = new SnapSharp('sk_live_...');

const image = await snap.htmlToImage(
  '<div style="padding:40px"><h1>Hello World</h1><p>Rendered by SnapSharp</p></div>',
  {
    width: 800,
    height: 400,
    format: 'png',
    css: 'body { font-family: Inter, sans-serif; background: #1a1a2e; color: #fff; display: grid; place-items: center; }',
  },
);

fs.writeFileSync('html-render.png', image);

API Reference

Complete list of methods available on the Node.js client.

screenshot()

screenshot(url: string, options?: ScreenshotOptions): Promise<Buffer>

Captures a screenshot of the given URL. Supports viewport dimensions, format (png/jpeg/webp), full-page mode, device emulation, dark mode, delay, and custom headers.

ogImage()

ogImage(url: string, options?: OGImageOptions): Promise<Buffer>

Generates an Open Graph image for the URL using built-in or custom templates. Returns a 1200×630 image optimized for social media sharing.

htmlToImage()

htmlToImage(html: string, options?: HTMLOptions): Promise<Buffer>

Renders raw HTML/CSS markup into an image. Supports inline styles, external fonts, custom viewport size, and transparent backgrounds.

siteAudit()

siteAudit(url: string, options?: AuditOptions): Promise<AuditResult>

Runs a performance and SEO audit on the URL. Returns Lighthouse-style scores for performance, accessibility, SEO, and best practices with actionable recommendations.

ping()

ping(): Promise<{ status: string; latency: number }>

Health-check endpoint. Returns API status and round-trip latency in milliseconds. Useful for connection validation on startup.

All methods that return images accept an optional format parameter ("png", "jpeg", "webp"). Default is "png". See the full API reference for every available option.

Error Handling

The SDK throws typed errors with HTTP status, message, and a unique request ID for debugging. Always wrap calls in a try/catch to handle rate limits and authentication errors gracefully.

typescript

import { SnapSharp, SnapSharpError } from '@snapsharp/sdk';

const snap = new SnapSharp('sk_live_...');

try {
  const image = await snap.screenshot('https://example.com');
} catch (error) {
  if (error instanceof SnapSharpError) {
    console.error(`Error ${error.status}: ${error.message}`);
    console.error('Request ID:', error.requestId);

    if (error.status === 401) {
      console.error('Invalid API key. Check your credentials.');
    }
    if (error.status === 429) {
      console.error('Rate limited. Retry after:', error.retryAfter, 'seconds');
    }
  }
}

Status	Meaning	Action
400	Bad Request — invalid parameters	Check the request body and query params
401	Unauthorized — invalid or missing API key	Verify your API key in the dashboard
429	Too Many Requests — rate limit exceeded	Wait for `retryAfter` seconds
500	Internal Server Error	Retry with exponential back-off

Configuration

Customise the client with optional settings passed at initialisation.

typescript

const snap = new SnapSharp('sk_live_...', {
  baseUrl: 'https://api.snapsharp.dev',   // Custom API base URL
  timeout: 30_000,                         // Request timeout in ms
  retries: 2,                              // Auto-retry on 5xx errors
  headers: { 'X-Custom-Header': 'value' }, // Extra headers per request
});

Option	Default	Description
baseUrl	api.snapsharp.dev	Override the API base URL (e.g. for on-premise)
timeout	30s	Maximum time to wait for a response
retries	0	Number of automatic retries on 5xx errors

SDKs for other languages

Python PHP Go Ruby

Ready to start building?

Get your free API key and start capturing screenshots in under a minute. 100 free screenshots every month — no credit card required.

Get Free API Key Read the Docs