Website Screenshot Service

English | 简体中文

A high-performance, stateless microservice for generating website screenshots. Built with Node.js, Fastify, and Puppeteer, it features advanced anti-detection capabilities, ad blocking, and cookie banner handling.

✨ Features

• 🚀 High Performance: Configurable concurrency with a custom semaphore-based browser pool.
• 🕵️ Anti-Detection: Integrated stealth plugin and optimized launch arguments to bypass bot detection.
• 🚫 Ad & Tracker Blocking: Built-in blocking engine based on uBlock Origin rules.
• 🍪 Smart Cookie Handling: Automatically detects and dismisses GDPR/cookie consent popups.
• 📸 Versatile Output: Supports WebP, PNG, and JPEG formats in both Base64 and binary responses.
• 🐳 Production Ready: Dockerized with health checks, graceful shutdown, and resource limits.
• 🔒 Secure: Optional API Key authentication and rate limiting.

🛠️ Tech Stack

• Runtime: Node.js 20+
• Framework: Fastify
• Browser Automation: Puppeteer (with puppeteer-extra)
• Image Processing: Sharp
• Language: TypeScript

🚀 Quick Start

Prerequisites

• Node.js 20 or higher
• Docker (optional)

Local Development

1. Clone the repository

   git clone https://github.com/DonRainl/website-screenshot-service.git
   cd website-screenshot-service

2. Install dependencies

   npm install

3. Configure environment

   cp .env.example .env
   # Edit .env as needed

4. Start the development server

   npm run dev

The server will start at http://localhost:3000.

Docker Deployment

Using Docker Compose (Recommended):

docker-compose up -d

Manual Build:

docker build -t screenshot-service .
docker run -p 3000:3000 --env-file .env screenshot-service

🔌 API Reference

Health Check

GET /health - Returns service status and browser pool statistics.

Take Screenshot

POST /api/screenshot

Body:

{
  "url": "https://example.com",
  "options": {
    "width": 1920,
    "height": 1080,
    "format": "webp",
    "responseType": "base64",
    "blockAds": true
  }
}

Options:

• width (number): Viewport width (default: 1920)
• height (number): Viewport height (default: 1080)
• format (string): 'webp', 'png', or 'jpeg' (default: 'webp')
• quality (number): Image quality 1-100 (default: 80)
• responseType (string): 'base64' or 'binary' (default: 'base64')
• blockAds (boolean): Enable ad blocker (default: true)
• blockCookieBanners (boolean): Attempt to dismiss cookie banners (default: true)
• delay (number): Wait time in ms after load (default: 1000)

⚙️ Configuration

Variable	Default	Description
PORT	3000	Server listening port
MAX_CONCURRENCY	5	Max parallel screenshot tasks
DEFAULT_TIMEOUT	30000	Global timeout in ms
ENABLE_STEALTH	true	Enable anti-detection stealth plugin
ENABLE_ADBLOCKER	true	Enable ad/tracker blocking
API_KEY	-	Optional. If set, requires x-api-key header
RATE_LIMIT_MAX	10	Max requests per minute per IP

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the project
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.