A powerful and beautiful screenshot service that takes high-quality, social media-worthy screenshots of any website using Puppeteer and Chromium. The service supports Apple emojis for beautiful rendering, utilizes BullMQ as an asynchronous job queue system, and stores metadata in MongoDB while serving images through a built-in CDN.
- 📷 High-quality screenshots of any website
- 🔍 Capture specific sections: full page, headers, or custom selectors
- 🌅 Enhanced images optimized for social media sharing
- 🍎 Apple emoji support for beautiful rendering
- ⚡ Asynchronous processing with BullMQ
- 🗄️ MongoDB storage for screenshot metadata
- 🔗 Built-in CDN with public links for easy embedding and sharing
- 🛡️ Rate limiting and security features
- 📱 Responsive design with customizable viewport sizes
- Node.js 16+
- MongoDB (local or Atlas)
- Redis (for BullMQ queue system)
- (Optional) Apple Color Emoji font for best emoji rendering
-
Clone the repository:
git clone https://github.com/yourusername/url2screenshot.git cd url2screenshot -
Install dependencies:
npm install
-
Create a
.envfile in the root directory with the following:# Server PORT=3000 NODE_ENV=development # MongoDB MONGODB_URI=mongodb+srv://your-username:[email protected]/url2screenshot # Redis (for BullMQ) REDIS_HOST=localhost REDIS_PORT=6379 REDIS_PASSWORD= # Screenshot settings SCREENSHOT_QUALITY=90 SCREENSHOT_PATH=public/screenshots MAX_SCREENSHOT_WIDTH=1920 MAX_SCREENSHOT_HEIGHT=1080 # Rate limiting RATE_LIMIT_WINDOW_MS=900000 RATE_LIMIT_MAX=100 -
Create the screenshots directory:
mkdir -p public/screenshots
-
Start the server:
npm start
For development with auto-reload:
npm run dev
- When you request a screenshot, it's added to a queue for processing
- The screenshot is captured using Puppeteer with high quality settings
- Images are optimized for social media with enhanced colors and sharpness
- Screenshots are stored in the file system and their metadata in MongoDB
- A public CDN URL is generated for each screenshot for easy access and sharing
URL2Screenshot provides built-in CDN functionality. Once a screenshot is captured, it is:
- Stored in the
/public/screenshotsdirectory - Accessible via a public URL at
/screenshots/{filename}.png - Optimized for fast loading and sharing
The CDN URLs are relative to your server address. For example, if your server is running at https://your-domain.com, a screenshot with ID 1234abcd.png would be accessible at:
https://your-domain.com/screenshots/1234abcd.png
These public URLs can be used directly in:
- Social media posts
- Website embeds
- Email campaigns
- API responses
POST /api/screenshots
Body parameters:
url(required): The URL to take a screenshot oftype(optional): Type of screenshot - 'full', 'header', or 'section' (default: 'header')selector(required for 'section' type): CSS selector for the element to capturewidth(optional): Viewport width (default: 1920)height(optional): Viewport height (default: 1080)
Example request using cURL:
curl -X POST http://localhost:3000/api/screenshots \
-H "Content-Type: application/json" \
-d '{
"url": "https://github.com",
"type": "header"
}'Example response:
{
"message": "Screenshot request accepted",
"jobId": "123abc",
"screenshotId": "60f1a7b2e6b44a1a7c3d5e7f",
"status": "pending",
"statusUrl": "/api/screenshots/60f1a7b2e6b44a1a7c3d5e7f"
}GET /api/screenshots/:id
Example request:
curl http://localhost:3000/api/screenshots/60f1a7b2e6b44a1a7c3d5e7fExample response:
{
"id": "60f1a7b2e6b44a1a7c3d5e7f",
"url": "https://github.com",
"type": "header",
"status": "completed",
"cdnUrl": "/screenshots/1234abcd.png",
"width": 1920,
"height": 950,
"createdAt": "2023-07-16T12:00:00.000Z",
"updatedAt": "2023-07-16T12:00:30.000Z"
}When the screenshot is completed, you can access it directly via the CDN URL:
http://localhost:3000/screenshots/1234abcd.png
GET /api/screenshots?page=1&limit=10&status=completed
Query parameters:
page(optional): Page number (default: 1)limit(optional): Number of results per page (default: 10)status(optional): Filter by status - 'pending', 'processing', 'completed', or 'failed'
Example request:
curl http://localhost:3000/api/screenshots?status=completedDELETE /api/screenshots/:id
Example:
curl -X DELETE http://localhost:3000/api/screenshots/60f1a7b2e6b44a1a7c3d5e7fThis example demonstrates the full process from requesting a screenshot to embedding it in a webpage:
- Request a screenshot of GitHub's home page
curl -X POST http://localhost:3000/api/screenshots \
-H "Content-Type: application/json" \
-d '{
"url": "https://github.com",
"type": "header",
"width": 1200,
"height": 800
}'- Get the screenshot status until it's completed
curl http://localhost:3000/api/screenshots/60f1a7b2e6b44a1a7c3d5e7f- Once completed, use the CDN URL in your HTML
<div class="feature-image">
<img src="http://localhost:3000/screenshots/1234abcd.png"
alt="GitHub Homepage"
width="1200" />
<p>GitHub's latest features</p>
</div>For the best emoji rendering, install the Apple Color Emoji font on your server. For Linux servers, you can use the font from samuelngs/apple-emoji-linux project.
-
Redis Connection Issues
- Ensure Redis is running on the configured host and port
- Check firewall settings if using a remote Redis instance
-
Puppeteer Installation Problems
- On some Linux distributions, you may need additional dependencies:
apt-get install -y gconf-service libasound2 libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgcc1 libgconf-2-4 libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 libnspr4 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 ca-certificates fonts-liberation libnss3 lsb-release xdg-utils wget
- On some Linux distributions, you may need additional dependencies:
-
Blurry Screenshots
- Try increasing the viewport size and quality settings in your request
- Check if the target site has responsive design issues
Contributions, issues, and feature requests are welcome! Feel free to check the [issues page]
MIT