Skip to Content
CMS 13 Headless Masterclass

Part 1: Introduction

Why Optimizely CMS 13 is ready to build on, why headless is its natural fit, and what this masterclass builds, part by part.

Hi, I'm Michał. I've been working with Optimizely for more than 13 years, and headless architecture is the part of that work I enjoy most. I've written about it before, on CMS 12, in my Going Headless series.

CMS 13 changes the starting point. On CMS 12, headless was one option among several and usually needed a good reason. On CMS 13, I think it's the natural default. That's why I wanted one place that walks through a complete headless build on CMS 13, from an empty project to Visual Builder, live preview, content variations and forms, in the order you'd actually build it.

This masterclass is that walkthrough. Every part is built hands-on in a real project before I write it up, so the commands and code you'll see are the ones that worked, not ones reconstructed from documentation.

Who this masterclass is for

You don't need prior experience with Optimizely headless. I'm writing for someone who may know one side of the stack well, say .NET and CMS 12, or Next.js and React, and is new to the other. Every hands-on part shows the exact commands, how to run each project, which URL to open, what you should see, and what it looks like when something goes wrong.

The CMS in this masterclass is PaaS CMS 13: the .NET-based Optimizely CMS that you host yourself or on Optimizely's Digital Experience Platform (DXP). It's a different product from Optimizely SaaS CMS, which Optimizely hosts for you and which is headless only.

This part has no code, so you don't need anything installed yet. For the hands-on parts, you'll need:

  • The .NET SDK and Node.js, to run the CMS and the front end locally.
  • Access to Optimizely with Opti ID (Optimizely's single sign-on), to connect the CMS to Optimizely Graph.
  • A DXP environment and a Vercel account, for the deployment part.

Part 3 lists the exact versions and walks through the setup.

DXP isn't a hard requirement. You can follow the masterclass with the CMS hosted somewhere else, for example on Azure or on your own servers. The masterclass itself is built on DXP, though, so not every step will match your setup one to one: mainly where the Opti ID credentials come from (Part 3), how the CMS gets deployed (Part 4) and the CDN in front of your media (Part 11). In those places, you'll need to adapt the step to your own hosting.

Versions used

This masterclass is built and tested on CMS 13.6.0 and @optimizely/cms-sdk 3.1.0 (the official JavaScript SDK). Newer versions will probably work, but if something you see doesn't match the article, check your versions first.

Where CMS 13 is now

CMS 13 reached general availability (GA) on March 31, 2026. Like most major releases, it launched with gaps. Three pieces were announced as coming later: Optimizely Forms, the JavaScript SDK and Language Manager. On top of that, the first build had a license-checking loop that stopped the CMS from starting outside DXP, for example on plain Azure.

Those gaps closed quickly:

  • Forms 6.0.0, the first CMS 13 version, shipped on April 9, nine days after GA. The same week, CMS 13.0.1 fixed the startup bug. Forms also has a headless API, so it's usable from a headless front end, not just from classic CMS pages.
  • The JavaScript SDK (@optimizely/cms-sdk) went GA on May 4. It's now at version 3.1.0, which added explicit support for PaaS CMS 13.
  • Language Manager for CMS 13 shipped in June.

So everything that was missing at launch was there less than three months later.

Since then, releases have kept coming at a steady pace. Between October 5 and November 10 alone, CMS went from 13.3.0 to 13.6.0, adding a Preview button in Visual Builder, device preview, a refreshed CMS UI and a faster full sync to Optimizely Graph, along with fixes for regressions found along the way. You can follow them in the CMS 13 release notes.

That doesn't mean everything is ready. Some popular add-ons have caught up: Forms, Language Manager, the DAM integration, Advanced Reviews and Geta's NotFoundHandler all have CMS 13 versions. The notable holdout is Search & Navigation (formerly Find): its latest release, from late October 2026, still supports CMS 12 only. That matters less than it sounds, because on CMS 13 Optimizely Graph is meant to take over that role. If you're planning a migration, check each add-on you depend on at nuget.optimizely.com and in Optimizely's third-party package compatibility notes first, since this list changes from month to month.

My take: CMS 13 is a solid foundation to build on today, for a new project or a migration.

Why headless on CMS 13

I covered the general pros and cons of headless in Going Headless: Making the Right Architectural Choices, so I won't repeat them here. In short, "headless" means the CMS stores and structures content and exposes it through an API, and a separate front-end application fetches that content and renders it.

What's specific to CMS 13 is that three things make headless the natural default rather than a special case.

1. Visual Builder comes from a headless product. Visual Builder is CMS 13's most prominent new feature: an editor where content authors put a page together from sections, rows, columns and blocks, and see the result as they go. It started in Optimizely SaaS CMS, which is headless by design. That's the setup it was built for, so a headless front end is the most direct way to get full value from it.

2. Optimizely Graph is at the heart of a CMS 13 solution. Optimizely Graph is a hosted GraphQL service that holds a synced copy of your content and makes it queryable. On CMS 13, content syncs there as part of the platform, and with Search & Navigation gone, Graph takes over search in most cases. The content API a headless front end needs is already in place on day one, without you building or hosting one.

3. AI tooling makes two projects easier to maintain. The classic cost of headless is maintaining two applications, the CMS and the front end, often in two languages. In my experience, AI coding assistants have made that noticeably cheaper, which puts headless within reach of smaller teams that couldn't justify it before.

None of this removes the trade-offs. You still host and deploy two applications, and the front end has to handle routing and preview on its own. This masterclass deals with those head-on: deployment gets its own part, and so does live preview.

The plan

The core path has eight parts. By the end of Part 8, you have a complete headless site.

  1. Introduction: this part.
  2. Architecture overview: how the CMS, Optimizely Graph and the front end fit together, and the stack this masterclass uses (Next.js on Vercel, with the official Optimizely SDK).
  3. Creating an empty CMS 13 project: scaffold the CMS with Opti ID and Graph, plus a Next.js front end, both running locally.
  4. Deployment: Vercel and DXP: deploy the front end to Vercel and the CMS to DXP.
  5. Content modeling and Visual Builder: model your content types in the CMS and render a Visual Builder home page in Next.js.
  6. Visual Builder live preview: let editors see their changes rendered by the real front end while they edit.
  7. Content variations: serve a different variation of the home page, picked by a query string parameter.
  8. Forms: build a form in the CMS and render and submit it from the Next.js front end.

After that come optional extensions. They build on the core path but aren't needed to finish it:

  1. Forms: authenticated submission: require a token to submit a form, both for a server-side app and for a signed-in user.
  2. Multisite: run a second site from the same CMS instance, with its own content and content types.
  3. Images and CDN: deliver media through the DXP CDN in a production-ready way.

Parts will show up in the sidebar as they're published, and the plan may shift a little as I build. If it does, this list will change with it.

What's next

In Part 2, Architecture overview, we'll look at how the pieces of a headless CMS 13 solution fit together and settle the stack the rest of the masterclass builds on.

I hope you find this series useful. Happy coding!