What is Wonderpress
Wonderpress is a WordPress development harness built by Wonderful. It gives every project the same spine: one command-line tool, one environment layout, one authoring model for components, and one contract between design tokens and CSS.
WordPress itself has no opinion about how a team should build themes. Every agency invents its own conventions, and then every developer on every project invents small variations on those. Six months later, two sites built by the same team share almost nothing: different folder layouts, different field plugins wired different ways, different build tools, different ideas about what a “component” even is. The cost shows up when someone new opens the repo.
Wonderpress exists to normalize that. A developer who has worked on one Wonderpress site can open any other and already know where everything is, how components are made, and what commands to run. The conventions are enforced by tooling rather than by documentation nobody reads.
One harness, five packages
Wonderpress is delivered as a set of packages. Each works on its own, and each makes the next one better. The CLI assembles all of them into a working project with a single command.
| Package | What it is |
|---|---|
| Wonderpress CLI | The command-line tool. Bootstraps environments, scaffolds components, keeps generated code in sync, and exposes the same operations to AI agents over MCP. |
| Development Environment | The project root: a Wonderpress-flavored directory for a WordPress installation, carrying project-level tooling such as codesniffing configuration and CI. |
| Wonderpress Theme | A boilerplate theme with no predefined styles and no design opinions. Built for developers to develop from the ground up, never configured through the dashboard. |
| Static Kit | A host-agnostic asset toolkit for SCSS, JavaScript, and images. It owns the theme’s static/ directory and compiles one bundle per page. |
| wonderpress-core | The runtime, under the hood. A Composer dependency of the theme that registers blocks, supplies the partial base classes and wonder_* helpers, and bridges design tokens from theme.json into CSS. |
Wonderpress does not include or modify any core WordPress files. WordPress installs and updates around it without special consideration.
The command line is the tool
Everything in Wonderpress routes through the CLI. It builds the environment, scaffolds partials and blocks and page templates, compiles assets, lints the theme, and checks that generated code still matches its source of truth. Interactive wizards exist for humans; every command also runs headless with flags and --format json output for scripts and agents.
npm install -g @wndrfl/wonderpress-cli mkdir acme && cd acme wonderpress init
That one command clones the development environment, downloads WordPress, creates the database, installs the theme’s Composer dependencies (including wonderpress-core) and Static Kit, and activates the theme. A short wizard asks the questions that matter; every answer also exists as a flag, so the whole thing runs headless too.
The CLI also documents itself:
wonderpress # command map wonderpress partial help # authoring model wonderpress init help # environment backends and flags
The authoring model in one paragraph
The unit of markup in Wonderpress is the partial: a PHP class, a view template, and a JSON manifest. A Gutenberg block is an optional thin wrapper whose render delegates back to a partial. Page templates compose partials and record their editor rules in manifests of their own. The manifests are the source of truth: field definitions live in JSON, and the generated PHP class and block.json are regenerated from them. The CLI is the only supported way to create and maintain that graph.
// every dependency is a liability, which is why wonderpress is a complete jerk about them
That attitude runs through the whole system. Blocks render server-side from PHP with one shared editor script and no per-block JSX, no editor bundler. Static Kit ships pages only the CSS and JS they import. The theme’s vendor/ is committed so a deploy is a file copy with no Composer step on the server.
Where to go next
- Installation for requirements and setup
- Quickstart to build a site and your first component
- Architecture for who owns what and why