Node.js SDK

The official Node.js/TypeScript SDK for RenderScreenshot.

Installation

npm install renderscreenshot

Requirements

• Node.js 18.0.0 or higher

Quick Start

import { Client, TakeOptions } from 'renderscreenshot';

const client = new Client('rs_live_xxxxx');

// Take a screenshot
const image = await client.take(
  TakeOptions.url('https://example.com').preset('og_card')
);

Client

Constructor

import { Client } from 'renderscreenshot';

const client = new Client(apiKey, options);

Methods

take(options)

Take a screenshot and return binary data.

const image = await client.take(
  TakeOptions.url('https://example.com').preset('og_card')
);

// Save to file
import { writeFile } from 'fs/promises';
await writeFile('screenshot.png', image);

Returns: Promise<Buffer>

takeJson(options)

Take a screenshot and return JSON metadata.

const response = await client.takeJson(
  TakeOptions.url('https://example.com').preset('og_card')
);

console.log(response.url);     // CDN URL
console.log(response.width);   // 1200
console.log(response.height);  // 630
console.log(response.cached);  // true/false

Returns: Promise<ScreenshotResponse>

generateUrl(options, expiresAt)

Generate a signed URL for public embedding.

const signedUrl = client.generateUrl(
  TakeOptions.url('https://example.com').preset('og_card'),
  new Date(Date.now() + 24 * 60 * 60 * 1000) // 24 hours
);

// Use in HTML: <img src="${signedUrl}" />

Returns: string

batch(urls, options) / batch(requests)

Process multiple screenshots in a batch.

// Simple batch
const results = await client.batch(
  ['https://example1.com', 'https://example2.com'],
  TakeOptions.url('').preset('og_card')
);

// Advanced batch with per-URL options
const results = await client.batch([
  { url: 'https://example1.com', options: { preset: 'og_card' } },
  { url: 'https://example2.com', options: { width: 1920 } },
]);

Returns: Promise<BatchResponse>

getBatch(batchId)

Get the status of a batch job.

const status = await client.getBatch('batch_abc123');
console.log(status.completed, status.total);

Returns: Promise<BatchResponse>

presets() / preset(id)

Get available presets.

const presets = await client.presets();
const ogCard = await client.preset('og_card');

devices()

Get available device presets.

const devices = await client.devices();

TakeOptions

Fluent builder for screenshot options.

Creating Options

import { TakeOptions } from 'renderscreenshot';

// From URL
const options = TakeOptions.url('https://example.com');

// From HTML
const options = TakeOptions.html('<h1>Hello World</h1>');

// From config object
const options = TakeOptions.from({ url: '...', width: 1200 });

Viewport Options

TakeOptions.url('...')
  .width(1200)           // Viewport width
  .height(630)           // Viewport height
  .scale(2)              // Device scale factor (1-3)
  .mobile()              // Enable mobile emulation

Capture Options

TakeOptions.url('...')
  .fullPage()            // Capture full scrollable page
  .element('.hero')      // Capture specific element
  .format('png')         // png, jpeg, webp, pdf
  .quality(90)           // JPEG/WebP quality (1-100)

Wait Options

TakeOptions.url('...')
  .waitFor('networkidle')      // load, networkidle, domcontentloaded
  .delay(2000)                 // Additional delay (ms)
  .waitForSelector('.loaded')  // Wait for selector
  .waitForTimeout(30000)       // Max wait time (ms)

Presets & Devices

TakeOptions.url('...')
  .preset('og_card')           // Use a preset
  .device('iphone_14_pro')     // Emulate a device

Content Blocking

TakeOptions.url('...')
  .blockAds()                  // Block ad networks
  .blockTrackers()             // Block analytics
  .blockCookieBanners()        // Auto-dismiss cookie popups
  .blockChatWidgets()          // Block chat widgets
  .blockUrls(['*.ads.com/*'])  // Block URL patterns
  .blockResources(['font'])    // Block resource types

Browser Emulation

TakeOptions.url('...')
  .darkMode()                  // Enable dark mode
  .reducedMotion()             // Prefer reduced motion
  .mediaType('print')          // screen or print
  .userAgent('Custom UA')      // Custom user agent
  .timezone('America/New_York')
  .locale('en-US')
  .geolocation(40.7128, -74.006)

Network Options

TakeOptions.url('...')
  .headers({ 'X-Custom': 'value' })
  .cookies([{ name: 'session', value: 'abc', domain: 'example.com' }])
  .authBasic('user', 'pass')
  .authBearer('token')
  .bypassCsp()

Cache Options

TakeOptions.url('...')
  .cacheTtl(86400)             // Cache TTL in seconds
  .cacheRefresh()              // Force refresh

PDF Options

TakeOptions.url('...')
  .format('pdf')
  .pdfPaperSize('a4')          // a4, letter, legal, etc.
  .pdfLandscape()
  .pdfMargin('1in')
  .pdfPrintBackground()
  .pdfHeader('<div>Header</div>')
  .pdfFooter('<div>Page <span class="pageNumber"></span></div>')

Storage Options (BYOS)

TakeOptions.url('...')
  .storageEnabled()
  .storagePath('{year}/{month}/{hash}.{ext}')
  .storageAcl('public-read')

Cache Management

// Get cached screenshot
const image = await client.cache.get('cache_xyz789');

// Delete single entry
await client.cache.delete('cache_xyz789');

// Bulk purge by keys
await client.cache.purge(['cache_abc', 'cache_def']);

// Purge by URL pattern
await client.cache.purgeUrl('https://mysite.com/blog/*');

// Purge by date
await client.cache.purgeBefore(new Date('2024-01-01'));

Webhook Helpers

import { verifyWebhook, parseWebhook } from 'renderscreenshot';

// Verify signature
const isValid = verifyWebhook(payload, signature, timestamp, secret);

// Parse event
const event = parseWebhook(payload);
if (event.type === 'screenshot.completed') {
  console.log(event.data.response?.url);
}

Error Handling

import { RenderScreenshotError } from 'renderscreenshot';

try {
  await client.take(TakeOptions.url('...'));
} catch (error) {
  if (error instanceof RenderScreenshotError) {
    console.log(error.httpStatus);  // 400, 429, etc.
    console.log(error.code);        // 'invalid_url', 'rate_limited'
    console.log(error.message);     // Human-readable message
    console.log(error.retryable);   // true/false
    console.log(error.retryAfter);  // Seconds (for rate limits)
  }
}

Error Codes

TypeScript

The SDK is written in TypeScript and provides full type definitions.

import {
  Client,
  TakeOptions,
  RenderScreenshotError,
  type ScreenshotResponse,
  type BatchResponse,
  type TakeOptionsConfig,
} from 'renderscreenshot';

Links

• npm package
• GitHub repository
• API Reference