finsilabs/edge-commerce

Edge Commerce

Overview

Edge computing executes code in the CDN PoP closest to each user, reducing latency from hundreds of milliseconds (round-trip to a central origin) to under 50ms. For e-commerce, this enables geo-routing (redirect UK users to a UK storefront), edge-side personalization (inject user tier into cached pages), instant A/B testing without origin round-trips, and distributed inventory caching via edge KV stores.

When to Use This Skill

• When pages routed through a central origin have high TTFB (>300ms) for international users
• When you need to redirect users to region-specific storefronts or localized product catalogs
• When you want to run A/B tests without adding JavaScript that delays page rendering
• When building a multi-region deployment where each region needs its own origin but shares a single domain

Core Instructions

Step 1: Determine your platform and what edge computing can do for you

| Platform | Edge Capabilities | How to Use Them | |----------|-----------------|----------------| | Shopify | Shopify's CDN (Fastly) already serves stores from global edge locations | Use Shopify Markets for geo-routing and multi-currency without custom edge code; Markets handles currency, language, and domain routing natively | | WooCommerce | Add Cloudflare as your CDN/proxy to get edge capabilities | Cloudflare Workers (free tier: 100k requests/day) adds edge logic; configure in Cloudflare dashboard after adding your domain | | BigCommerce | BigCommerce uses Fastly CDN globally | Use BigCommerce's built-in multi-storefront feature for geo-routing; for custom edge logic add Cloudflare in front | | Custom / Headless | Full control — choose Cloudflare Workers, Vercel Edge Middleware, or Fastly Compute | Build custom geo-routing, A/B testing, and personalization at the edge; see implementation below |

Step 2: Configure geo-routing on your platform

---

Shopify: Use Shopify Markets

1. Go to Settings → Markets in your Shopify admin
2. Click Add market and select the countries/regions for your new market
3. Configure per-market settings:
   • Currency: set the local currency (Shopify handles conversion automatically)
   • Language: assign a translated theme version
   • Domain/subdomain: e.g., uk.yourstore.com routes UK visitors automatically
4. Shopify automatically redirects users to their market based on IP geolocation — no custom code needed
5. For manual market URL overrides: Shopify's cookie-based market selector handles users who want to change their market

---

WooCommerce: Cloudflare Workers geo-routing

1. Add your domain to Cloudflare (free plan is sufficient for geo-routing)
2. Go to Workers & Pages → Create Worker in the Cloudflare dashboard
3. Add a simple geo-redirect rule:

// Cloudflare Worker — deploy via Cloudflare dashboard
export default {
  async fetch(request) {
    const country = request.headers.get('CF-IPCountry') ?? 'US';
    const url = new URL(request.url);

    // Redirect UK users to UK store variant
    if (country === 'GB' && !url.pathname.startsWith('/uk')) {
      return Response.redirect(`https://${url.hostname}/uk${url.pathname}`, 302);
    }

    return fetch(request);
  }
};

4. In Worker settings, add a Route that matches your domain: *yourstore.com/*
5. For currency/language: use a WooCommerce multi-currency plugin (WPML + WooCommerce Multilingual, or Aelia Currency Switcher) that reads the URL path or a cookie set by the Worker

---

Custom / Headless

Vercel Edge Middleware (Next.js) for geo-routing:

// middleware.ts — runs at the edge globally, <5ms
import { NextRequest, NextResponse } from 'next/server';
import { geolocation } from '@vercel/functions';

const REGION_MAP: Record<string, string> = {
  GB: 'uk', DE: 'de', FR: 'fr', CA: 'ca', AU: 'au',
};

export function middleware(request: NextRequest) {
  const { country } = geolocation(request);
  const region = country ? REGION_MAP[country] : null;

  // Redirect root to regional store
  if (region && request.nextUrl.pathname === '/') {
    const url = request.nextUrl.clone();
    url.pathname = `/${region}`;
    return NextResponse.redirect(url, { status: 302 });
  }

  // Pass country to origin for catalog/pricing logic
  const response = NextResponse.next();
  if (country) response.headers.set('x-user-country', country);
  return response;
}

export const config = { matcher: ['/', '/products/:path*', '/collections/:path*'] };

Edge A/B testing (assign variant once, persist in cookie):

// In middleware.ts — no origin round-trip needed
const EXPERIMENTS = [
  { id: 'checkout-cta', buckets: [{ name: 'control', weight: 0.5 }, { name: 'variant-a', weight: 0.5 }] },
];

function assignVariant(buckets: Array<{name: string; weight: number}>) {
  let r = Math.random(), cumulative = 0;
  for (const b of buckets) {
    cumulative += b.weight;
    if (r < cumulative) return b.name;
  }
  return buckets[0].name;
}

// Add to existing middleware function:
for (const exp of EXPERIMENTS) {
  const cookieName = `ab_${exp.id}`;
  let variant = request.cookies.get(cookieName)?.value;
  if (!variant) {
    variant = assignVariant(exp.buckets);
    response.cookies.set(cookieName, variant, { maxAge: 30 * 24 * 3600, httpOnly: true });
  }
  response.headers.set(`x-ab-${exp.id}`, variant); // available in your app for rendering
}

Cloudflare Workers KV for edge inventory caching:

// cloudflare-worker.ts — inventory cached at every Cloudflare PoP globally
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);

    if (url.pathname.startsWith('/api/inventory/')) {
      const productId = url.pathname.replace('/api/inventory/', '');
      const cached = await env.INVENTORY_KV.get(productId, 'json');

      if (cached) {
        return new Response(JSON.stringify(cached), {
          headers: { 'Content-Type': 'application/json', 'X-Edge-Cache': 'HIT' },
        });
      }

      // Cache miss — fetch from origin and store for 60 seconds
      const data = await fetch(`${env.ORIGIN_URL}/api/inventory/${productId}`).then(r => r.json());
      await env.INVENTORY_KV.put(productId, JSON.stringify(data), { expirationTtl: 60 });
      return new Response(JSON.stringify(data), {
        headers: { 'Content-Type': 'application/json', 'X-Edge-Cache': 'MISS' },
      });
    }

    return fetch(request);
  },
};

KV namespace wrangler.toml:

name = "commerce-edge"
main = "src/index.ts"
compatibility_date = "2025-01-01"
[[kv_namespaces]]
binding = "INVENTORY_KV"
id = "your-kv-namespace-id"

Vercel Edge Config for instant feature flags:

// Read feature flags at edge — ~0ms latency (stored in PoP)
import { get } from '@vercel/edge-config';

export async function middleware(request: NextRequest) {
  const maintenanceMode = await get<boolean>('maintenance_mode');
  if (maintenanceMode) {
    return NextResponse.rewrite(new URL('/maintenance', request.url));
  }
  return NextResponse.next();
}

Step 3: Monitor edge performance

Regardless of platform, measure these metrics:

1. TTFB from multiple regions — use tools like WebPageTest.org with test locations in US, EU, and Asia; target under 200ms TTFB from each region
2. CDN cache hit rate — Cloudflare: Analytics → Performance → Cache hit rate (target 90%+); Shopify: check Lighthouse via Online Store → Themes → View report
3. Edge error rate — Cloudflare: Workers → Metrics; Vercel: Deployments → Functions tab
4. Geographic latency breakdown — Cloudflare Analytics shows latency by country; use this to identify regions that would benefit from an additional origin

Best Practices

• Use edge for routing decisions, not business logic — edge functions are best for fast decisions based on request metadata (country, cookie, header); complex business logic (pricing, inventory) belongs at the origin with a result cached at the edge
• Keep edge functions fast — Cloudflare Workers have 10ms CPU limit on free plan, 30ms on paid; avoid synchronous external API calls from edge middleware on the critical path
• Pre-populate KV before product launches — Workers KV has eventual consistency; pre-populate edge inventory cache before a flash sale via the KV REST API
• Test geo-routing from multiple locations — use a VPN to verify redirect logic; production geo-routing mistakes affect all users in a region

Common Pitfalls

| Problem | Solution | |---------|----------| | Edge making external API calls on every request | Cache external data in Edge Config or Workers KV; never make synchronous third-party API calls from edge middleware on the critical path | | Personalized responses cached without Vary header | Set Vary: Cookie or a custom header that differentiates personalized responses; without it, one user's content can be served to others | | Workers KV stale inventory causing oversells | Use edge KV only for displaying inventory status; always validate against the authoritative inventory source at checkout time | | A/B variant flickering on first load | Set the variant cookie in the response before the page renders; on first visit, set the cookie and redirect to ensure consistent rendering |

Related Skills

• @ecommerce-caching
• @flash-sale-scaling
• @monitoring-alerting-commerce
• @image-optimization-cdn