Skip to content

Core Concepts

Jump to bottom
Jon Imms edited this page Jun 25, 2026 · 1 revision

Core Concepts

The architectural pillars behind StrataWP — what each one is, why it matters, and how it changes the way you build WordPress themes.

StrataWP is a WordPress theme framework built from the ground up with TypeScript, Vite, and modern tooling. Rather than a single feature, its value comes from a handful of pillars that work together: type safety across both languages, a fast build pipeline, native Full Site Editing, automatic block discovery, hot reloading that extends to PHP, design-system integration, and a monorepo of focused packages.

This page explains the why behind each pillar. For exact commands and flags, see the CLI Reference. To get a theme running first, start with Installation & Quick Start.

TypeScript-First

StrataWP treats TypeScript as the default authoring language across the whole stack — type safety spanning both your PHP framework code and your JavaScript/React block code. Blocks, components, and headless front-ends are written in .tsx/.ts, and the framework ships typed APIs so your editor can catch mistakes before they reach the browser.

Why it matters: WordPress block development involves a lot of loosely-typed surface area (block attributes, editor props, REST responses). Static types turn whole classes of runtime bugs into editor errors. When you scaffold a block, you get a typed Edit component out of the box:

// src/blocks/hero/index.tsx
import { useBlockProps, RichText } from '@wordpress/block-editor'

export default function Edit({ attributes, setAttributes }) {
  const blockProps = useBlockProps()
  return (
    <div {...blockProps}>
      <RichText
        tagName="h1"
        value={attributes.heading}
        onChange={(heading) => setAttributes({ heading })}
        placeholder="Enter heading..."
      />
    </div>
  )
}

Because types live in the source, your editor surfaces attribute and prop mistakes as you write, and a tsc type-check can gate the same errors in CI. For how type-checking and linting fit into the wider quality pipeline, see Testing & Quality.

Vite-Powered Builds and HMR

StrataWP uses Vite as its build engine, delivering fast Hot Module Replacement (HMR) and sub-second rebuilds during development. The dev server runs continuously (pnpm dev), and production bundling, minification, and source maps come from a single pnpm build.

Why it matters: traditional WordPress asset pipelines force a full rebuild-and-refresh loop on every change. With Vite, edits propagate near-instantly, so the feedback loop stays tight while you iterate on blocks and styles.

In practice the dev server treats different file types differently:

Change type Behaviour
CSS / SCSS Instant update, no page reload
TypeScript / JavaScript Fast rebuild and reload
PHP / templates Automatic page refresh (see PHP Hot Reload)

Note The dev server runs at http://localhost:3000 by default, while you view your site at its local WordPress URL (for example http://localhost:8888). Keep the pnpm dev terminal open — HMR only works while the server is running.

The Vite integration lives in the @stratawp/vite-plugin package, configured in your theme's vite.config.ts. See Architecture & Packages for how it fits the rest of the stack.

Block Theme (FSE)

StrataWP themes are Block Themes with Full Site Editing support out of the box. Layout lives in HTML templates and template parts, and global styles, color/spacing/typography presets, and settings live in theme.json.

Why it matters: FSE is WordPress's modern theming model. Building on it means your headers, footers, and page layouts are editable in the Site Editor, and your design tokens are exposed as native WordPress presets that both the editor and the front-end understand.

A scaffolded theme has a predictable layout:

my-theme/
├── inc/Components/   # PHP feature components
├── patterns/         # Block patterns (PHP)
├── parts/            # Template parts (header, footer, …)
├── src/blocks/       # Gutenberg blocks (TypeScript/React)
├── src/scss/         # Styles
├── templates/        # FSE templates (HTML)
├── theme.json        # FSE configuration
└── vite.config.ts    # Build configuration

Templates use standard block markup, so a page template references parts and native blocks directly:

<!-- wp:template-part {"slug":"header"} /-->
<!-- wp:group {"layout":{"type":"constrained"}} -->
<div class="wp-block-group">
  <!-- wp:heading {"level":1} --><h1>About Us</h1><!-- /wp:heading -->
</div>
<!-- /wp:group -->
<!-- wp:template-part {"slug":"footer"} /-->

For a full tour of the directory layout, see Project Structure. For block, pattern, and design-token authoring, see Blocks, Patterns & Design Systems.

Automatic Block Registration

You don't manually wire up your Gutenberg blocks. The Vite plugin scans your src/blocks directory for block.json files and registers them automatically — discovering blocks, generating the PHP registration code, and rebuilding when a block.json changes.

Why it matters: registering blocks by hand means keeping a PHP registry in sync with your block folders, an easy source of drift and "why isn't my block showing up?" bugs. Auto-discovery removes that bookkeeping: drop a block folder in src/blocks, and it's registered.

Auto-registration is enabled through the strataWP plugin in vite.config.ts:

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { strataWP } from '@stratawp/vite-plugin'

export default defineConfig({
  plugins: [
    react(),
    strataWP({
      blocks: {
        dir: 'src/blocks',
        autoRegister: true,
        namespace: 'stratawp',
      },
    }),
  ],
})

Under the hood the plugin scans for block.json, discovers every block, generates the PHP registration, and watches for changes during development. Use stratawp block:new <name> to scaffold a new block in the right place — see CLI Reference.

PHP Hot Reload

HMR in StrataWP extends to PHP. When you edit a PHP template or theme.json, the Vite plugin detects the change and signals the browser to refresh automatically — no manual reload.

Why it matters: PHP changes normally fall outside front-end build tooling, so you'd alt-tab and hit refresh constantly. Watching PHP closes that gap, giving template and component edits the same fast feedback as your CSS and TypeScript.

It's configured through the plugin's phpHmr options:

strataWP({
  phpHmr: {
    enabled: true,
    watch: ['**/*.php', 'theme.json'],
    debounce: 100, // ms
  },
})

The flow is: the plugin detects the file change, debounces it, sends a reload signal to the browser, and the page refreshes. Adjust the watch globs to control which files trigger a reload.

Design Systems with WordPress Preset Mappings

StrataWP can wire a utility-CSS design system — Tailwind CSS or UnoCSS — into your theme, with the key twist that it maps to WordPress presets. Your design system stays in sync with theme.json, so colors, spacing, and typography are shared between your utility classes and WordPress's native preset system.

Why it matters: normally a utility framework and theme.json are two parallel sources of truth for design tokens, and they drift. Mapping them means one definition drives both your authored markup and the Site Editor's global styles, keeping the editor experience and the front-end visually consistent.

Set it up in one step:

stratawp design-system:setup tailwind
# or
stratawp design-system:setup unocss

Tip create-stratawp also offers a CSS-framework choice (vanilla, Tailwind, UnoCSS, or Panda) during the initial wizard, so you can opt in at creation time instead.

For the full workflow and preset-mapping details, see Blocks, Patterns & Design Systems.

The Monorepo

StrataWP is developed as a monorepo managed with Turborepo and pnpm workspaces. The framework is split into focused, independently published packages under packages/, alongside the example themes under examples/.

Why it matters: each capability — the CLI, the Vite plugin, testing, sync, headless, the component explorer — is its own package with a clear boundary. You install only what a given theme needs, packages version independently, and the build graph (via Turbo) only rebuilds what changed.

The published npm packages you'll encounter:

Package Role
@stratawp/cli The stratawp and create-stratawp commands
@stratawp/vite-plugin Vite integration: HMR, block auto-registration, PHP watch
@stratawp/sync Environment sync, snapshots, rollback
@stratawp/testing Vitest and Playwright utilities
@stratawp/headless REST client, React hooks, Next.js integration
@stratawp/explorer Interactive component browser

Note The PHP framework core (the stratawp/core Composer package) also lives in the repo. Distributed via Composer rather than npm, it provides the component-based theme architecture your inc/Components/ build on. A @stratawp/mcp package — an MCP server that exposes the scaffolding generators to AI agents — ships from the same repo.

For a package-by-package breakdown of responsibilities and APIs, see Architecture & Packages.

How the Pillars Fit Together

These concepts compound. TypeScript and Vite give you a fast, type-safe authoring loop; FSE and automatic block registration mean what you author is native WordPress with no manual wiring; PHP hot reload extends the fast loop to server-side code; design-system mapping keeps tokens consistent; and the monorepo packages each of these as a clean dependency you can adopt incrementally.

Where to go next:

StrataWP v2.0.0 · GPL-3.0-or-later · Built by Jon Imms Repository · README

Home

Start here

Building themes

Shipping

Extending & contributing

Help

Clone this wiki locally