browsergrab

Official JavaScript / TypeScript SDK for the BrowserGrab Screenshot API.

Capture pixel-perfect screenshots of any URL with a single function call. Works in Node.js, Deno, Bun, and any environment with the Fetch API.

Installation

npm install browsergrab
# or
yarn add browsergrab
# or
pnpm add browsergrab

Quick start

import BrowserGrab from "browsergrab";

const client = new BrowserGrab("bg_live_your_api_key");

const result = await client.screenshot({ url: "https://example.com" });
console.log(result.url); // https://cdn.browsergrab.app/screenshots/...

Get your API key from browsergrab.app/dashboard/keys.

Usage

Basic screenshot

const result = await client.screenshot({
  url: "https://stripe.com",
});
// result.url  — CDN URL to the PNG
// result.width, result.height, result.format

All options

const result = await client.screenshot({
  url: "https://github.com",

  // Output
  format: "webp",       // "png" | "jpeg" | "webp"  (default: "png")
  width: 1920,          // viewport width  (default: 1280)
  height: 1080,         // viewport height (default: 800)
  fullPage: true,       // capture full scrollable height (default: false)
  waitFor: 1500,        // extra ms to wait after load (default: 0)
  storage: "cloud",     // "cloud" | "gdrive" | "none" (default: "cloud")

  // Super plan only
  retina: true,         // 2× device pixel ratio
  darkMode: true,       // force prefers-color-scheme: dark
  blockAds: true,       // block ads before capture
  quality: 90,          // JPEG/WebP quality 1–100
});

Storage options

| storage | Result | |---|---| | "cloud" | Stored on BrowserGrab CDN — returns a permanent public URL | | "gdrive" | Saved to your connected Google Drive — returns a Drive link | | "none" | Returns a data:image/...;base64,... string, nothing stored remotely |

Error handling

import BrowserGrab, { BrowserGrabError } from "browsergrab";

const client = new BrowserGrab("bg_live_xxx");

try {
  const result = await client.screenshot({ url: "https://example.com" });
  console.log(result.url);
} catch (err) {
  if (err instanceof BrowserGrabError) {
    console.error(err.message);  // human-readable message
    console.error(err.code);     // machine-readable: "quota_exceeded", "invalid_api_key", etc.
    console.error(err.status);   // HTTP status code
    console.error(err.charged);  // false = no credit was used
  }
}

Common error codes

| Code | HTTP | Meaning | |---|---|---| | invalid_api_key | 401 | API key not found or revoked | | quota_exceeded | 429 | Monthly screenshot limit reached | | dimension_exceeds_plan | 403 | Resolution exceeds your plan limit | | feature_requires_super | 403 | retina/darkMode/blockAds need Super plan | | page_load_failed | 422 | Page couldn't load (DNS error, blank page) — not charged | | timeout | 0 | Request timed out client-side | | network_error | 0 | Network failure — not charged |

Client options

const client = new BrowserGrab("bg_live_xxx", {
  retries: 3,          // retry on 5xx errors (default: 2)
  timeoutMs: 60_000,   // request timeout in ms (default: 90000)
  baseUrl: "https://...", // override API base URL
});

Plans

| | Free | Super | |---|---|---| | Screenshots/month | 15 | 5,000 | | Max resolution | 1920×1080 | 3840×2160 | | Retina (2×) | ✗ | ✓ | | Dark mode | ✗ | ✓ | | Ad blocking | ✗ | ✓ | | Cloud storage | ✓ | ✓ | | Google Drive | ✗ | ✓ |

License

MIT