React Home Headless

WordPress plugin for running a React-powered headless homepage from any normal block theme.

This rebuild merges the useful ideas from wp-headless-react-theme-master into react-home-headless without requiring a special theme template. It is designed to work with:

• a normal WordPress block theme,
• wp-bbuilder blocks and dynamic forms,
• wp-bbtheme theme settings/assets where present,
• an embedded React homepage, a proxied external React app, a redirect mode, or API-only mode.

Install

1. Upload react-home-headless to /wp-content/plugins/.
2. Activate React Home Headless.
3. Go to React Headless in wp-admin.
4. Select a source page. The default is the WordPress static front page.
5. Choose a render mode.

REST API

Main endpoint:

/wp-json/rhh/v1/homepage

Additional endpoints:

/wp-json/rhh/v1/navigation
/wp-json/rhh/v1/form
/wp-json/rhh/v1/builder
/wp-json/rhh/v1/settings
/wp-json/rhh/v1/page/{slug}

Backward-compatible endpoints are also available:

/wp-json/headless-home/v1/homepage
/wp-json/headless-home/v1/page-by-slug/{slug}

Payload includes

• page ID, title, slug, URL, excerpt and featured image,
• raw content, rendered HTML and parsed Gutenberg blocks,
• block attributes, nested blocks, rendered block HTML and component hints,
• WP BBuilder block detection and dynamic form extraction,
• ACF fields when ACF is active,
• SEO payload from Yoast or Rank Math where present,
• navigation menu items,
• WP BBuilder / WP BBTheme detection,
• public app settings and endpoint URLs.

Render modes

Embedded React app inside WordPress

The plugin replaces only the homepage request with a small React renderer. This is the easiest mode for a normal block theme.

Proxy external React app through WordPress

The plugin fetches the external React app URL, injects window.__RHH_DATA__, and serves it from WordPress.

Redirect

The WordPress homepage redirects to your external React app.

API only

WordPress renders normally. You can consume the REST API from any React/Vite/Next app.

WP BBuilder notes

The plugin forces the wpbb-form-view runtime on the React homepage when WP BBuilder is active, because forms loaded through React/REST are not always detected by WordPress during normal enqueue timing.

WP BBuilder blocks are exposed as rendered HTML plus structured block metadata. You can either render the HTML directly or map component values like WPBBHero, WPBBDynamicForm, WPBBGallery, WPBBAccordion, etc. to custom React components.

React starter

See examples/App.jsx for a minimal external React app example.