Application framework

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/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
• When you need to scale 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 various interfaces to provide specific capabilities:

IRoutableApplication

Applications that can be routed via 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 can exist.

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 (typically 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

📘

Note

Website supports fewer host types because the front-end application typically 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.
  • To support routing of 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 navigates to a content item belonging to an application whose edit host does not match the current host, CMS automatically redirects to the configured edit host. Only one edit host is allowed per application.

• Supported by – InProcessWebsite only
• When to use
  • Separate edit/settings interface from public site
  • Enforce same host for edit/settings interface and public site
• Best practice – Only define edit hosts when you truly need to enforce them. Redirecting users between different hosts while navigating across applications can be disruptive to the editing experience. Use edit hosts primarily 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 may 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 URLs are generated, hosts are selected based on the current context which represents the current request the application is served under.

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 vs canonical/absolute URL
• Whether the content is media

Key principles

• Edit mode can force an edit host – If an edit host is configured for the content’s application, CMS uses it in edit mode.
• Relative URLs prefer staying on the current host – In edit or preview mode, the current host is preferred when possible. In default mode, a host with matching language is preferred.
• Media content can use a media host – If a media host is configured for the content’s application, it is used in default mode. If not configured, it can fall back to the default application's media host or 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.