RFC: Previews

[whoami-pwd]

Abstract

This document outlines a proposal for a customizable Preview functionality for Headless WordPress. The intent is to provide editors with a more dynamic, flexible preview experience, addressing challenges such as authentication requirements for previews, managing drafts, and handling non-public post statuses. Currently, the developer experience can be unfriendly due to complexities with post statuses and preview requirements, which this RFC aims to simplify.

Motivation

We are planning to offer a WP plugin that delivers customizable Preview functionality for Headless WordPress environments. The solution will be framework-agnostic while offering extensive configuration options, making it easier for developers and content editors to manage previews without extensive custom work.

Research

Code example: https://github.com/wpengine/hwptoolkit/tree/poc-post-previews-plugin/plugins/hwp-previews

Auth Required

Previews and non-public post statuses often require authentication. The system must securely manage access to unpublished or draft content.

Security

A common approach is to use JWT to maintain a stateless authentication state, which suits this scenario. Additionally, employing WP nonce can provide an extra layer of security and dynamic control.

FE graphql queries for 'drafts' and other non public statuses

Front-end implementations need to query for draft and non-public statuses via GraphQL. Ensuring these queries are secure and efficient is a key requirement.

Non-unique slugs for the drafts

Draft posts may have non-unique slugs, so the system needs to handle URL conflicts and ensure correct content is previewed.

No possibility to select draft as a parent for another hierarchical post type item

Drafts should not be selectable as parent items for hierarchical post types, preventing potential issues in content organization.

Variety of configuration options to dynamically set up previews for the Framework used on the FE

The plugin should support multiple frameworks by allowing dynamic configuration of preview settings, catering to various front-end environments.

Framework Specific Draft Mode

Certain frameworks (e.g., Next.js, Nuxt.js) offer their own Draft Mode implementations. The solution should integrate with these systems while maintaining a unified configuration interface.

UX in terms of WP Admin Headless previews

In the WP Admin, the preview experience is typically provided via a new tab with a filtered URL preview. Alternative approaches, such as embedding previews in iframes, have also been explored.

Proposal

We propose to develop a series of proof-of-concepts (POCs for the WP Plugin "HWP Previews") that demonstrate the core preview functionalities. This includes comprehensive documentation and code examples to guide integration efforts. Further work will be needed to refine the options and functionalities available.

Options include:

• Specify post types on which previews are enabled.
• Specify post statuses for which previews are enabled.
• Enable/disable unique slugs for specified post types and statuses.
• Enable/disable the selection of post statuses as parent items for hierarchical post types.
• Configure the front-end URL for previews.
• Customize the naming of all required URL parameters.
• Enable/disable Draft Mode, which alters the preview URL structure by providing a SLUG.
• Leverage the WPGraphQL JWT plugin to offer built-in support for authentication-required queries.
• Enable/Disable iframe preview mode (default). New tab Preview when iframe disabled.
• Provide additional examples using alternative authentication methods, such as WP App Password.

Alternatives Considered

An alternative approach would be to forgo the WP plugin functionality entirely and instead offer documentation and examples for developers to implement their own preview solutions. However, this is not ideal, as the goal is to provide a faster, more user-friendly Headless WP Previews experience.

How Do We Teach This?

The solution will be thoroughly documented within the code and accompanying readme files. Extensive descriptions for each option and setting will be provided, along with code links or inline examples directly within the plugin itself, ensuring that both developers and content editors can easily understand and adopt the functionality.

How Can You Help?

We welcome your feedback on the proposed Preview functionality. Please share any suggestions for additional features, improvements, or potential challenges that you foresee. Your input is invaluable as we work to create a more robust and user-friendly Headless WP Previews experience.

Note: This RFC might be edited during a couple of days. The changelog will be provided.

[moonmeister]

Nice work Alex! lots of good info and ideas here! here's my 🪙 🪙:

Proposal Feedback

Our proposal should be to build a plugin and provide a series of examples and docs on how to leverage that plugin. You say that other places, but the proposal sections seem to ignore the plugin. That's the core of this proposal.

"Auth Required" - I disagree

While I agree that auth is a common requirement, I don't believe it is a requirement for this plugin or universally. By integrating auth into this, we require them to integrate our auth, which is now a public API we maintain; making this pluggable adds more code to maintain, and I just don't see why we care need this. I'd rather start simple and rely on them providing auth based on the work being done in the Auth RFC.

Remember, one valid option here would be for me to make draft data publicly available in WP GraphQL. While not terribly secure, this would be a simple way for me to enable previews without wiring up a whole auth system. Combine this with setting a server to only respond to my IP, and I've created "auth" without ever touching code or JWTs.

"Framework Specific Draft Mode"

We definitely want to enable support for these, but I think this explicit option is the wrong choice. Based on what you say here, this only takes a specific set of data and adds it to the query param for the preview URL. If we had the ability to map any post data to any query string that'd solve this problem and the query string naming issue while being much more customizable. We could then create customizable presets for Next, Nuxt, Faust, etc.

Questions

• Would this work for REST API users? is there anything WPGraphQL specific here?
• Are these preview URLs sharable?

[whoami-pwd]

@moonmeister Thank you for the feedback!

On the Proposal Structure

You're absolutely right that our core proposal is to build a plugin with supporting documentation and examples. I'll ensure this is clearly emphasized in the revised proposal to avoid any confusion.

On Authentication Requirements

I completely agree with your point about authentication. Integrating auth directly into this plugin would create unnecessary dependencies and maintenance burden. We should:

• Delegate authentication optional and pluggable
• Allow developers to leverage existing auth solutions (including Auth RFC and/or existing plugins)
• Support simple use cases where drafts might be publicly accessible in controlled environments

This approach provides flexibility while maintaining security options for those who need them.

On Framework-Specific Draft Mode

Your suggestion about generalizing this functionality through customizable parameter mapping is excellent. Rather than hardcoding support for specific frameworks, we can:

• Create a flexible system that maps any post data to any query string parameter
• Provide preset configurations for popular frameworks (Next.js, Nuxt, Faust, etc.)
• Allow custom configurations for specialized implementations

Addressing Your Questions

REST API Support: Yes, the preview functionality is designed to be API-agnostic. It can work with both GraphQL and REST implementations, focusing on generating proper preview URLs with appropriate parameters rather than being tied to a specific API structure.
Shareable Preview URLs: Yes, preview URLs can be made shareable. Probably still need to brainstorm:

• Optional time-limited expiration for preview links
• Configurable access controls (e.g., IP restrictions, referring domains)
• Simple token validation that doesn't require complex authentication but provides basic security

Additional Considerations

The current updated POC provides a mechanism to use WP Post object public properties as preview URL parameters and supports custom parameter registration through action hooks. We'll maintain this flexibility while adding:

• A user-friendly settings page for quick configuration
• Front-end validation mechanisms to prevent preview URL abuse
• Documentation for common implementation patterns

Security Mechanisms for Front-End

To address front-end preview verification, we can implement:

• A lightweight validation endpoint that can verify preview requests are legitimate
• Optional signed tokens with configurable expiration
• Rate limiting capabilities to prevent abuse

[moonmeister]

@whoami-pwd Thanks for the follow-up! great info! I was talking to @JacobNWolf, and he mentioned that Next.js Draft mode is likely only supported on Vercel. Have you gotten that working on a node server? we might need to NOT use draft mode.

[colinmurphy]

Just noting that the initial POC (Alpha) has been merged - https://github.com/wpengine/hwptoolkit/tree/main/plugins/hwp-previews
We plan to have a Beta version in the next 2 months.

[colinmurphy]

Just a quick update, We expect to have Beta version within the next 2 weeks. There will be a release under releases -https://github.com/wpengine/hwptoolkit/releases

[colinmurphy]

Plugin is now available for beta testing and use - https://github.com/wpengine/hwptoolkit/releases/tag/%40wpengine%2Fhwp-previews-wordpress-plugin-0.0.7