CMS 13 (PaaS): A Technical Overview

Introduction

Welcome to the first module of the Optimizely Academy CMS 13 PaaS Developer Certification path. As the platform evolves toward a more composable, SaaS-like delivery model, developers must shift their mental models from traditional monolithic site definitions to a more flexible application-oriented architecture.

This article provides a high-level technical overview of the architectural shifts, authentication changes, and delivery patterns introduced in Optimizely CMS 13.

1. The Platform Shift: .NET 10 and Version 13.x

Optimizely CMS 13 marks a significant step forward in performance and modern development practices by targeting .NET 10. While the move from CMS 11 to CMS 12 represented the major transition from .NET Framework to .NET Core, CMS 13 builds on that modern base rather than replacing it outright.

1.1 Key Framework Updates

• Target Framework: Developers must update project files to target net10.0.
• NuGet Package Versioning: Core packages such as EPiServer.CMS move to the 13.x major version line.
• API Consolidation: APIs previously marked obsolete in CMS 12 are removed, pushing developers toward content-agnostic patterns such as using ContentReference instead of PageReference.

2. Beyond Site Definitions: The Application Model

One of the biggest conceptual changes in CMS 13 is the move away from traditional site definitions and toward an Application-based model.

In older versions, a site was essentially a database-driven mapping between hosts and content roots. In CMS 13, the platform introduces the Application base class, enabling more diverse delivery patterns and making room for both in-process and remote heads under a common administrative model.

• Website (In-process): Represents a traditional CMS application where the delivery head and CMS engine run within the same process.
• RemoteWebsite (Headless/Remote): Represents a decoupled front end such as a Next.js or Nuxt application that consumes content through APIs while still being managed inside the CMS administrative interface.

2.1 The New Repository Pattern

Developers should move away from ISiteDefinitionRepository. To work with application configurations, the recommended pattern is to use IApplicationRepository.

This shift from GUID-based site IDs to immutable application names simplifies configuration management across environments such as Integration, Preproduction, and Production.

3. Unified Authentication with Opti ID

For PaaS customers, CMS 13 standardizes administrative and editorial authentication around Opti ID, Optimizely’s OIDC-based single sign-on solution.

3.1 Implementation in Startup.cs

Configuration no longer depends on heavier legacy identity setups for the shell UI. Instead, the EPiServer.OptimizelyIdentity package provides a more streamlined integration.

By default, Opti ID secures protected shell modules and edit mode. If needed, you can set useAsDefault: true to extend it to the public front end as well. In many implementations, however, teams continue using external identity providers such as Microsoft Entra ID for public users while reserving Opti ID for editorial staff.

4. Querying and Search: The Role of Optimizely Graph

In CMS 13, Optimizely Graph becomes a foundational layer for querying content. Traditional in-process APIs such as IContentLoader and IContentRepository still matter for application-side operations, but more advanced querying and cross-application search increasingly flow through Graph.

4.1 Why Optimizely Graph?

• Unified Index: It acts as a central hub for content from CMS, Commerce, and potentially external sources.
• GraphQL API: Front-end teams can request exactly the fields they need without introducing excessive DTO mapping in C#.
• Visual Builder Dependency: Advanced experiences such as the new Visual Builder rely on Graph to deliver variations and content in real time.

5. Migration Strategy: Moving from CMS 12

The path from CMS 12 to CMS 13 is designed to be relatively compatible, but several cleanup and modernization tasks are still required in project configuration and startup behavior.

1. Framework Upgrade: Move from net8.0 to net10.0.
2. Database Compatibility: Update database settings and version assumptions for the new platform schema.
3. UI Components: Replace legacy shell helpers such as @Html.CreatePlatformNavigationMenu() with the newer <platform-navigation /> Tag Helper.
4. Visitor Groups: Explicitly register visitor group services using services.AddVisitorGroups().

5.1 Constraints to Consider

Although the upgrade is smoother than earlier generation jumps, teams should plan carefully for the Optimizely Graph transition. If a solution depends heavily on legacy Search & Navigation implementations, those requirements should be mapped to Graph capabilities early in the upgrade cycle.

Conclusion

Optimizely CMS 13 continues the modernization that began with CMS 12, but it also introduces meaningful architectural shifts in how applications, authentication, and content querying are handled. For developers, the key mindset change is moving away from older site-centric assumptions toward a more composable application model supported by Opti ID and Optimizely Graph. Understanding these changes early makes the rest of the CMS 13 learning path a lot less like surprise surgery and a lot more like planned engineering.