RFC: Blocks

[josephfusco]

RFC: Next-Generation Block Support in the Headless WordPress Toolkit

Abstract

The Headless WordPress Toolkit aims to simplify how developers integrate WordPress blocks in headless environments. Current methods for handling Gutenberg blocks in decoupled architectures often require excessive customization, making projects complex and difficult to maintain. This RFC proposes an approach to querying, registering, and rendering WordPress blocks in headless applications through a GraphQL-driven data layer and framework-agnostic rendering utilities, building on wp-graphql-content-blocks as its foundation.

Motivation

WordPress blocks are powerful, but implementing them in headless applications remains challenging. Developers frequently encounter:

1. Inconsistent approaches to handling block content
2. Inefficient data retrieval through the REST API
3. Difficulties maintaining consistent rendering across projects
4. SEO and performance issues from client-side rendering
5. The need to rebuild block-handling logic for each project

The Headless WordPress Toolkit can provide a more structured approach to working with WordPress blocks across JavaScript frameworks.

Research & Background

Several approaches to handling blocks in headless WordPress have emerged:

• Parsing raw HTML blocks
• Using REST API block content
• Rendering blocks client-side
• Server-side processing with GraphQL

wp-graphql-content-blocks has shown promise by providing structured block content through GraphQL. By incorporating this tool into a broader toolkit, we can better serve developers building block-based headless applications.

Proposal: A Unified Block Rendering System

1. GraphQL-Enhanced Block Querying

• Implement wp-graphql-content-blocks for structured data retrieval
• Define normalized GraphQL schemas aligned with WordPress blocks
• Support extension points for custom block definitions

2. CLI for Block Management

npx @hwp/blocks add post-grid

• Support customizable block templates
• Provide scaffolding for common block patterns

3. Framework-Agnostic Rendering

• Support React, Vue, and Svelte components
• Optimize for Next.js, Nuxt, and Astro
• Maintain compatibility with Gutenberg and Classic Editor

4. Configuration & Documentation

/packages/headlesswp-blocks

• Implement a configurable block directory
• Define GraphQL block schemas in toolkit.config.json
• Include documentation for each block type

Alternatives Considered

1. Static HTML parsing - Limited interaction capabilities
2. PHP pre-rendering - Creates unwanted backend coupling
3. REST API - Lacks structured data capabilities

GraphQL provides the necessary structure and flexibility for complex block data.

Adoption Strategy

• Release experimental package for testing
• Create example projects across frameworks
• Publish implementation guides
• Engage with the community via GitHub and WordPress Slack

Future Considerations

• Block preview functionality
• Dynamic block registration
• Cross-site block sharing
• Enhanced GraphQL schema flexibility

How You Can Help

The success of this project depends on community input. We're particularly interested in:

• Feedback on real-world block implementations
• Suggestions for rendering approaches
• Example projects showing practical usage

Closing Thoughts

This RFC proposes a path toward better block handling in headless WordPress. By focusing on GraphQL querying, automated tooling, and flexible rendering, we can improve how developers work with blocks in modern JavaScript applications.

We welcome community discussion to refine and improve this proposal.

[colinmurphy]

@josephfusco the RFC looks great 🚀 👏