Configurable Preview Routing

Configurable preview routing in Optimizely CMS 13 represents a significant shift from hardcoded server-side logic to a dynamic, configuration-first model. This architecture allows for a flexible contract between administrators, who define the structure of preview URLs, and developers, who implement the underlying logic to render content based on those structures.

The Administrative Responsibility: Configuration and Tokens

Administrators control preview routing through the CMS Admin interface under Settings > Preview routing. This section allows for the management of preview behaviors at the application level, providing a granular way to define how different types of content are previewed.

Enabling Preview Destinations

Administrators can toggle "Preview enabled" for specific applications. When active, they can define URL patterns for specific content types or base types (such as Pages or Blocks). This flexibility ensures that a multi-channel setup—where different frontends might handle different content branches—can be centrally managed within the CMS.

Using Dynamic Tokens

Preview URLs are constructed using a set of predefined tokens that the CMS replaces with real metadata at runtime. Key tokens include:

• {host}: Resolves to the primary hostname of the site.
• {key}: The unique identifier (GUID) for the content item.
• {version}: The specific version ID, essential for showing the exact state of a draft.
• {locale}: The language branch of the content.
• {path}: The hierarchical URL segment.
• {context}: Indicates whether the request is for an interactive edit mode or a standard preview.

Common Pattern Example:

The Developer Responsibility: Implementation and Routing

While administrators define the "where," developers are responsible for the "how." The frontend application (built in frameworks like React, Next.js, or Astro) must be architected to handle the dynamic requests generated by these configured routes.

Synchronizing Frontend Routes

Developers must ensure that the routing system in their application can parse the parameters defined by the administrator. If an administrator configures a route like /preview/{key}, the developer must implement a corresponding dynamic route (e.g., /preview/[key] in Next.js) that can extract that ID and use it to perform a GraphQL query.

Bypassing Default Logic

When a request is identified as a preview request (often via the {context} token or the presence of a preview_token), the developer logic must:

1. Switch Authentication: Move from public HMAC keys to the JWT-based preview_token.
2. Target Specific Versions: Force the data fetch to request the specific {version} provided in the URL, rather than the newest "published" version.
3. Inject Communication Scripts: Include the communicationinjector.js script to allow the frontend to interact with the CMS editor shell.

Supporting Interactivity Attributes

For a truly seamless experience, developers should render specific HTML attributes (such as data-epi-edit) that allow the CMS to map UI elements directly to content fields. This metadata confirms to the CMS that the frontend is a "smart" preview host capable of on-page editing.

Conclusion

Configurable preview routing decentralizes the management of the editor experience. By leveraging dynamic tokens, administrators can adjust the routing paths for an entire organization without touching code, while developers focus on the robust implementation of version-aware rendering and secure token handling. This alignment is the foundation of a successful hybrid or headless Optimizely CMS implementation.