Glance Utils

A Node.js utility service that provides Open Graph image generation and website thumbnail extraction capabilities. Built with Express.js and optimized for deployment on Vercel.

Features

• Open Graph Image Generation: Dynamically generate social media preview images with custom user data
• Website Thumbnail Extraction: Extract Open Graph and Twitter Card images from any URL
• Intelligent Caching: Multi-layer caching system with memory and file-based storage
• Device Detection: Built-in user agent parsing for responsive behavior
• SVG to PNG Conversion: Uses Satori and Resvg for high-quality image rendering

API Endpoints

Generate Open Graph Image

GET /og?name={name}&username={username}&bio={bio}&photo={photo_url}

Generates a custom Open Graph image with user information.

Parameters:

• name - User's display name
• username - User's username/handle
• bio - User's bio/description
• photo - Profile photo URL (optional, defaults to placeholder)

Example:

https://your-domain.com/og?name=John%20Doe&username=johndoe&bio=Software%20Engineer&photo=https://example.com/photo.jpg

Response: PNG image (1200x630px)

Extract Website Thumbnail

GET /thumbnail?url={website_url}

Extracts the main image from a website's Open Graph or Twitter Card meta tags.

Parameters:

• url - Target website URL (automatically adds https:// if missing)

Example:

https://your-domain.com/thumbnail?url=github.com

Response:

{
  "url": "github.com",
  "image": "https://github.githubassets.com/images/modules/site/social-cards/campaign-social.png"
}

Cache Management

GET /cache/stats

Returns cache performance statistics.

DELETE /cache

Clears all cached data (useful for development).

Installation

1. Clone the repository:

git clone <repository-url>
cd glance-utils

2. Install dependencies:

npm install

3. Create environment file (optional):

cp .env.example .env

4. Start the development server:

npm run dev

The server will start on port 4000 (or the port specified in the PORT environment variable).

Deployment

Vercel (Recommended)

This project is optimized for Vercel deployment with the included vercel.json configuration.

1. Install Vercel CLI:

npm i -g vercel

2. Deploy:

vercel

Other Platforms

The service can be deployed to any Node.js hosting platform. Make sure to:

• Set the NODE_ENV=production environment variable
• Ensure the platform supports Node.js 16+
• Configure any necessary build commands

Configuration

Environment Variables

• PORT - Server port (default: 4000)
• NODE_ENV - Environment (development/production)

Cache Configuration

The cache system can be configured in the CacheManager initialization:

const cache = new CacheManager({
  ttl: 3600,              // Cache TTL in seconds (1 hour)
  enableFileCache: true,   // Enable persistent file cache
  maxFileCacheSize: 200,   // Maximum number of cached files
});

Architecture

Tech Stack

• Runtime: Node.js
• Framework: Express.js
• Image Generation: Satori + Resvg
• HTML Parsing: Cheerio
• Caching: node-cache + file system
• Font Loading: Inter font family from CDN

Caching Strategy

The service implements a two-tier caching system:

1. Memory Cache: Fast in-memory storage using node-cache
2. File Cache: Persistent storage for longer-term caching
3. Automatic Cleanup: Removes old cache files when limits are exceeded

Image Generation Process

1. Parse query parameters
2. Check cache for existing image
3. Generate HTML template with user data
4. Convert HTML to SVG using Satori
5. Convert SVG to PNG using Resvg
6. Cache the result
7. Return PNG buffer

Development

Project Structure

glance-utils/
├── index.js          # Main server file
├── cache.js          # Cache management system
├── package.json      # Dependencies and scripts
├── vercel.json       # Vercel deployment config
├── tsconfig.json     # TypeScript configuration
└── .cache/           # File cache directory

Adding Features

The service is designed to be easily extensible. Key areas for enhancement:

• Templates: Modify the HTML template in the /og endpoint
• Styling: Update the SVG styling and layout
• Caching: Adjust cache strategies in cache.js
• Endpoints: Add new utility endpoints following the existing pattern

Testing

Test the service locally:

# Start development server
npm run dev

# Test OG image generation
curl "http://localhost:4000/og?name=Test&username=test&bio=Testing"

# Test thumbnail extraction
curl "http://localhost:4000/thumbnail?url=github.com"

# Check cache stats
curl "http://localhost:4000/cache/stats"

Performance

• Caching: Reduces image generation time by 90%+ for repeated requests
• Font Preloading: Inter fonts are loaded once and cached
• Optimized Rendering: Satori provides fast HTML-to-SVG conversion
• Memory Management: Automatic cache cleanup prevents memory leaks

License

ISC

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

Support

For issues and questions, please create an issue in the repository or contact the maintainers.