URL to PNG

URL-to-PNG is a lightweight, self‑hosted service that renders arbitrary web pages into PNG snapshots over HTTP. It exposes a minimal query‑string API, allowing developers to embed rendered images directly in HTML or generate them on demand for static sites, documentation generators, or monitoring dashboards. The core functionality is powered by Playwright, a browser automation library that guarantees accurate rendering across modern browsers while providing fine‑grained control over viewport, user agent, and dark mode. The service also incorporates a cache layer, optional domain allow‑listing, and pluggable storage backends (S3, CouchDB, or the local filesystem) to persist generated images for reuse.

Key Features

• API‑First Rendering – Pass url, width, height, and optional flags (e.g., darkMode=true) as query parameters; the endpoint returns a PNG image or a cached copy.
• Headless Chromium via Playwright – Uses the same engine as automated testing suites, ensuring consistency with real‑world browser rendering and support for modern JavaScript/CSS.
• Domain Whitelisting – Prevents accidental scraping or denial‑of‑service by restricting which URLs may be rendered.
• Configurable Caching – In‑memory or external caches reduce repeated rendering costs and improve latency.
• Extensible Storage – Built‑in adapters for AWS S3, CouchDB, and local files make it easy to persist artifacts in the storage system that best fits an organization’s architecture.
• Metrics Exposure – A Prometheus‑compatible endpoint provides request counts, cache hit ratios, and latency distributions for observability.

Technical Stack

The application is written in TypeScript, providing strong typing across the API surface and configuration schema. The build pipeline uses pnpm for deterministic dependency resolution, ensuring consistent installs across environments.

Core Capabilities

• Dynamic Image Generation – Render any public URL to PNG with optional viewport and dark mode adjustments.
• Caching API – GET /cache endpoints expose cache statistics; developers can pre‑warm or purge caches programmatically.
• Custom Playwright Options – Advanced users may tweak launch arguments (e.g., headless mode, proxy settings) through configuration files.
• Webhook‑like Callbacks – Post‑render hooks can trigger downstream processes (e.g., uploading to a CDN) via configurable HTTP callbacks.
• Extensible Plugin System – While not a full plugin framework, the service exposes hooks for custom middleware in Fastify, allowing developers to inject authentication or rate‑limiting logic.

Deployment & Infrastructure

The service is intentionally minimal, making it suitable for:

• Docker‑Based Environments – A single container runs out of the box; environment variables expose all configuration.
• Kubernetes – Deploy as a Deployment with an Ingress controller; use ConfigMaps for config files and Secrets for credentials.
• Bare Metal / VMs – Run node directly after installing dependencies; no external services required beyond optional cache or storage backends.
• Scalability – Stateless HTTP handling allows horizontal scaling behind a load balancer; the cache layer can be shared via Redis or a CDN to reduce rendering overhead.

Integration & Extensibility

• RESTful API – The query‑string interface is trivial to consume from any language; no SDKs are required.
• Webhooks – After rendering, the service can notify external services via configurable URLs, enabling CI/CD pipelines or monitoring alerts.
• Custom Middleware – Fastify’s plugin system lets developers add authentication, IP rate limiting, or logging without touching core code.
• Storage Plug‑Ins – Adding a new backend typically involves implementing the Store interface; community contributions have already added S3 and CouchDB support.

Developer Experience

• Configuration – A single YAML/JSON file defines all options; the CLI offers a --config flag for overrides. Documentation is hosted on GitHub Pages and includes examples for every feature.
• TypeScript Types – The public API surface is fully typed, enabling IDE autocomplete and compile‑time validation.
• Community & Licensing – MIT license allows unrestricted use; active GitHub issues and pull requests demonstrate responsive maintenance. The project’s star history indicates steady adoption in the open‑source community.
• Metrics & Observability – Prometheus metrics integrate seamlessly with existing monitoring stacks, giving developers insight into rendering performance and cache efficiency.

Use Cases