lity.

Step 1: Edge Detection Layer

CloudFront Functions execute at regional edge locations with strict runtime constraints: 10KB maximum size, synchronous execution only, and no network I/O. These constraints are intentional. They force lightweight logic that cannot block the request pipeline.

// edge-crawler-router.ts
// CloudFront Functions use standard JavaScript, not TypeScript.
// This example shows the compiled logic structure.

interface CloudFrontRequest {
  uri: string;
  headers: Record<string, { value: string }>;
  querystring: Record<string, { value: string }>;
}

interface CloudFrontResult {
  request: CloudFrontRequest;
}

const CRAWLER_SIGNATURES = [
  'twitterbot',
  'facebookexternalhit',
  'slackbot',
  'linkedinbot',
  'discordbot',
  'whatsapp',
  'pinterest',
  'embedly'
];

export function handler(event: { request: CloudFrontRequest }): CloudFrontResult {
  const request = event.request;
  const userAgent = request.headers['user-agent']?.value?.toLowerCase() || '';

  const isCrawler = CRAWLER_SIGNATURES.some(signature => 
    userAgent.includes(signature)
  );

  if (isCrawler) {
    // Rewrite URI to route through metadata resolver
    request.uri = `/meta-render${request.uri}`;
    // Preserve original path for downstream parsing
    request.headers['x-original-uri'] = { value: request.uri };
  }

  return { request };
}

Architecture Rationale: The edge function performs only pattern matching and URI rewriting. It never fetches data, never renders HTML, and never exceeds the 10KB boundary. By rewriting the URI, we create a clear routing boundary that the origin or Lambda@Edge can intercept. The x-original-uri header ensures downstream components can parse the intended page context without relying on the rewritten path.

Step 2: Metadata Resolution Layer

The resolver operates as a standard AWS Lambda function. Unlike CloudFront Functions, Lambda supports asynchronous operations, external API calls, database queries, and larger payload sizes. This is where we fetch page-specific metadata.

// meta-resolver.ts
import { APIGatewayProxyEvent, APIGatewayProxyResult } from 'aws-lambda';

interface PageMetadata {
  title: string;
  description: string;
  imageUrl: string;
  imageWidth: number;
  imageHeight: number;
  url: string;
  type: 'website' | 'article' | 'profile';
  siteName: string;
}

const METADATA_STORE: Record<string, PageMetadata> = {
  '/products/analytics-dashboard': {
    title: 'Real-Time Analytics Dashboard',
    description: 'Monitor KPIs, track user behavior, and generate custom reports.',
    imageUrl: 'https://cdn.example.com/og/analytics-preview.png',
    imageWidth: 1200,
    imageHeight: 630,
    url: 'https://app.example.com/products/analytics-dashboard',
    type: 'website',
    siteName: 'DataFlow SaaS'
  },
  '/blog/edge-rendering-patterns': {
    title: 'Edge-First Meta Rendering for SPAs',
    description: 'How to deliver accurate social previews without full SSR.',
    imageUrl: 'https://cdn.example.com/og/edge-rendering.png',
    imageWidth: 1200,
    imageHeight: 630,
    url: 'https://app.example.com/blog/edge-rendering-patterns',
    type: 'article',
    siteName: 'DataFlow Engineering'
  }
};

export async function handler(event: APIGatewayProxyEvent): Promise<APIGatewayProxyResult> {
  const originalPath = event.headers['x-original-uri'] || event.path;
  const normalizedPath = originalPath.split('?')[0].toLowerCase();
  
  const metadata = METADATA_STORE[normalizedPath] || {
    title: 'DataFlow Platform',
    description: 'Enterprise analytics and workflow automation.',
    imageUrl: 'https://cdn.example.com/og/default.png',
    imageWidth: 1200,
    imageHeight: 630,
    url: `https://app.example.com${normalizedPath}`,
    type: 'website',
    siteName: 'DataFlow SaaS'
  };

  return {
    statusCode: 200,
    headers: {
      'Content-Type': 'text/html; charset=utf-8',
      'Cache-Control': 'public, max-age=86400, stale-while-revalidate=3600',
      'X-Content-Type-Options': 'nosniff'
    },
    body: generateMetaHtml(metadata)
  };
}

function generateMetaHtml(meta: PageMetadata): string {
  return `<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>${escapeHtml(meta.title)}</title>
  <meta property="og:title" content="${escapeHtml(meta.title)}" />
  <meta property="og:description" content="${escapeHtml(meta.description)}" />
  <meta property="og:image" content="${meta.imageUrl}" />
  <meta property="og:image:width" content="${meta.imageWidth}" />
  <meta property="og:image:height" content="${meta.imageHeight}" />
  <meta property="og:url" content="${meta.url}" />
  <meta property="og:type" content="${meta.type}" />
  <meta property="og:site_name" content="${escapeHtml(meta.siteName)}" />
  <meta name="twitter:card" content="summary_large_image" />
  <meta name="twitter:title" content="${escapeHtml(meta.title)}" />
  <meta name="twitter:description" content="${escapeHtml(meta.description)}" />
  <meta name="twitter:image" content="${meta.imageUrl}" />
</head>
<body></body>
</html>`;
}

function escapeHtml(text: string): string {
  return text
    .replace(/&/g, '&amp;')
    .replace(/</g, '&lt;')
    .replace(/>/g, '&gt;')
    .replace(/"/g, '&quot;')
    .replace(/'/g, '&#039;');
}

Architecture Rationale: The resolver separates data fetching from HTML generation. In production, METADATA_STORE would be replaced with a DynamoDB query, S3 object fetch, or CMS API call. The function returns a minimal HTML document containing only the <head> section. Crawlers parse this instantly. The Cache-Control header ensures crawlers cache the response, reducing repeated Lambda invocations. The escapeHtml utility prevents injection attacks when metadata contains user-generated content.

Step 3: Routing & Deployment Configuration

The CloudFront distribution requires two behavioral rules:

1. Default behavior: Serves the SPA bundle to all non-crawler requests.
2. Metadata behavior: Routes /meta-render/* requests to the Lambda function via Lambda@Edge or API Gateway integration.

CloudFront Functions attach to the viewer-request event. They execute before cache key evaluation, ensuring crawler detection happens early in the request lifecycle. The rewritten URI triggers the second behavior, which routes to the metadata resolver. Human traffic bypasses this entirely, maintaining optimal SPA performance.

Pitfall Guide

1. Overloading the Edge Function

Explanation: CloudFront Functions enforce a 10KB size limit and prohibit asynchronous operations. Attempting to fetch metadata, render HTML, or perform complex string manipulation at the edge causes deployment failures or runtime timeouts. Fix: Restrict edge logic to header inspection, URI rewriting, and simple conditional routing. Delegate all data retrieval and HTML generation to Lambda or origin servers.

2. Ignoring Secondary Crawlers

Explanation: Focusing only on Twitter and Facebook misses Slack, Discord, LinkedIn, WhatsApp, and Pinterest. Each platform uses distinct User-Agent strings and OGP parsing rules. Missing these results in broken previews across collaboration tools. Fix: Maintain an allowlist of crawler signatures. Update it quarterly as platforms change their bot identifiers. Test previews using each platform's official debugger before deployment.

3. Omitting Image Dimensions

Explanation: OGP specifications require explicit og:image:width and og:image:height tags. Without them, crawlers must fetch the image to determine dimensions, adding latency and sometimes causing preview failures. Fix: Always include width and height metadata alongside the image URL. Use standardized dimensions (1200x630 for large cards, 1024x1024 for square previews) and verify assets match declared sizes.

4. Cache Poisoning & Stale Metadata

Explanation: Aggressive caching without proper invalidation causes crawlers to serve outdated previews after content updates. Conversely, no caching triggers excessive Lambda invocations and increased costs. Fix: Implement max-age for crawler responses with stale-while-revalidate for background refresh. Use CloudFront cache keys that include the request path. Invalidate metadata caches when underlying content changes via Lambda or CI/CD hooks.

5. User-Agent Spoofing & False Positives

Explanation: Relying solely on User-Agent strings can misidentify legitimate browsers or miss crawlers that spoof headers. Some enterprise proxies modify User-Agent values, causing routing failures. Fix: Combine User-Agent inspection with request pattern analysis. Look for known crawler IP ranges, missing browser-specific headers (like sec-ch-ua), and predictable request frequencies. Use a fallback mechanism that serves metadata on ambiguous requests.

6. Missing Content-Type Headers

Explanation: Crawlers reject responses without explicit Content-Type: text/html headers. Lambda functions returning JSON or missing headers cause preview generation to fail silently. Fix: Always set Content-Type: text/html; charset=utf-8 in metadata responses. Validate headers using curl or HTTPie before deploying to production.

7. Path Parameter Extraction Errors

Explanation: SPA routes often contain dynamic segments, query parameters, or hash fragments. Incorrect parsing leads to metadata mismatches or 404 responses for valid pages. Fix: Normalize paths by stripping query strings and trailing slashes before metadata lookup. Use a mapping layer that translates client-side routes to server-side metadata keys. Implement fallback metadata for unmapped paths.

Production Bundle

Action Checklist

• Audit existing SPA metadata: Run Twitter Card Validator, Facebook Sharing Debugger, and LinkedIn Post Inspector against key URLs.
• Define metadata schema: Standardize title, description, image, URL, type, and dimensions across all pages.
• Implement edge detection: Deploy CloudFront Function with crawler allowlist and URI rewriting logic.
• Build metadata resolver: Create Lambda function with async data fetching, HTML assembly, and proper caching headers.
• Configure CloudFront behaviors: Set default SPA routing and metadata resolver routing with correct cache policies.
• Add cache invalidation: Implement CI/CD hooks or webhook listeners to purge metadata caches on content updates.
• Validate end-to-end: Test with all target platforms, verify image dimensions, and monitor Lambda invocation costs.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Existing SPA on AWS, dynamic metadata	Edge Detection + Lambda	Preserves SPA, leverages existing CDN, sub-50ms latency	Low (Lambda invocations + CloudFront data transfer)
Static marketing site, infrequent updates	Pre-rendered HTML export	Zero runtime overhead, simplest deployment	None (static hosting)
Complex app with real-time data, high traffic	Full SSR Framework	Native metadata support, unified rendering pipeline	High (server instances, scaling, maintenance)
Multi-framework team, limited AWS budget	Third-party Prerender Service	Vendor-managed rendering, no infra changes	Medium-High (monthly SaaS fees, per-request pricing)
Internal tools, no social sharing	Client-Side SPA	No metadata requirements, minimal complexity	None

Configuration Template

# cloudfront-behaviors.yaml
# Attach to existing CloudFront distribution

Behaviors:
  - PathPattern: '/meta-render/*'
    TargetOriginId: 'MetadataResolver'
    ViewerProtocolPolicy: 'https-only'
    CachePolicy: 'CachingOptimized'
    OriginRequestPolicy: 'MetadataResolverPolicy'
    FunctionAssociations:
      - EventType: 'viewer-request'
        FunctionARN: 'arn:aws:cloudfront::123456789012:function/EdgeCrawlerRouter'
    LambdaFunctionAssociations:
      - EventType: 'origin-request'
        LambdaFunctionARN: 'arn:aws:lambda:us-east-1:123456789012:function:MetaResolverProd'

  - PathPattern: '/*'
    TargetOriginId: 'SPABundle'
    ViewerProtocolPolicy: 'https-only'
    CachePolicy: 'SPACachingPolicy'
    OriginRequestPolicy: 'SPARoutingPolicy'
    FunctionAssociations: []
    LambdaFunctionAssociations: []

CachePolicies:
  CachingOptimized:
    MinTTL: 86400
    MaxTTL: 604800
    DefaultTTL: 86400
    ParametersInCacheKeyAndForwardedToOrigin:
      Headers:
        Items: ['x-original-uri']
        Enable: true
      QueryStrings:
        Enable: false

Quick Start Guide

1. Create the metadata resolver: Deploy the Lambda function with your metadata store or API integration. Ensure it returns Content-Type: text/html and includes OGP tags.
2. Attach the edge router: Upload the CloudFront Function to your AWS account. Associate it with the viewer-request event on your distribution.
3. Configure routing behaviors: Add a /meta-render/* behavior pointing to the Lambda function. Keep the default /* behavior for your SPA bundle.
4. Test with platform debuggers: Submit URLs to Twitter Card Validator, Facebook Sharing Debugger, and LinkedIn Post Inspector. Verify previews render correctly.
5. Monitor and iterate: Track Lambda invocations, cache hit ratios, and crawler response times. Adjust TTL values and crawler allowlists based on traffic patterns.