Architecture and Packages

Architecture & Packages

A contributor-facing tour of the StrataWP monorepo: how the workspace is organized, how the packages depend on one another, and what each one is responsible for.

This page is for contributors and anyone who wants to understand StrataWP's internals. If you just want to build a theme, start with Installation & Quick Start and Core Concepts instead.

The monorepo at a glance

StrataWP is a monorepo managed with Turborepo on top of pnpm workspaces. The root package is private (@stratawpji/root, version 2.0.0) and is never published — it exists only to orchestrate the workspace.

Two workspace globs define what lives inside (pnpm-workspace.yaml):

packages:
  - 'packages/*'
  - 'examples/*'

• packages/* — the publishable libraries and tools (CLI, core PHP framework, Vite plugin, sync, headless, explorer, testing, MCP, and the create-stratawp wrapper).
• examples/* — the three reference themes (basic-theme, advanced-theme, store-theme) that double as integration fixtures. See Example Themes.

Why Turborepo + pnpm

• pnpm provides content-addressable installs and workspace:* linking, so packages resolve their siblings from source during development.
• Turborepo runs tasks across the graph in dependency order, with caching. The pipeline is defined in turbo.json:

Task	Behavior
build	dependsOn: ["^build"] — builds dependencies first; outputs dist/**, build/**, .next/** (excluding .next/cache/**).
dev	cache: false, persistent: true — long-running dev servers.
test	dependsOn: ["build"]; outputs coverage/**; inputs scoped to src/** and test/** (.ts/.tsx).
lint	No cached outputs.
typecheck	dependsOn: ["^build"] — typed after dependencies are built.
clean	cache: false.
e2e	cache: false.

The ^build prefix means "build everything this package depends on first" — that ordering is the backbone of how the packages compose.

Note: The repo pins pnpm@8.12.1 and the root engines require node >=18.18 and pnpm >=8.0.0. Use the pinned package manager to avoid lockfile churn.

Root scripts contributors use most

From the root package.json:

Script	What it does
pnpm dev / pnpm build / pnpm test / pnpm typecheck	Fan out to Turborepo across the workspace (turbo dev / turbo build / turbo test / turbo typecheck).
pnpm lint / pnpm lint:fix	ESLint over the repo (eslint . / eslint . --fix).
pnpm lint:php	PHP linting via scripts/lint-php.mjs.
pnpm test:e2e	Playwright accessibility suite in examples/basic-theme (playwright.a11y.config.ts).
pnpm format / pnpm format:check	Prettier over **/*.{ts,tsx,md,json}.
pnpm changeset / pnpm version-packages / pnpm release	Versioning and publishing via Changesets.
pnpm contracts:check / contracts:validate / contracts:types:check	Contract and type-drift checks (scripts/check-contracts.mjs, scripts/validate-contracts.mjs, scripts/check-types-drift.mjs).

pnpm release runs turbo build && changeset publish. See Contributing & Releases.

How the packages depend on each other

The packages form a small, intentional dependency graph rather than one monolith. At a high level:

create-stratawp ──▶ @stratawp/cli
                          │
                          ├──▶ @stratawp/explorer   (bundled: launches the component browser)
                          └──▶ @stratawp/sync       (bundled: DB sync, snapshots, rollback)

@stratawp/mcp ──▶ @stratawp/cli        (wraps generators as MCP tools)
              └─▶ @stratawp/explorer   (exposes the component catalog as MCP resources)

A generated theme depends on:
  @stratawp/vite-plugin   (build-time: HMR, block discovery, asset manifest)
  @stratawp/core          (runtime PHP: component architecture, asset enqueuing)
  @stratawp/testing       (dev: Vitest/Playwright utilities)   [optional]
  @stratawp/headless      (for decoupled/Next.js front-ends)   [optional]

A few relationships are worth calling out:

• create-stratawp is a thin shim. Its only dependency is @stratawp/cli (workspace:*); it installs and delegates to the CLI so npx create-stratawp my-theme always runs the current generator logic.
• @stratawp/cli bundles @stratawp/explorer and @stratawp/sync as direct dependencies, which is why stratawp explorer, stratawp deploy, stratawp sync:db:*/sync:templates, and stratawp rollback:* all work from a single install.
• @stratawp/mcp depends on both @stratawp/cli and @stratawp/explorer, re-exposing the CLI's generators as MCP tools and the explorer's discovery as MCP resources. See AI, Agent Skills & MCP.
• @stratawp/core is the only PHP package — it is installed in a theme via Composer (composer require stratawp/core), not npm, and stands apart from the JS dependency graph.

High-level data flow

The build- and run-time pieces fit together like this:

1. Authoring. You edit PHP, SCSS, and TypeScript/React in a theme. @stratawp/vite-plugin watches files, provides HMR for JS/CSS/PHP, and discovers Gutenberg blocks by scanning src/blocks/**/block.json.
2. Build output. The Vite plugin emits a WordPress-compatible asset manifest (file hashes, CSS dependencies, WP script deps such as wp-element/wp-blocks, and version strings) plus generated PHP block-registration code.
3. Runtime. In the theme's functions.php, @stratawp/core reads that manifest. Its built-in components enqueue the Vite-built assets, auto-register the discovered blocks, and apply performance optimizations — each feature being a self-initializing ComponentInterface.
4. Quality. @stratawp/testing supplies shared Vitest/Playwright config files, WordPress mocks, and custom matchers; @stratawp/explorer renders blocks/components/patterns/templates for live inspection.
5. Ship. @stratawp/cli (via the bundled @stratawp/sync) deploys over FTP/SFTP/SSH/Git, syncs the database and FSE templates, and snapshots before each deploy for rollback. See Deployment and Environment Sync & Rollback.

Per-package reference

Versions are taken from each package's package.json. @stratawp/core is a Composer package (stratawp/core) with no semver pinned in its composer.json.

Package	Version	Responsibility	Key entry points	README
@stratawp/cli	2.0.0	The primary command-line tool to create and manage StrataWP themes. Drives scaffolding (block:new/component:new/template:new/part:new), dev/build, design-system setup, deployment (FTP/SFTP/SSH/Git targets via FTPDeployer/SSHDeployer), database sync, rollback, and icon-font management. Bundles @stratawp/explorer and @stratawp/sync. Built on Commander.	Bins stratawp and create-stratawp; package exports . and ./generators (programmatic generators). Commands registered in src/index.ts; implementations in src/commands/* (block, component, template, part, design-system, dev, build, test, deploy/, sync, rollback, icons, update). Invocations are colon-namespaced, e.g. block:new, deploy:setup, sync:db:pull, rollback:list, icons:setup.	No README — described from src + package.json.
@stratawp/core	(Composer stratawp/core, unversioned)	The PHP framework (PHP 8.1+). Provides a component-based theme architecture where every feature is a ComponentInterface with a unique slug that self-initializes via WordPress hooks. Ships built-in components (e.g. Setup, Assets, Blocks, Performance, plus Accessibility, Fonts, Icons, Image sizes, Critical CSS, and more under src/Components/). PSR-4 autoloaded under StrataWP\.	StrataWP\Theme (->initialize(), ->template_tags()); stratawp() global helper (Theme::instance()); ComponentInterface (get_slug(), initialize()). Installed via composer require stratawp/core.	README
@stratawp/vite-plugin	0.2.0	Vite plugin for WordPress theme development: HMR for JS/CSS/PHP, Gutenberg block auto-discovery (scans src/blocks/**/block.json and generates PHP registration), PHP file watching/reload, and a WordPress-compatible asset manifest. Peer dependency on Vite ^5.	Plugin factory exported from ..	README
@stratawp/sync	0.1.0	Environment sync, deployment snapshots, and rollback. Handles MySQL dump/restore (direct or over SSH), serialization-safe URL replacement, and snapshot create/list/compare/restore plus a file/SQL diff engine. Integrates with stratawp deploy for automatic pre-deploy snapshots.	Exports ., ./database, ./snapshots, ./diff. APIs: DatabaseDumper, SSHDatabaseDumper, DatabaseRestorer, UrlReplacer (./database); SnapshotManager (./snapshots); DiffEngine (./diff).	README
@stratawp/headless	0.8.0	Headless/decoupled WordPress utilities for React/Next.js front-ends against the WP REST API: a typed REST client, React hooks, Next.js integration, SEO metadata, and image helpers.	Exports ., ./react, ./next. APIs: WordPressClient; preview, SEO, and image utilities; full WP* types. React hooks and Next helpers live under the ./react and ./next subpaths.	README
@stratawp/explorer	0.7.0	Interactive, Storybook-style component explorer for StrataWP block themes. Auto-discovers blocks, React components, patterns, templates, and parts; live preview with viewports, attribute controls, and source viewing; hot reload via an Express REST API and a WebSocket channel.	Launched via stratawp explorer (alias storybook), port 3000 by default. Programmatic: ExplorerDevServer, ComponentDiscovery (discoverAll(), watch()). REST: GET /api/components, /api/components/:id, /api/components/:id/source, /api/health.	README
@stratawp/testing	0.1.0	Testing utilities for StrataWP themes: Vitest unit testing with WordPress JS API mocks, Playwright E2E helpers, WordPress custom matchers, and shareable Vitest/Playwright config files (vitest.config.ts, playwright.config.ts shipped in the package).	Exports ., ./vitest, ./playwright. Vitest side: setupWordPressMocks/clearWordPressMocks, renderBlockEdit/renderBlockSave, testBlockRegistration, block matchers (toHaveBlockClass, toBeRegisteredBlock, etc.). Playwright side: wpLogin, openBlockEditor, insertBlock, getBlock, axe helpers.	README
@stratawp/mcp	0.1.0	MCP (Model Context Protocol) server that exposes the framework's generators and component catalog to AI agents. Built on @modelcontextprotocol/sdk with zod schemas; wraps @stratawp/cli generators as tools and @stratawp/explorer discovery as resources. Ships a contract snapshot (contracts/tools.snapshot.json) for tool-surface stability.	Bin stratawp-mcp. Tools: scaffold_block, scaffold_component, scaffold_template, scaffold_part. Resources: stratawp://components, stratawp://components/{id}, stratawp://components/{id}/source.	No README — described from src + package.json.
create-stratawp	0.5.2	A thin one-command wrapper (npx create-stratawp my-theme) that installs and runs @stratawp/cli to scaffold a new theme. Its only source file is index.js; its sole dependency is @stratawp/cli.	Bin create-stratawp → resolves and imports @stratawp/cli/dist/create.js. Node 18+.	README

Tip: During local development the workspace:* links mean a change in, say, @stratawp/vite-plugin is picked up by a theme without republishing — just rebuild (pnpm build, or turbo build for the affected package and its dependents).

Where to go next

• Commands and flags for every tool above — CLI Reference.
• The component model in @stratawp/core — Core Concepts.
• Folder layout of a generated theme — Project Structure.
• Deployment, sync, and rollback internals — Deployment and Environment Sync & Rollback.
• The MCP server and bundled agent skills — AI, Agent Skills & MCP.
• Adding a package or cutting a release — Contributing & Releases.