Skip to main content

Project Structure

Root Layout​

reactwp/
|-- .agents/
|   `-- skills/
|-- AGENTS.md
|-- configs/
|-- dist/
`-- src/

Repository Agent Skills​

ReactWP keeps its repository-scoped Codex skills in .agents/skills/. Each skill has its own directory containing a required SKILL.md, optional focused references or scripts, and an agents/openai.yaml file for its display name, short description, default prompt, and invocation policy. This standard location lets Codex discover the skills automatically from the repository root.

AGENTS.md is intentionally a small router: it keeps repository invariants and maps affected behavior to the orchestration, frontend, backend, content and SEO, security, or quality-assurance skill. Detailed procedures live in each skill and are loaded progressively through its reference router.

Skill loading is proportional to the task. A localized change uses only its applicable expert guidance; substantial independent cross-layer work uses the orchestrator. Visual-reference reconnaissance can be site-wide, page-level, or component-level. Frontend/content tandem review is required only when editorial decisions materially affect hierarchy, SEO, CMS variability, responsive measure, media, structured data, or layout. QA first maps affected domains, then loads the applicable experts; release-wide and cross-layer audits load all four product-domain skills.

These files guide development work only: they are not copied into dist/ and are not part of the WordPress or browser runtime.

configs/​

configs/ contains the build system:

  • package.json
  • webpack configuration
  • build scripts
  • installed Node dependencies

See Build Tooling.

dist/​

dist/ is the generated WordPress install.

This is the directory your local server should point to.

Treat it as build output. The project is normally authored in src/, not in dist/.

src/​

src/ contains the editable project source:

  • src/core/ for root WordPress project files such as wp-config.php and .htaccess
  • src/mu-plugins/ for the shared ReactWP runtime
  • src/plugins/ for bundled standard plugins
  • src/themes/ for themes

Mu-Plugin Layout​

The ReactWP mu-plugin is the application runtime.

Important areas include:

  • template/init.php
  • template/inc/runtime/
  • template/inc/routes/
  • template/inc/admin.php
  • template/inc/firstload.php

This is where the starter defines the bootstrap payload, route resolver, menu normalization, global ReactWP cache generation, headless API, admin settings pages, and the optional RWP_FIRSTLOAD scaffold. That scaffold is disabled by default and is separate from the frontend loader's first-load animation.

Bundled Plugin Layout​

src/plugins/ contains opinionated environment plugins such as:

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

These plugins shape the starter defaults around frontend output, media handling, backend cleanup, SEO, SVG uploads, and ACF JSON storage.

Theme Layout​

Inside the default theme:

  • js/inc/ contains runtime code
  • js/inc/config/ contains the intended project-level runtime overrides
  • js/components/ contains reusable React components
  • js/templates/ contains page templates
  • scss/ contains styling source files
  • template/ contains the PHP shell and theme hooks

If a project needs to version ACF local JSON with the theme, use template/datas/acf/ so it is copied with the rest of the PHP theme files.

There is no project-level datas/acf/ directory. ACF JSON belongs to the theme that owns those fields.

Inside scss/, the project keeps the permanent base separate from template-owned screen styles so shipped starter visuals can be replaced without touching the runtime-safe base.

For the component layer, see Components.

Theme Runtime Layout​

The runtime code in js/inc/ is intentionally split by responsibility:

  • Runtime.js reads the bootstrap payload
  • Loader.js owns first-load and critical asset preparation
  • PageTransition.js owns route transition animation
  • RouteService.js fetches and caches route payloads
  • TemplateRegistry.js resolves lazy templates
  • Scroller.js owns the smooth scrolling layer
  • Cache.js owns versioned browser JSON/media cache storage
  • render/server.jsx is the universal React render entry
  • useRouteTransition.js coordinates navigation, preload, swap, and reveal

Generated Theme Assets​

A built theme can contain:

assets/
|-- css/
|   |-- <theme>.min.css
|   `-- chunks/
|-- js/
|   |-- <theme>.js or <theme>.min.js
|   |-- entrypoints.json
|   `-- chunks/
|-- render/
|   |-- server.cjs
|   |-- serve.mjs
|   |-- templates.json
|   |-- template-assets.json
|   `-- static/
|-- fonts/
|-- images/
|-- videos/
|-- audios/
`-- others/

Production JavaScript/CSS can also have .br and .gz siblings. These files, the chunks, and entrypoints.json are one deployment unit.

PHP Theme Shell​

The PHP theme shell lives mostly in:

  • template/header.php
  • template/footer.php
  • template/functions.php

Those files define:

  • the shell markup IDs used by the runtime
  • the bootstrap JSON script
  • the initial loader node
  • critical inline shell styles
  • the theme-level extension point for project hooks

The default classic theme intentionally omits 404.php. WordPress falls back to index.php, while the route resolver still selects the React NotFound template and preserves the 404 response.

See Theme Shell and Scroll.

Safe Runtime Configuration Files​

Projects are expected to customize a few dedicated files instead of patching runtime internals directly:

  • js/inc/config/configureLoader.js
  • js/inc/config/configurePageTransition.js
  • js/inc/config/configureTemplateRegistry.js

Those files run after the starter restores its default runtime state, so a project can override behavior without rebuilding the runtime architecture first.