Kōhī Roasters // Headless E-Commerce at the Edge

The standard approach to e-commerce is broken. Most modern digital storefronts rely on massive, monolithic platforms (like Shopify or Magento) paired with heavy client-side JavaScript frameworks. The result is often a bloated DOM, severe hydration delays, and a Largest Contentful Paint (LCP) that easily exceeds 3 seconds.

For Kōhī Roasters, a premium single-origin coffee brand based in Tokyo, a 3-second load time was unacceptable. The brand demanded a luxury, editorial-grade visual experience, but it needed to perform like a static document.

I architected Kōhī as a Headless E-Commerce Edge Application. By completely decoupling the frontend from the payment processor, we achieved sub-second global load times without sacrificing transactional security.

https://kohi.com

01. The Frontend: Chasing the 0.4s LCP

To guarantee instantaneous delivery, I abandoned Server-Side Rendering (SSR) entirely. While SSR is powerful, it still incurs a Time to First Byte (TTFB) penalty as the server generates the HTML on request.

Instead, I configured Next.js for a pure static HTML export (output: 'export') hosted directly on Cloudflare's Edge CDN.

Eliminating JS-Heavy Animation Libraries

A common mistake in "premium" web design is relying on libraries like Framer Motion or GSAP to handle scroll effects, which blocks the main thread during initialization. For Kōhī's immersive roasting parallax section, I utilized CSS-only sticky positioning and mix-blend-mode: difference for the navigation bar.

Zero-JavaScript Parallax

By nesting a sticky container inside a 150vh wrapper, the background image locks into place while the typography naturally scrolls over it. The navigation bar dynamically inverts its color using mix-blend-mode. Total JavaScript execution cost: 0ms.

0 KBAnimation Bundle Size

02. State Management: The Hydration Trap

Because the site is a static export, there is no server session to store the user's shopping cart. The cart state must be managed strictly on the client using localStorage.

However, injecting localStorage directly into React state during the initial render causes a severe Hydration Mismatch. The server builds the static HTML with an empty cart (0), but the browser immediately finds items in localStorage and tries to render (2). React violently catches the mismatch and discards the UI tree.

To solve this, I architected a custom Context Provider that strictly isolates the local storage retrieval until after the component has mounted to the DOM.

export function CartProvider({ children }: { children: ReactNode }) {
  const [cart, setCart] = useState<CartItem[]>([]);
  const [isMounted, setIsMounted] = useState(false);

  // Safely hydrate from localStorage ONLY on the client
  useEffect(() => {
    setIsMounted(true);
    const saved = localStorage.getItem('kohi_cart');
    if (saved) setCart(JSON.parse(saved));
  }, []);

  // Sync state back to localStorage
  useEffect(() => {
    if (isMounted) {
      localStorage.setItem('kohi_cart', JSON.stringify(cart));
    }
  }, [cart, isMounted]);

  // ...

03. Secure Transactions at the Edge

Herein lies the ultimate challenge of static e-commerce: How do you securely process a payment without a backend?

Historically, developers used Stripe's Client-Only Integration (redirectToCheckout), which passed product IDs directly from the browser. However, in modern iterations of the @stripe/stripe-js SDK (v8.x+), Stripe completely deprecated this method due to a critical security vulnerability: malicious users could intercept the network request and alter the item prices before checkout.

Today, generating a secure Stripe Checkout Session requires a backend wielding a hidden Secret Key.

To maintain our static frontend architecture, I built a serverless interceptor using Cloudflare Pages Functions.

export const onRequestPost: PagesFunction<Env> = async (context) => {
  const { request, env } = context;
  const { cart } = (await request.json()) as RequestBody;

  // Build form-urlencoded payload for Stripe's REST API
  const body = new URLSearchParams();
  body.append("mode", "payment");
  body.append("success_url", `${new URL(request.url).origin}/?success=true`);

  // Map local cart quantities to secure, pre-defined Stripe Price IDs
  cart.forEach((item, index) => {
    body.append(`line_items[${index}][price]`, item.priceId);
    body.append(`line_items[${index}][quantity]`, item.quantity.toString());
  });

  // Execute native fetch to Stripe using secure Edge environment variables
  const stripeResponse = await fetch("https://api.stripe.com/v1/checkout/sessions", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${env.STRIPE_SECRET_KEY}`,
      "Content-Type": "application/x-www-form-urlencoded",
    },
    body: body.toString(),
  });

  const session = await stripeResponse.json();
  return new Response(JSON.stringify({ url: session.url }), { status: 200 });
};

When a user clicks "Checkout", the static React app POSTs the cart payload to the Cloudflare Edge network. The worker securely negotiates with Stripe's REST API using native fetch(), completely eliminating the need for the bulky Stripe Node.js SDK.

Cloudflare Pages Functions handle the checkout handshake with a median CPU execution time of just 2.54ms (P99: 3.87ms), delivering a complete end-to-end payment redirection in 439ms.

The Outcome

By treating the browser as the operating system and leveraging Cloudflare's edge network for secure checkout mutations, Kōhī Roasters achieves full e-commerce functionality without the operational overhead or latency penalties of traditional server-side CMS monoliths.

The resulting architecture delivers sub-150ms rendering, zero layout shifts, and instant client-side cart persistence, proving that high-end digital storefronts can be both visually rich and blazingly fast.