Admin and Settings

Role

ReactWP ships with an opinionated admin setup.

The goal is to make the project editable from WordPress while keeping the runtime contract predictable.

Settings Pages

By default, ReactWP registers two options pages:

• Site settings
• Theme settings

These are created by the shared mu-plugin runtime.

Both pages require manage_options by default. rwp_options_page_capability may replace that capability for both pages; an empty filtered value falls back to manage_options.

This part of the starter requires ACF PRO because the options pages, repeaters, and field groups use PRO APIs. ACF Free remains supported for standard project field groups, but ReactWP hides the unavailable Site settings and Theme settings links and shows an administrator notice explaining the limitation.

The heavier Site settings field groups are only assembled on the Site settings screen and its ACF AJAX requests. ReactWP avoids building those choices on unrelated dashboard and list screens.

Site settings

Site settings owns the starter-level configuration used by the shared runtime. The current groups and stored field names are:

Group	Field contract
Languages	langs, an ACF repeater limited to five rows, with text subfields name and code
Theme Locations	theme_locations, an unbounded repeater with text slug and one translated name_<language-code> text field for every configured language
Media Groups Global Settings	mediaGroups_post_types, a checkbox of selectable public post types
React Template Global Settings	react_template_post_types, a checkbox of selectable public post types
Headless API	headless_allowed_origins, a repeater limited to 20 rows, each containing the URL field origin
SEO	global fields registered by the active reactwp-seo plugin; see Head and SEO for every current field

The five shared groups have show_in_rest disabled. Runtime code reads the saved options and publishes only the specific values described by each frontend/headless contract.

Theme settings

Theme settings exists as a dedicated place for project-specific theme options.

By default, the starter ships the page but does not force a large field set into it.

That means a project theme can define its own options there without mixing them into the shared runtime settings.

Languages

The starter stores languages in Site settings.

This language data is used by the runtime for:

• translated menu location labels
• language-aware SEO fields
• general starter defaults

Integrated React templates receive the current language through the normalized route and the initial language through the site payload:

const Template = ({ route, site }) => {
    const language = route.lang || site.language || 'en';
    const locale = site.locale || 'en_US';
};

• route.lang follows the route currently being rendered, including client navigation
• site.language is the initial bootstrap language and a useful fallback
• site.locale is the complete WordPress locale, such as fr_CA

External headless frontends receive the same route.lang, site.language, and site.locale values through the public payload contract.

Theme Locations

Theme menu locations are created in Site settings, not hardcoded in the theme.

This is important because it means:

• locations can be added or removed from the admin
• the runtime registers menus from options
• the frontend receives only the normalized result

See Content and Menus.

Media Groups Post Types

The Media Groups Post Types setting controls which post types expose the media groups feature in ACF.

That feature is what lets a route declare which critical and deferred asset groups the loader should use.

Those extra ACF fields are registered by the shared runtime field groups, not by the theme.

Regardless of the checkbox, the text field media_groups is always attached to built-in posts, pages, all user forms, and all taxonomies. Selected post types add more ACF locations. Its field group is visible in the side column and has show_in_rest: 1.

React Template Post Types

The React Template Post Types setting controls which post types expose the React template selector in ACF.

That selector lets editors or developers assign a React template name that the route resolver will include in the payload.

If a custom post type does not appear here yet, make sure the post type exists before reloading the settings page.

The same supported content screens receive the React Rendering group. It can override the registered template's client/static/server default and configure SSR cache scope and TTL for one route. See Hybrid Rendering.

More exactly, the runtime attaches these fields to built-in posts, pages, all user forms, all taxonomies, and the additionally selected post types:

Group	Field	Type and values	REST exposure
React Template	react_template	free text template name	group show_in_rest: 1
React Rendering	react_render_mode	select: template default (''), client, static, server	group show_in_rest: 0
React Rendering	react_render_cache_scope	when server is selected: private (default) or public	group show_in_rest: 0
React Rendering	react_render_cache_ttl	when server is selected: integer seconds, minimum 0, default 0	group show_in_rest: 0

The free-text template value is still validated and normalized later by the template/render contracts; the ACF field itself is not a registry picker.

Headless API Origins

The Allowed Headless Origins setting controls which external frontend origins can use credentialed headless authentication.

Use exact origins, including the scheme and port when needed:

https://app.example.com
http://localhost:3000

Do not add wildcard values. Public content endpoints are public, but login, logout, and current-user requests should stay limited to trusted frontend origins.

See Headless API.

SEO Global Settings

The built-in SEO plugin adds its global settings into Site settings.

That is where default SEO values such as descriptions and OG fields are managed.

See Head and SEO.

Optional First-Load Scaffold

The PHP first-load scaffold is disabled by default. It can be enabled before or after the normal WordPress installation. Temporarily define RWP_FIRSTLOAD as true, then visit the administration as a user with manage_options to seed missing starter values once.

It can create or reuse the ReactWP 3 home page, add French and English language rows, add the primary theme location, create or reuse Primary Navigation, configure the static front page, and set pretty permalinks when they are empty. ACF repeater options stored as 0 are treated as empty. Missing ACF field references from an older or interrupted run are repaired, while repeaters containing rows are preserved.

The rwp_firstload option records the successful scaffold schema version, which defaults to 1. ReactWP will still repair missing required repeaters or field references when the constant is enabled, even if that version was recorded by an older run. A short-lived option lock prevents concurrent administrator requests from running the scaffold twice. Remove the constant after verifying the first successful administration request.

This behavior lives in:

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

This PHP scaffold is unrelated to the browser loader's visual "first load" lifecycle.

Backend Cleanup

The bundled reactwp-backend plugin also reshapes the admin.

It removes and reorganizes parts of the default dashboard and admin menus, and adds quick links in the admin bar.

This is part of the default authoring experience of the starter, not an unrelated plugin. The cleanup changes navigation and editing UI; it does not revoke WordPress capabilities or unregister the hidden screens. See Bundled WordPress Plugins for the exact dashboard boxes, side-menu entries, Customizer sections, and capability-gated admin-bar links.

ReactWP Admin Bar

For users with the required capabilities, reactwp-backend adds a ReactWP group to the WordPress admin bar. Its links can include:

• Site settings
• Theme settings
• Themes
• Plugins
• Cache
• ACF
• Import
• Export

The Cache item is placed immediately after Plugins. Capability checks still decide which users see each destination.

ReactWP Cache Screen

ReactWP > Cache shows the current cache generation and a button to invalidate the ReactWP-managed cache layers.

The action:

• requires manage_options
• uses a WordPress nonce
• advances the server-controlled generation
• causes visitor JSON/media Cache Storage and versioned JavaScript/CSS references to rotate on the next full page load
• invalidates static and cached SSR HTML fragments, including public shared entries and per-user private entries
• queues affected static fragments for regeneration when the optional render service is configured

It does not reach into an already-open remote browser tab immediately, and it cannot automatically purge a provider-specific CDN cache. See Cache and Invalidation.

ACF Local JSON

The bundled ACF JSON plugin uses the active built theme runtime path:

<active stylesheet theme>/datas/acf/

Author its deployable source equivalent at src/themes/<theme>/template/datas/acf/. The plugin creates server-protection files, replaces ACF's save path, removes the first default load path, and appends the theme path when it exists. Create that directory when the project wants field groups versioned with the theme. Do not create a root datas/acf/ directory and expect the pipeline to discover it.

Recommendation

Keep this distinction in mind:

• Site settings is for starter-level shared runtime configuration
• Theme settings is for project-level theme configuration
• ReactWP > Cache is an operational release control, not a content options page

That split helps keep the shared ReactWP runtime stable while still giving each project a clean place for custom options.