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

Client, static, server or edge? Choosing a Personalize architecture

•
7 min read

Where you resolve variants matters more than any other Personalize decision you make. It decides whether visitors see a flash of the wrong headline, whether your CDN can cache anything, and what search engines index. The SDK calls are almost the same in every setup. The architecture around them is where projects go right or wrong.

The short version

There are four ways to wire up Contentstack Personalize, and I recommend them in this order:

  1. SSR at the edge. An edge function resolves variants, the origin renders, the CDN caches per variant. Use it unless you cannot run code in front of your origin.

  2. SSR without an edge. The origin resolves variants on every request. No flicker, but you build your own caching.

  3. CSR on top of SSG. Static pages from the CDN, personalization in the browser afterwards. Fast first paint, visible swap.

  4. Pure CSR. Everything in the browser. Only when there is no server in the picture at all.

The rest of this post explains why.

What actually differs

Every Personalize setup does the same three things: get a manifest from the Personalize Edge API, turn it into variant aliases like cs_personalize_a_0, and pass those aliases to the Content Delivery API (CDA) with variants(). The CDA returns the base entry merged with the variant overrides.

The only question is where those steps run and when the HTML is produced. Move them later in the request and you get flicker. Move them earlier and you need infrastructure. Put them in the wrong layer and you lose caching.

Client-side rendering

The browser loads the page with base content, initializes the SDK, fetches the manifest, fetches entry variants from the CDA and re-renders.

It is the easiest to add to an existing single-page app. A few SDK calls and you are personalizing. That is where the good news ends.

The visitor sees base content, then the swap. Skeleton loaders and opacity: 0 on personalized sections make it less ugly, but the two-phase render stays. Nothing personalized can be cached, because every variant fetch happens per visitor from the browser. Search engines see base content only. And every page load waits for two round trips before the right content appears.

There is also a Lytics catch. The cs-lytics-audiences cookie is written by the Lytics tag in the browser. If the Personalize SDK initializes before the tag fires, Lytics audiences do not evaluate on that load.

I would only pick pure CSR when the app is a single-page app with no server rendering path and adding one is blocked, not just inconvenient.

Static generation with client-side personalization

This is CSR with a better starting point. The build produces static HTML with base content, the CDN serves it fast, and the browser applies personalization on top.

You keep fast, cacheable static pages and an origin that is only a build target. For sites already on static generation, it is the cheapest way to start.

The flicker is still there. The static page is visible before the variant arrives, which is fine for a sidebar recommendation and bad for a hero banner. Search engines index base content, not variants. And base content changes need a rebuild, while personalization decisions update in real time, so the two halves of the page change on different schedules.

Pick this when time to first byte is your top concern, the site is already static, and the personalized parts sit below the fold.

Server-side rendering at the origin

The origin calls the Personalize Edge API for every request, gets the manifest, fetches entry variants and renders HTML. No flicker, and search engines get real HTML.

The cost is caching. A standard CDN cache keyed on the URL would serve one visitor's variant to everyone. So you either skip the cache and let every request hit your origin, or build a cache layer that includes variants in the key, with TTLs, invalidation and monitoring for the number of combinations. At any real traffic level, the origin becomes the bottleneck.

The origin does not need to be JavaScript. The Edge SDK wraps an HTTP API, so a Java, .NET or Go server can call the manifest endpoint and build the aliases itself.

Pick this when you have server rendering but genuinely nowhere to run edge code, such as a self-hosted setup behind a plain load balancer.

Server-side rendering at the edge

An edge function runs before the CDN cache. It initializes the Edge SDK with the incoming request, gets the manifest, and rewrites the URL to something like /pricing?personalize_variants=a_0,b_1. The CDN uses that rewritten URL as the cache key. On a miss, the origin reads the parameter, calls variants() and renders.

const sdk = await Personalize.init(projectUid, { request });
url.searchParams.set(sdk.VARIANT_QUERY_PARAM, sdk.getVariantParam());
const response = await fetch(new Request(url.toString(), request));

That is the core of it. Everyone who resolves to a_0,b_1 shares one cached page. The origin only renders on a cache miss and never sees a user ID. No flicker, full SEO, and the decision happens close to the visitor.

The trade-offs are real but small. You need an edge layer: Launch Edge Functions, Vercel middleware, Netlify Edge Functions, Cloudflare Workers, Fastly, Akamai or CloudFront all work. Tracking impressions and conversions still happens in the browser, because the edge cannot know what was seen or clicked. Every variant combination is a separate cache entry, so dozens of overlapping experiences fragment your cache. And on Launch specifically, Next.js middleware runs on the server, so the logic goes in a Launch Edge Function.

Since the origin only reads a query parameter, this also works in front of a non-JavaScript backend. The edge function is a separate deployment that the origin does not need to know about.

Side by side

CSR

CSR + SSG

SSR

SSR at the edge

Flicker

Yes

Yes

No

No

SEO on variant content

Poor

Base content only

Full

Full

CDN caching

None for personalized content

Static shell only

Only with a custom cache layer

Per variant combination

Origin load

Low

Low

Every request

Cache misses only

Extra latency

Two browser round trips before content

Same, after the static paint

Edge API call per request

Edge API call at the edge

Complexity

Low

Medium, two render phases

Medium, custom caching

Low after a one-time edge setup

Infrastructure

None

Static hosting

Server

Server plus edge layer

Use it for

Last resort SPAs

Static sites, below-the-fold widgets

No edge available

Almost everything else

How I would decide

I ask two questions.

Can you run code in front of your origin? If yes, use SSR at the edge. That includes non-JavaScript backends, because the edge function is separate from the origin.

If not, do you render on the server? If yes, use SSR at the origin and plan your cache key around variants from day one. If no, use static generation with client-side personalization, and keep personalized content out of the hero.

Pure CSR is what is left when the answer to both is no.

For native mobile apps, the question looks different: call the Personalize Edge API directly from the device. It is one hop, close to the user, and there is no HTML to cache. Put a small edge proxy in between only if you need to hide credentials or enforce your own rate limits.

Where to go from here

If you are going the edge route, the guide Personalize with server-side rendering at the edge builds the whole thing on Next.js and Launch: the edge function, entry variants with variants(), cache headers, tracking and layered experiences. The chapter on setting up the Edge SDK is where to start if you already know the concepts.

For the bigger picture of how the CMS, Personalize and Lytics divide the work, read Understanding how Contentstack CMS, Personalize and Lytics work together.

My take: the edge pattern looks like the advanced option, and it is the simplest one to run in production. The setup is one edge function and one query parameter on the origin. After that, marketers add experiences and you do not touch the code.

Frequently asked questions

  • Which Personalize architecture should I start with?

    SSR at the edge, unless you cannot run any code in front of your origin. It is the only option without flicker that still caches at the CDN.

  • Does my backend have to be JavaScript to use the edge pattern?

    No. The Edge SDK runs in the edge layer. Your origin only reads a query parameter and passes variant aliases to the Content Delivery API.

  • Why does client-side personalization flicker?

    The browser renders the base content first, then asks Personalize for variants, fetches them and re-renders. The swap is visible.

  • Can a statically generated site use Personalize?

    Yes, by personalizing client-side on top of the static page. You keep fast static delivery but accept flicker, and search engines only see base content.