Microlink

Turn any website into structured data with rich metadata extraction, screenshots, PDFs, and performance insights.

package: @deepagent/microlink
exports: class MicrolinkClient, MicrolinkError
env vars: MICROLINK_API_KEY (optional for free tier)
source
microlink api docs

Install

npm install @deepagent/microlink

npm install @deepagent/microlink

yarn add @deepagent/microlink

yarn add @deepagent/microlink

pnpm add @deepagent/microlink

pnpm add @deepagent/microlink

Usage

Basic Metadata Extraction

import { MicrolinkClient } from '@deepagent/microlink'

const microlink = new MicrolinkClient()

const metadata = await microlink.getMetadata('https://github.com/microlinkhq')

console.log({
  title: metadata.title,
  description: metadata.description,
  image: metadata.image?.url,
  logo: metadata.logo?.url,
  publisher: metadata.publisher
})

With API Key (Pro Plan)

const microlink = new MicrolinkClient({
  apiKey: process.env.MICROLINK_API_KEY,
  timeout: 15000
})

const metadata = await microlink.getMetadata('https://example.com', {
  waitUntil: 'networkidle0',
  headers: {
    'User-Agent': 'Custom Bot/1.0'
  }
})

Screenshot Generation

const result = await microlink.getScreenshot('https://example.com', {
  viewport: { width: 1200, height: 800 },
  colorScheme: 'dark',
  waitUntil: 'networkidle0'
})

console.log('Screenshot URL:', result.screenshot?.url)

PDF Generation

const result = await microlink.getPdf('https://example.com', {
  waitUntil: 'load',
  device: 'desktop'
})

console.log('PDF URL:', result.pdf?.url)

Performance Insights

const result = await microlink.getInsights('https://example.com')

console.log('Performance metrics:', result.insights)

Batch Processing

const urls = [
  'https://github.com/microlinkhq',
  'https://vercel.com',
  'https://nextjs.org'
]

const results = await microlink.batchGetMetadata(urls)

results.forEach(result => {
  if (result.success) {
    console.log(`✓ ${result.data.title}`)
  } else {
    console.error(`✗ ${result.url}: ${result.error.message}`)
  }
})

API Reference

MicrolinkClient

Constructor

new MicrolinkClient(config?: MicrolinkConfig)

Config Options:

apiKey?: string - Microlink API key (optional for free tier)
baseUrl?: string - API base URL (default: 'https://api.microlink.io')
timeout?: number - Request timeout in milliseconds (default: 30000)
defaultOptions?: Partial<MicrolinkOptions> - Default options for all requests

Methods

`getMetadata(url, options?)`

Extract basic metadata from a website.

const metadata = await microlink.getMetadata('https://example.com', {
  waitUntil: 'networkidle0',
  device: 'iPhone'
})

Options:

waitUntil?: 'load' | 'domcontentloaded' | 'networkidle0' | 'networkidle2'
device?: string - Device to emulate
viewport?: { width: number; height: number }
headers?: Record<string, string>
prerender?: boolean
colorScheme?: 'light' | 'dark'

`getScreenshot(url, options?)`

Capture website screenshot along with metadata.

const result = await microlink.getScreenshot('https://example.com', {
  viewport: { width: 1920, height: 1080 },
  waitUntil: 'networkidle0'
})

`getPdf(url, options?)`

Generate PDF of webpage along with metadata.

const result = await microlink.getPdf('https://example.com', {
  waitUntil: 'load',
  device: 'desktop'
})

`getInsights(url, options?)`

Get performance insights along with metadata.

const result = await microlink.getInsights('https://example.com')

`batchGetMetadata(urls, options?)`

Process multiple URLs in parallel.

const results = await microlink.batchGetMetadata(urls)

Response Types

MicrolinkData

interface MicrolinkData {
  title: string | null
  description: string | null
  lang: string | null
  author: string | null
  publisher: string | null
  image?: MicrolinkMedia
  date: string | null
  url: string
  logo?: MicrolinkMedia
  // Additional fields based on options:
  screenshot?: MicrolinkMedia  // with screenshot: true
  pdf?: MicrolinkMedia        // with pdf: true
  insights?: any              // with insights: true
}

MicrolinkMedia

interface MicrolinkMedia {
  url: string
  type: string
  size: number
  height: number
  width: number
  size_pretty: string
}

Advanced Usage

Custom Configuration

const microlink = new MicrolinkClient({
  apiKey: process.env.MICROLINK_API_KEY,
  timeout: 20000,
  defaultOptions: {
    waitUntil: 'networkidle0',
    viewport: { width: 1920, height: 1080 }
  }
})

Error Handling

import { MicrolinkError } from '@deepagent/microlink'

try {
  const metadata = await microlink.getMetadata('https://example.com')
} catch (error) {
  if (error instanceof MicrolinkError) {
    console.error('Microlink API Error:', {
      message: error.message,
      statusCode: error.statusCode,
      response: error.response
    })
  }
}

Real-world Examples

Link Preview Component

async function generateLinkPreview(url: string) {
  const microlink = new MicrolinkClient()
  
  try {
    const metadata = await microlink.getMetadata(url)
    
    return {
      title: metadata.title || 'Untitled',
      description: metadata.description || '',
      image: metadata.image?.url,
      favicon: metadata.logo?.url,
      url: metadata.url
    }
  } catch (error) {
    console.error('Failed to generate preview:', error)
    return null
  }
}

async function generateSocialCard(url: string) {
  const microlink = new MicrolinkClient()
  
  const metadata = await microlink.getScreenshot(url, {
    viewport: { width: 1200, height: 630 }, // Twitter card dimensions
    waitUntil: 'networkidle0'
  })
  
  return {
    title: metadata.title,
    description: metadata.description,
    image: metadata.screenshot?.url,
    url: metadata.url
  }
}

Competitor Analysis

async function analyzeCompetitors(urls: string[]) {
  const microlink = new MicrolinkClient({
    apiKey: process.env.MICROLINK_API_KEY
  })
  
  const results = await microlink.batchGetMetadata(urls, {
    insights: true,
    screenshot: true
  })
  
  return results
    .filter(result => result.success)
    .map(result => ({
      url: result.data.url,
      title: result.data.title,
      description: result.data.description,
      screenshot: result.data.screenshot?.url,
      insights: result.data.insights
    }))
}

Pricing & Limits

Free Tier

50 requests per day
Basic metadata extraction
No API key required
Rate limited

Pro Plans

Higher rate limits (14K - 560K requests)
Advanced features (screenshots, PDFs, insights)
Custom headers and TTL
API key required

Get your API key at microlink.io

Features

🎯 Website Metadata Extraction - Get title, description, images, and more
📸 Screenshot Generation - Capture website screenshots with custom options
📄 PDF Generation - Convert webpages to PDF documents
📊 Performance Insights - Get website performance metrics
🔄 Batch Processing - Process multiple URLs simultaneously
🛡️ Type Safety - Full TypeScript support with comprehensive types
⚡ Production Ready - Robust error handling and validation
🆓 Free Tier Support - Works with Microlink's free plan

Use Cases

Link Previews - Generate rich link previews for social media
SEO Analysis - Extract metadata for SEO optimization
Content Curation - Automatically gather website information
Social Media Automation - Create social media cards and posts
Website Monitoring - Track changes in website metadata
Research Tools - Batch analyze competitor websites
Documentation - Generate website snapshots and PDFs

Error Handling

The package includes comprehensive error handling:

URL Validation - Ensures valid URLs before making requests
Response Validation - Validates API responses with flexible schema
Network Errors - Handles timeout and connection issues
API Errors - Properly surfaces Microlink API error messages
Type Safety - Full TypeScript support prevents runtime errors

On this page