Overview

Notes:

• We create a WordPress theme, but we strip out most of the default stuff.
• Creating a WordPress theme usually involves creating a bunch of PHP template files. Instead, we write a bunch of React/TypeScript files.
• When a user visits a URL on a site, we let WordPress figure out what should be shown — An archive, a post type, a page, search results, the homepage. We hook into this process, and guide WordPress to look in the views/ folder for .tsx files, rather than PHP templates. This allows us to use the traditional naming conventions of single, front-page, page, single-[post-type], archive-[post-type] etc.
• When the template file has been resolved, the our PHP library automatically looks for an (optional) paired .graphql query file, which specifies a query that should be run, to provide data and content to the frontend.
• When a template has been resolved, a JSON payload is generated, containing the name of the matched template file, the result of the GraphQL query, and other metadata like the page title and OpenGraph data.
• If the page is accessed with ?_props=1, then the request will return the JSON payload directly. This is used when navigating between pages — rather than loading the HTML of the new page, just the JSON payload is loaded — and this tells the browser environment which template component to load and render, and which props to pass to that component.
• Without the ?_props=1, the JSON payload is instead included in a <script> tag, and HTML is returned.

Single-Page Application (SPA Mode)

SPA mode is used when accessing the site directly from a WordPress hosting environment, where server-side JS is not available. So, when accessing a Flywheel or Local site directly.

When accessing a page, the HTML of the page will contain an empty div element, where the frontend application will be rendered.

This mode works fine as a preview, but isn’t great as the primary user-facing frontend, since none of the page content will be included in the output of the page, and users with JavaScript disabled (or, if build issues have occurred) will see a blank white page instead.

When developing locally using Local, you’ll be using this mode when you access the Local site directly — eg. my-site.local. You should instead develop in SSR mode, by running the dev tool and accessing my-site.local:8080, which more accurately reflects the production environment, helping you catch SSR issues.

Server-Side Rendering Mode (SSR Mode)

This mode requires a JavaScript server, and so is only available when running the eddev CLI tool, or after deploying to Vercel or CloudFlare Workers.