screencut

Headless Chromium screenshots — CLI and Node.js SDK.

Install

npm install screencut

Chromium is downloaded automatically by Puppeteer on install. If you already have Chromium on your system (Docker, CI), skip the download and point to your binary instead:

PUPPETEER_SKIP_DOWNLOAD=true npm install screencut
PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium screencut https://example.com

CLI

npx screencut <url> [output] [options]

output defaults to screenshot-YYYY-MM-DD-HH-mm-ss.png (with timestamp). The image format is inferred from the file extension when --type is not set.

| Flag | Default | Description | |------------------|------------------|---------------------------------------------------------------------------------| | --width | 1280 | Viewport width in pixels | | --height | 720 | Viewport height in pixels | | --type | png | Image format: png, jpeg, webp | | --quality | 80 | Compression quality for jpeg / webp (0–100) | | --scale | 1 | Device pixel ratio for HiDPI output (2 = retina) | | --full-page | off | Capture the full scrollable page | | --wait-for | — | CSS selector to wait for before capturing | | --wait-until | networkidle2 | Navigation strategy: load, domcontentloaded, networkidle0, networkidle2 | | --timeout | 30000 | Navigation timeout in ms | | --delay | 0 | Extra wait time in ms after page load | | --wait-for-stable | off | Enable intelligent waiting for page stability | | --scroll-delay | 500 | Delay in ms between scrolls when waitForStable is enabled | | --max-scroll-attempts | 5 | Max scroll attempts for lazy loading | | --no-wait-for-network-idle | off | Disable network idle check between scrolls | | --quiet | off | Suppress all output except errors | | --verbose | off | Enable verbose debug output | | --no-timestamp | off | Disable timestamp in output filename (enabled by default) | | --dark-mode | off | Emulate prefers-color-scheme: dark | | --emulate-media-type| screen | Emulate media type: screen, print, handheld | | --user-agent | — | Override the browser user-agent string | | --stdout | off | Write image bytes to stdout instead of a file | | -v, --version | | Print version and exit | | -h, --help | | Show help |

# Save to a file
screencut https://example.com
screencut https://example.com shot.png

# Full-page JPEG
screencut https://example.com shot.jpeg --full-page --quality 90

# Retina screenshot
screencut https://example.com retina.png --scale 2

# Faster capture — skip waiting for network idle
screencut https://example.com --wait-until domcontentloaded

# Wait for a specific element to appear
screencut https://example.com --wait-for "#hero" --timeout 10000

# Mobile user-agent
screencut https://example.com --user-agent "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0)"

# Pipe bytes to another tool
screencut https://example.com --stdout | convert - -resize 400x thumb.jpg
screencut https://example.com --stdout > shot.png

# Full-page capture with lazy-loading and animations
screencut https://example.com --full-page --wait-for-stable
screencut https://example.com --full-page --wait-for-stable --scroll-delay 1000

# Dark mode
screencut https://example.com --dark-mode

# Disable timestamp
screencut https://example.com --no-timestamp

SDK

const screencut = require('screencut');

require('screencut') returns a ready-to-use instance. No setup needed.

capture(url, options?) → Promise<Buffer>

const buf = await screencut.capture('https://example.com');

const buf = await screencut.capture('https://example.com', {
  width: 1920,
  height: 1080,
  type: 'jpeg',
  quality: 90,
  fullPage: true,
});

captureAsStream(url, options?) → Readable

Returns a stream synchronously — the capture runs in the background and data is pushed when ready. Pipe it anywhere without awaiting.

// Stream to an HTTP response
res.setHeader('Content-Type', 'image/png');
screencut.captureAsStream('https://example.com').pipe(res);

// Stream to a file
screencut.captureAsStream('https://example.com').pipe(fs.createWriteStream('shot.png'));

captureAsBase64(url, options?) → Promise<string>

const b64 = await screencut.captureAsBase64('https://example.com');
// "iVBORw0KGgoAAAANSUhEUgAA..."

captureAsDataURL(url, options?) → Promise<string>

const dataUrl = await screencut.captureAsDataURL('https://example.com', {
  type: 'jpeg',
  quality: 85,
});
// "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."

const html = `<img src="${dataUrl}" />`;

captureToFile(url, outputPath, options?) → Promise<void>

await screencut.captureToFile('https://example.com', './shot.png');

await screencut.captureToFile('https://example.com', './shot.jpeg', {
  type: 'jpeg',
  quality: 80,
  fullPage: true,
});

close() → Promise<void>

Closes the underlying Chromium instance. The default instance closes itself automatically on SIGINT, SIGTERM, and beforeExit. Call close() manually when using a custom instance.

await screencut.close();

Options

All capture methods accept the same options object. Every field is optional.

| Option | Type | Default | Description | |---------------------|-----------|------------------|-------------------------------------------------------------------------------------| | width | number | 1280 | Viewport width in pixels | | height | number | 720 | Viewport height in pixels | | type | string | 'png' | Image format: 'png', 'jpeg', 'webp' | | quality | number | 80 | Compression quality for jpeg and webp (0–100) | | fullPage | boolean | false | Capture the full scrollable page | | waitFor | string | — | CSS selector to wait for before capturing | | waitUntil | string | 'networkidle2' | Navigation strategy: 'load', 'domcontentloaded', 'networkidle0', 'networkidle2' | | timeout | number | 30000 | Navigation timeout in milliseconds | | userAgent | string | — | Override the browser user-agent string | | deviceScaleFactor | number | 1 | Device pixel ratio for HiDPI / retina output | | delay | number | 0 | Extra wait time in ms after page load | | waitForStable | boolean | false | Enable intelligent waiting for page stability | | scrollDelay | number | 500 | Delay in ms between scrolls when waitForStable is enabled | | maxScrollAttempts | number | 5 | Max scroll attempts for lazy loading | | waitForNetworkIdle| boolean | true | Wait for network idle between scrolls | | quiet | boolean | false | Suppress all output except errors | | verbose | boolean | false | Enable verbose debug output | | darkMode | boolean | false | Emulate prefers-color-scheme: dark | | timestamp | boolean | true | Add timestamp to output filename (default: true) | | emulateMediaType | string | screen | Emulate media type: screen, print, handheld | | clip | object | — | Restrict capture to a region: { x, y, width, height }. Ignored when fullPage is true. |

Custom instance

Use new Screencut(defaults?) when you need an isolated browser with its own defaults. You are responsible for calling close().

const { Screencut } = require('screencut');

const mobile = new Screencut({
  width: 390,
  height: 844,
  userAgent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15',
});

const buf = await mobile.capture('https://example.com');
await mobile.close();

LaunchDefaults extends all capture options and adds two browser-level fields:

| Option | Type | Default | Description | |------------|------------|---------|-----------------------------------------------| | headless | boolean | true | Set to false to debug captures visually | | args | string[] | [...] | Additional Chromium launch flags |

Recipes

Express screenshot endpoint

const express = require('express');
const screencut = require('screencut');

const app = express();

app.get('/screenshot', (req, res) => {
  const { url } = req.query;
  if (!url) return res.status(400).send('Missing ?url=');

  res.setHeader('Content-Type', 'image/png');
  screencut.captureAsStream(url).pipe(res);
});

app.listen(3000);

Thumbnail generation with sharp

const sharp = require('sharp');
const screencut = require('screencut');

const buf = await screencut.capture('https://example.com');
const thumb = await sharp(buf).resize(400, 225).toBuffer();

Batch captures

One instance handles multiple concurrent captures — no need to spawn a browser per URL.

const screencut = require('screencut');

const urls = ['https://example.com', 'https://github.com', 'https://nodejs.org'];

const buffers = await Promise.all(urls.map(url => screencut.capture(url)));

If you need truly isolated browser processes (different proxies, separate sessions), create one instance per process:

const { Screencut } = require('screencut');

const a = new Screencut({ args: ['--proxy-server=socks5://proxy1:1080'] });
const b = new Screencut({ args: ['--proxy-server=socks5://proxy2:1080'] });

const [bufA, bufB] = await Promise.all([
  a.capture('https://example.com'),
  b.capture('https://example.com'),
]);

await Promise.all([a.close(), b.close()]);

Clip a region

const buf = await screencut.capture('https://example.com', {
  clip: { x: 0, y: 0, width: 600, height: 400 },
});

TypeScript

Types are bundled. No @types package needed.

import screencut, { Screencut, CaptureOptions, LaunchDefaults } from 'screencut';

const options: CaptureOptions = {
  width: 1440,
  type: 'webp',
  quality: 90,
  fullPage: true,
  waitUntil: 'domcontentloaded',
};

const buf: Buffer = await screencut.capture('https://example.com', options);

import { Screencut, LaunchDefaults } from 'screencut';

const defaults: LaunchDefaults = {
  width: 390,
  height: 844,
  headless: true,
};

const instance = new Screencut(defaults);
const buf = await instance.capture('https://example.com');
await instance.close();

Requirements

• Node.js >= 18.0.0
• Chromium — downloaded automatically by Puppeteer on npm install

License

MIT