Skip to main content
Contentstack MCP profile hub is in general availability!

Personalize with server-side rendering at the edge

•
4 min read

Personalization usually breaks one of three things: page speed, caching or SEO. Run it in the browser and you get a flash of default content before the variant appears. Run it on the origin for every request and you lose your CDN cache. Personalize avoids both if you split the work: an edge function decides which variants a visitor gets, and the origin renders those variants as if they were normal content.

This guide builds that setup on Next.js and Contentstack Launch. The same split works on Vercel, Netlify, Cloudflare Workers and other edge runtimes, and the guide calls out where they differ.

What you'll learn

  • How Personalize turns a visitor into a set of variant aliases

  • How to run the Personalize Edge SDK in a Launch Edge Function

  • How to fetch entry variants with the Delivery SDK and cache the result per variant

  • How to track impressions and conversions from the browser

  • How priority decides what renders when experiences overlap

How the pieces fit

Every page request goes through the same path. The edge function asks the Personalize Edge API for the visitor's manifest, writes the active variants into a query parameter, and forwards the request. The CDN treats that rewritten URL as the cache key. On a miss, the origin reads the parameter, asks the Content Delivery API (CDA) for the matching entry variants and renders HTML.

DiagramMermaid

The origin never sees a user ID or an audience. It only sees a_0,b_1, which is why the response is safe to cache and share with every visitor who resolved to the same variants.

The chapters

Each chapter covers one part of the flow:

  1. How Personalize resolves variants explains projects, attributes, audiences, experiences and how a variant alias maps to a CMS entry variant. Read it first if Personalize is new to you.

  2. Set up the Edge SDK builds the Launch Edge Function: initialize the SDK with the request, rewrite the URL, and write the user and manifest cookies.

  3. Fetch entry variants reads the parameter on the origin, passes aliases to variants(), and sets cache headers that work when the response varies per variant.

  4. Track impressions and conversions wires up the browser SDK so A/B tests and analytics have data.

  5. Layered and prioritized experiences covers several experiences on one page, priority, and when to pick segmented versus A/B.

Production note: The code uses the instance API of @contentstack/personalize-edge-sdk (version 1.0.9 and later), where Personalize.init() returns an SDK instance. The older global methods such as Personalize.getVariantAliases() still exist but are deprecated, and they share state across requests at the edge.

If you are still deciding whether edge rendering is right for your project, read Client, static, server or edge? Choosing a Personalize architecture first. For how Personalize relates to the CMS and Lytics, see Understanding how Contentstack CMS, Personalize and Lytics work together.

Key takeaways

  • The edge function decides, the origin renders, the browser reports.

  • Variants travel as a query parameter (personalize_variants), so the CDN caches one page per variant combination.

  • The origin needs no Personalize credentials and no user context.

  • On Launch, use an Edge Function in functions/[proxy].edge.js, not Next.js middleware.

  • Use the SDK instance returned by Personalize.init(), not the deprecated global methods.

Frequently asked questions

  • Why resolve variants at the edge instead of in the browser?

    The page arrives already personalized, so there is no flicker, search engines see real HTML, and the CDN can cache one copy per variant combination.

  • Does my origin need the Personalize SDK?

    Only for one static helper that turns the variant query parameter into aliases. The origin never calls the Personalize Edge API.

  • Can I use Next.js middleware on Launch for this?

    No. On Launch, Next.js middleware runs on the server, not at the edge, so use a Launch Edge Function instead.

  • Where do impressions and conversions get tracked?

    In the browser. The edge function picks variants; the browser SDK reports what the visitor saw and did.