Skip to main content

Architecture

Role​

ReactWP is not just a theme. It is a starter made of three cooperating layers:

  • a shared mu-plugin runtime
  • a set of bundled plugins
  • a React-driven theme

Understanding that split is the fastest way to understand the project.

The Three Main Layers​

1. Mu-Plugin Runtime​

The ReactWP mu-plugin is the shared application runtime.

This is where the starter defines:

  • the bootstrap payload
  • the route resolver
  • the normalized navigation payload
  • the REST route used for client-side navigation
  • the public headless API contract
  • signed preview and headless authentication endpoints
  • the default admin settings pages
  • the first-load seeding behavior

Main files:

  • src/mu-plugins/plugins/reactwp/template/init.php
  • src/mu-plugins/plugins/reactwp/template/inc/runtime/Bootstrap.php
  • src/mu-plugins/plugins/reactwp/template/inc/runtime/RouteResolver.php
  • src/mu-plugins/plugins/reactwp/template/inc/runtime/MenuBuilder.php
  • src/mu-plugins/plugins/reactwp/template/inc/runtime/PublicPayload.php
  • src/mu-plugins/plugins/reactwp/template/inc/runtime/HeadlessApi.php
  • src/mu-plugins/plugins/reactwp/template/inc/runtime/PreviewToken.php
  • src/mu-plugins/plugins/reactwp/template/inc/admin.php
  • src/mu-plugins/plugins/reactwp/template/inc/firstload.php

2. Bundled Plugins​

The standard plugins shape the WordPress environment around the starter.

Shipped plugins:

  • reactwp-frontend
  • reactwp-images
  • reactwp-backend
  • reactwp-seo
  • reactwp-accept-svg
  • reactwp-acf-local-json

3. Theme​

The theme is the frontend experience layer.

It provides:

  • the PHP shell markup
  • the React application entry
  • templates
  • components
  • SCSS
  • theme-level payload customizations

Main files:

  • src/themes/reactwp/template/header.php
  • src/themes/reactwp/template/footer.php
  • src/themes/reactwp/template/functions.php
  • src/themes/reactwp/js/App.jsx

Bundled Plugin Responsibilities​

reactwp-frontend​

This plugin cleans the public frontend.

It removes or disables several default WordPress frontend behaviors, including:

  • the admin bar
  • block library styles
  • classic theme styles
  • speculation rules
  • various extra tags in <head>

Use it when you want the starter to own the frontend output more tightly.

reactwp-images​

This plugin changes how images are handled.

By default it:

  • disables intermediate image sizes
  • sets image quality to 100

This is an opinionated default. Projects that rely on WordPress responsive image sizes may want to revisit it.

reactwp-backend​

This plugin cleans the admin experience.

It:

  • disables Gutenberg
  • removes several dashboard widgets
  • trims admin menu items
  • adds useful shortcuts to the admin bar

This is part of the starter's opinionated backend workflow.

reactwp-seo​

This plugin owns the built-in SEO layer.

It:

  • controls wp_robots
  • generates <title>, description, Open Graph, and favicon tags
  • supports both direct PHP renders and React navigation through rwp_wp_head

See Head and SEO.

reactwp-accept-svg​

This plugin allows SVG uploads with a basic safety pass.

It:

  • allows the svg mime type
  • sanitizes the uploaded file name
  • rejects several unsafe SVG patterns

reactwp-acf-local-json​

This plugin stores ACF local JSON with the theme.

If a project needs ACF local JSON files, keep them in src/themes/reactwp/template/datas/acf/ so they are copied with the rest of the PHP theme files.

This keeps field groups and other ACF definitions versioned with the theme through the normal template copy flow.

First Boot​

On first boot, ReactWP seeds a usable starter environment.

By default, that includes:

  • a front page
  • default languages
  • a starter menu location
  • a starter menu assigned to that location
  • static front page settings
  • permalink structure

That behavior lives in:

  • src/mu-plugins/plugins/reactwp/template/inc/firstload.php

Request Lifecycle​

At a high level, ReactWP works like this:

  1. WordPress resolves the current object
  2. RouteResolver turns it into a normalized route payload
  3. Bootstrap builds the full first-load payload
  4. PHP injects that payload into the page
  5. React mounts and reads the payload
  6. On later navigations, the frontend fetches only the next route payload through REST
  7. The loader and transition runtime coordinate preload, leave, swap, and enter

For external headless frontends, the same resolver is transformed by PublicPayload and exposed through the headless REST endpoints. That keeps external apps away from WordPress internals while preserving the same source of truth for routes, menus, SEO, and ACF data.

Where To Customize What​

Use the right layer for the right job:

  • mu-plugin runtime: shared application behavior
  • bundled plugins: WordPress environment defaults
  • theme functions.php: project-level payload and asset customizations
  • React js/inc/config/: frontend runtime overrides
  • templates and components: rendering and UI