RFC: Routing

[colinmurphy]

Abstract

In the context of headless WordPress (HWP) development, the traditional WordPress template hierarchy and fallback mechanisms do not translate intuitively for HWP developers.

This is due to the reliance on WordPress features that do not exist in a headless environment, such as themes, routing using a fallback system, WordPress configuration, and expected file name resolution (e.g., single.php). This results in a "round peg into a square hole" type of development to replicate the WordPress routing or template hierarchy in a headless setup.

Additionally, different frameworks offer different routing structures, mechanisms, and logic, making the WordPress template hierarchy difficult to replicate. This complexity is further compounded when considering whether the site is a single or multisite WordPress instance and how the multisite setup should be structured.

In the past, with Faust.js, we used a Seed Query to resolve templates and fetch data. However, this required two queries to render the page and was tightly coupled with the Apollo HTTP client.

Motivation

Our motivation is to simplify the routing and templating system for HWP developers while offering multiple routing approaches, including template hierarchy systems.

We do not want to restrict developers to a single approach but rather provide multiple solutions so they can choose what best fits their needs. This will be delivered through documentation and boilerplate project examples.

Through our research, we have learned that a "one size fits all" approach to routing and templating is not feasible. Additionally, we recognize that we cannot assume how every developer wants to set up routing. Instead, we should offer different solutions that allow developers to choose what fits their specific requirements.

We also want to foster a deeper understanding of the best practices for routing and templating in headless WordPress. This means continuously updating and expanding our documentation and examples. We welcome community contributions and aim to build documentation and examples that is intuitive and beneficial to our community.

Research

Over the last few weeks, we conducted research in several areas to evaluate the best approach for the community.

• We analyzed how routing is resolved and configured in modern JavaScript frameworks such as Next.js (App Router and Pages Router), Svelte, and Nuxt to understand how these approaches could be applied to WordPress routing in a headless setup.
• We reviewed how Faust.js resolves routing and templates, identifying issues that the community faces with this approach.
• We experimented with rewrites in a proof-of-concept (PoC) branch for different JavaScript frameworks to assess their viability for solving routing challenges in WordPress headless development - POC Branch.

Our conclusion is that any package or automated approach for routing, templates, and template hierarchy would not meet the diverse needs of the community. Instead, we need to provide multiple solutions for various setups, allowing developers to determine what works best for them.

The best way to achieve this is through comprehensive documentation and example boilerplate projects available for community review and contribution.

Proposal

We propose delivering routing, templates, and template hierarchy solutions through documentation and example boilerplate projects within this toolkit repository.

For our first iteration, we aim to provide example projects for Next.js (App Router and Pages Router) for a single WordPress instance. These examples will demonstrate how to route WordPress content natively within the framework and how to use rewrites to recreate the WordPress template hierarchy.

Additionally, we will provide documentation with code examples for common WordPress headless development use cases related to routing and templates.

The initial topics include:

• How to set up WordPress natively for headless development
• How to recreate the WordPress template hierarchy using rewrites in a headless environment
• How to use the Seed Query for headless WordPress
• How to set up WordPress multisite for headless development

Alternatives Considered

We considered building a CLI tool for routing and template generation. However, at this stage, we believe this is not the best approach for the reasons outlined above.

This does not mean we will not revisit this idea in the future. For now, our focus is on delivering high-quality documentation and example projects for the community.

Adoption Strategy

We aim to create the best documentation and examples for the WordPress headless community. We will promote and encourage community contributions and reviews to foster a collaborative learning environment.

How Do We Teach This?

We will ensure that our documentation and example projects are easy to follow and provide strong community support.

How Can You Help?

We are excited about this new toolkit and the opportunities it presents for the WordPress headless community.

We’d love your feedback on the following:

• Is this the best approach for the community regarding routing and templates? Are there better approaches we should consider?
• Are we missing any major topics or examples?
• What other topics would you like us to cover? We would love to hear from you!

RFC Changelog

• January 29, 2025 - Initial WIP for routing, templates and template hierarchy.
• January 30, 2025 - Minor edits to some of the wording under the section "Motivation"

[Fran-A-Dev]

Thank you for the write-up on this, @colinmurphy! This is great. I feel like you have covered everything as far as the purpose and goals for this repo are concerned. Stoked!

[colinmurphy]

Thanks @Fran-A-Dev for reviewing this 😁

[moonmeister]

Action items: #10