screenshotly-js package provides a convenient interface for the Screenshotly API in Node.js.
Installation
npm install screenshotly-js
Setup
const { Screenshotly } = require('screenshotly-js');
// Simple setup
const client = new Screenshotly('your-api-key-here');
// Advanced setup with options
const client = new Screenshotly({
apiKey: 'your-api-key-here',
baseUrl: 'https://api.screenshotly.dev', // optional
timeout: 60000 // optional, in milliseconds
});
Store your API key in an environment variable, not in your source code:
const client = new Screenshotly(process.env.SCREENSHOTLY_API_KEY);
Capture a screenshot
const screenshot = await client.capture({
url: 'https://example.com',
viewport_width: 1280,
viewport_height: 800,
format: 'png'
});
if (screenshot.success) {
console.log('Screenshot URL:', screenshot.data.imageUrl);
console.log('Remaining credits:', screenshot.remainingCredits);
} else {
console.error('Error:', screenshot.error);
}
Capture options
| Parameter | Type | Default | Description |
|---|---|---|---|
url | string | — | URL to capture (required) |
name | string | — | Optional name for the screenshot |
viewport_width | number | 1280 | Viewport width in pixels (100–5000) |
viewport_height | number | 1024 | Viewport height in pixels (100–5000) |
full_page | boolean | false | Capture the full scrollable page |
format | string | 'png' | Output format: 'png', 'jpeg', 'webp', 'pdf' |
image_quality | number | 80 | Image quality for JPEG/WebP/PDF (0–100) |
device_scale_factor | number | 1 | Device pixel ratio (1–3, use 2 for retina) |
viewport_mobile | boolean | false | Emulate mobile device |
viewport_has_touch | boolean | false | Enable touch events |
viewport_landscape | boolean | false | Landscape orientation |
wait_for_selector | string | — | CSS selector to wait for |
selector | string | — | CSS selector of element to capture |
delay | number | 0 | Delay in ms before capture (0–10000) |
timeout | number | 60000 | Request timeout in ms (1000–90000) |
block_ads | boolean | false | Block advertisements |
block_cookie_banners | boolean | false | Block cookie consent banners |
block_chats | boolean | false | Block chat widgets |
dark_mode | boolean | — | Emulate dark color scheme |
response_type | string | 'by_format' | Response format: 'by_format', 'json', 'empty' |
Batch capture
Capture multiple URLs with shared settings (max 50 URLs per request):const result = await client.captureBatch({
urls: [
'https://example.com',
'https://google.com',
'https://github.com'
],
options: {
format: 'png',
viewport_width: 1280,
viewport_height: 800,
full_page: true
}
});
if (result.success) {
console.log(`Succeeded: ${result.succeededCount}, Failed: ${result.failedCount}`);
console.log('Remaining credits:', result.remainingCredits);
}
List screenshots
Retrieve your captured screenshots with pagination:const screenshots = await client.getScreenshots(1, 10); // page 1, 10 per page
console.log('Screenshots:', screenshots.data);
Get a screenshot by ID
const screenshot = await client.getScreenshot('67b8a1c2d3e4f5a6b7c8d9e0');
console.log('Status:', screenshot.data.status);
console.log('URL:', screenshot.data.imageUrl);
Delete a screenshot
const result = await client.deleteScreenshot('67b8a1c2d3e4f5a6b7c8d9e0');
console.log('Deleted:', result.success);
Error handling
try {
const screenshot = await client.capture({
url: 'https://example.com'
});
if (!screenshot.success) {
console.error('Capture failed:', screenshot.error);
}
} catch (error) {
// Network errors, timeouts, etc.
console.error('Request failed:', error.message);
}
Using with ES modules
import { Screenshotly } from 'screenshotly-js';
const client = new Screenshotly(process.env.SCREENSHOTLY_API_KEY);