Application framework

21 min

The application framework in Optimizely Content Management System (CMS) 13 provides a flexible system for managing multiple websites and applications within a single CMS 13 instance. Each application can have its own content structure, hosts, and preview configuration, enabling both traditional server-rendered and headless multi-site scenarios.

Application types

The framework provides two main application types that inherit from the abstract Application base class.

Website

A Website represents an application that is hosted out-of-process (headless or decoupled architecture).

Key characteristics

Content rendering happens in a separate application (such as Next.js, React, Vue)

CMS delivers content via Optimizely Graph

Supports preview tokens for secure preview functionality

When to use

Headless CMS scenarios

JavaScript frameworks (such as React, Vue, Angular, Next.js) hosted separately

Mobile applications consuming CMS content

Scaling the front end separately from CMS

Multi-channel delivery (web, mobile, IoT)

In-process website

An InProcessWebsite represents an application that runs in-process within the same ASP.NET Core application as CMS.

Key characteristics

Routing to content is handled using ASP.NET Core endpoint routing

Supports controllers (MVC), Razor Pages, and other components implementing EPiServer.Web.IRenderTemplate

Full integration with CMS rendering pipeline

Content is rendered server-side in the same process

When to use

Traditional server-rendered websites

MVC or Razor Pages applications hosted in the same process as CMS

Application interfaces

Applications implement interfaces to provide specific capabilities.

IRoutableApplication

Applications that route through hosts and generate URLs for content.

Properties

EntryPoint – Specifies the content item that serves as the starting point for generating URLs

Url – Primary URL of the application

Hosts – List of application hosts for routing

IsDefault – The default routable application acts as a fallback when resolving an application from content, hostname, and request context. Only one default routable application exists.

IPreviewableApplication

Applications that support content previewing.

Properties

IsDefault – The default previewable application is used to preview content that does not belong to any specific application. For example, global assets such as shared blocks and images.

IRemotelyPreviewableApplication

Extends IPreviewableApplication for headless scenarios.

Properties

Hosts – Application hosts for previewing

PreviewUrlFormats – A collection of URL format patterns for previewing content. Each format can include replaceable tokens (for example KEY, VERSION) and can be defined per content type.

UsePreviewTokens – Appends a short-lived access token, based on the current user's principal, in the query parameter preview_token.

IResourceableApplication

Applications that provide access to application-specific assets.

Properties

AssetsRoot – Content reference to the assets folder (in SysSiteAssets)

Application host types

Application hosts define how requests are handled and how URLs are generated. Both Website and InProcessWebsite support multiple hosts and different types. The preferred URL scheme (http or https) for URL generation is controlled by the host.

Supported host types by application type

Host type supported	Website	InProcessWebsite
Primary	Yes	Yes
Default	No	Yes
Preview	Yes	No
Edit	No	Yes
RedirectPermanent	No	Yes
RedirectTemporary	No	Yes
Media	Yes	Yes

📘 Note Website supports fewer host types because the front-end application handles redirects.

Primary

Use as the main host for the application. Use as the redirect target and for generating outgoing URLs.

Supported by – Website and InProcessWebsite

When to use

The canonical domain for your website

When you want all URLs generated to use this host

As the target for redirect hosts

URL generation priority – Highest priority when generating URLs.

Best practice – Each application should have exactly one primary host per locale.

📘 Note Primary host must be unique.

Default

Use as the generic host without specific behavior.

Supported by – InProcessWebsite only

When to use

Initial setup before defining specific host types.

Routing additional hostnames to the primary host.

URL generation priority – Fallback if no primary host is found.

📘 Note Default host must be unique.

Preview

Use as the dedicated host for headless content preview functionality. Only one preview host is allowed per application.

Supported by – Website only

When to use

Headless scenarios where preview happens on a different host than where CMS is hosted.

When your production and preview environments are separate.

Edit

Specifies the host used by CMS in edit mode. When an edit host is defined for an application, CMS enforces it by redirecting requests. If a user opens a content item in an application with a different edit host, CMS redirects to the configured edit host. Only one edit host is allowed per application.

Supported by – InProcessWebsite only

When to use

Separate edit or settings interface from public site

Enforce same host for edit or settings interface and public site

Best practice – Only define edit hosts when you need to enforce them. Redirecting users between different hosts across applications disrupts the editing experience. Use edit hosts if you want to preserve the legacy behavior from CMS 12, where redirects were always enforced.

RedirectPermanent

Use as HTTP 301 permanent redirect to the primary host.

Supported by – InProcessWebsite only

When to use

Old domains that should permanently redirect

Non-www to www redirects (or vice versa)

Domain migrations

SEO consolidation

RedirectTemporary

Use as HTTP 302 temporary redirect to the primary host.

Supported by – InProcessWebsite only

When to use

Temporary domain changes

A/B testing scenarios

Maintenance redirects

Situations where you plan to revert the redirect later

Media

Use as host type when generating media URLs.

Supported by – Website and InProcessWebsite

When to use – Serving media assets from a dedicated domain or CDN.

Host selection priority for URL generation

When the system generates URLs, it selects hosts based on the current context. The context represents the current request serving the application.

Factors that affect host selection

Application matching the context's host

Application the content belongs to

Context mode ( Default, Edit, or Preview)

Requested language

Relative or canonical URL

Whether the content is media

Key principles

Edit mode forces an edit host – If an edit host is configured for the content application, CMS uses it in edit mode.

Relative URLs prefer the current host – In edit or preview mode, the current host is preferred. In default mode, a host with matching language is preferred.

Media content uses a media host – If a media host is configured for the content application, CMS uses it in default mode. If not configured, it falls back to the default application media host or the configured fallback media host in RoutingOptions.FallbackMediaHost.

Standard priority order

Primary host matching language

Default host matching language

Primary host without language mapping

Default host without language mapping

Context's current host (only applies to InProcessWebsite)

First available primary host

First available default host

Recommended configuration practices

Set one default application to handle fallback scenarios.

Use Website for headless scenarios to leverage preview tokens and URL formats.

Configure a primary host for predictable URLs.

Use edit hosts only when you want strict edit-host enforcement.

Configure media host when serving assets from a CDN or separate media domain.

Use locale-specific hosts when managing multilingual sites and want to omit the language segment from URLs.