@kiliman/screenshot

Generate high-quality screenshots from HTML files using Playwright.

Features

• 🎯 Simple CLI interface
• 🖼️ Support for PNG and JPEG formats
• 📐 Customizable viewport dimensions
• 🎨 Retina-quality output (2x device scale)
• 🚀 Fast and reliable with Playwright
• 📦 Zero configuration needed

Installation

# Use with npx (no installation required)
npx @kiliman/screenshot page.html

# Or install globally
pnpm add -g @kiliman/screenshot

Usage

Basic Usage

# Generate a PNG screenshot with default settings
npx @kiliman/screenshot page.html

# Specify output filename
npx @kiliman/screenshot page.html screenshot.png

# Use JPEG format
npx @kiliman/screenshot page.html --format jpg

# Use size presets for common social media platforms
npx @kiliman/screenshot page.html --size github
npx @kiliman/screenshot page.html --size og --format jpg
npx @kiliman/screenshot page.html --size twitter

# Custom dimensions
npx @kiliman/screenshot page.html --width 1920 --height 1080

# Output to specific directory
npx @kiliman/screenshot page.html --outdir ./screenshots

# Real example: The social preview image above was generated using this package!
npx @kiliman/screenshot assets/social-preview.html social-preview.jpg --outdir assets --size github --format jpg

Size Presets

Use --size to quickly generate screenshots optimized for different platforms:

| Preset | Dimensions | Description | |-------------|--------------|--------------------------------------| | github | 1280×640 | GitHub social preview | | og | 1200×630 | Open Graph (Facebook, LinkedIn) | | twitter | 1200×675 | Twitter/X card | | instagram | 1080×1080 | Instagram post (square) | | hd | 1920×1080 | HD/Full HD | | 4k | 3840×2160 | 4K/Ultra HD |

You can override preset dimensions with --width and --height:

# Use Twitter preset but make it wider
npx @kiliman/screenshot page.html --size twitter --width 1600

CLI Options

Usage: npx @kiliman/screenshot HTML_FILE [OUT_FILE] [OPTIONS]

Arguments:
  HTML_FILE              Path to the HTML file to screenshot (required)
  OUT_FILE              Output filename (optional, default: basename.format)

Options:
  --size PRESET         Use a size preset (github, og, twitter, instagram, hd, 4k)
  --width WIDTH         Viewport width in pixels (default: 1280)
  --height HEIGHT       Viewport height in pixels (default: 720)
  --format FORMAT       Image format: png, jpg, jpeg (default: png)
  --outdir DIR          Output directory (default: current directory)
  --help, -h            Show help message

Note: --width and --height override --size preset values

Programmatic Usage

You can also use this package programmatically in your Node.js projects:

import { generateScreenshot } from '@kiliman/screenshot';

// Using size preset
await generateScreenshot('page.html', 'output.png', {
  size: 'github',
  format: 'jpg',
  outdir: './screenshots'
});

// Using custom dimensions
await generateScreenshot('page.html', 'output.png', {
  width: 1920,
  height: 1080,
  format: 'png',
  outdir: './screenshots'
});

API

generateScreenshot(htmlFile, outputFile?, options?)

Generates a screenshot from an HTML file.

Parameters:

• htmlFile (string, required): Path to the HTML file
• outputFile (string, optional): Output filename (default: basename + format extension)
• options (object, optional):
  • size ('github' | 'og' | 'twitter' | 'instagram' | 'hd' | '4k'): Size preset
  • width (number): Viewport width in pixels (default: 1280, overrides size preset)
  • height (number): Viewport height in pixels (default: 720, overrides size preset)
  • format ('png' | 'jpg' | 'jpeg'): Image format (default: 'png')
  • outdir (string): Output directory (default: current directory)
  • quality (number): JPEG quality 0-100 (default: 85, only for JPEG)

Returns: Promise - The full path to the generated screenshot

Requirements

• Node.js 18 or higher
• Playwright will automatically download required browser binaries on first use

License

MIT © Michael Carter

Author

Created by Michael Carter