Quickstart

This page walks the order of work for a new project, including the one decision you cannot take back. The CLI reference has every flag; this is the narrative.

1. Choose a backend, build the environment

Wonderpress supports two environment backends. You choose once, at init, and the choice is recorded in .wonderpressrc so every later command knows what kind of project it is working in.

  • host (the default). WordPress runs against a MySQL you provide, served by wonderpress server in the foreground. Use this when you already have a local LAMP-ish setup you like.
  • wp-env. WordPress runs in Docker containers via @wordpress/env, on port 8888 with sensible debug flags (WP_DEBUG, WP_DEBUG_LOG, SCRIPT_DEBUG) already on. Use this when you want zero local MySQL administration.

You can override the backend for a single invocation with the WONDERPRESS_ENV environment variable, though you will rarely need to.

code
wonderpress init --dir ~/projects/acme --env wp-env --namespace acme --theme acme

That clones the development environment, downloads WordPress, creates the database, installs wonderpress-core at its pinned version, installs Static Kit, and activates the theme. On the wp-env backend the site is already serving when it finishes. On host, start it yourself:

code
wonderpress server

Compile or watch assets from the same root:

code
wonderpress static compilewonderpress static compile --watch

Resist the urge to cd into wp-content/themes/<theme>/static to run Static Kit directly. That tree belongs to Static Kit; the wonderpress static compile command exists so you never have to leave the project root.

Pass --yes to skip the wizard and take defaults, which is how scripts and agents run it.

2. The one decision you cannot take back

--namespace. Blocks are emitted as <namespace>/<slug>, and WordPress writes that string into page content:

code
<!-- wp:acme/pull-quote {"quote":"…"} /-->

That makes the namespace a commitment to content rather than a naming preference. Change it later and every block already placed on every page becomes unrecognized. The content survives, and WordPress no longer knows what renders it.

Give it the client’s name. It defaults to the theme slug, and it is pinned in .wonderpressrc at init so it cannot drift afterwards.

Everything else on this page can be changed whenever you like.

3. Set up the design tokens

Put the brand in wp-content/themes/<theme>/theme.json: the palette, the font families, the type scale under settings.custom.type, and status colors under settings.custom.color. This file is the source of truth, and it is what constrains the editor. It is the reason a client’s color picker offers your swatches instead of the spectrum.

wonderpress-core bridges those values to the CSS variable names Static Kit’s token files already consume, so your SCSS and the block editor stay in agreement automatically. The full mechanics (and the honest costs) are in Design tokens.

4. Curate the editor

A stock WordPress offers 117 blocks. Once you know which ones the client actually needs, in the theme’s functions.php:

code
define( 'WONDERPRESS_CURATE_BLOCKS', true );

That narrows the inserter to your own blocks plus a small core set. It governs what can be inserted, so it is safe to turn on mid-project. Details in Curating and locking the editor.

5. Build a component

code
wonderpress partial create --name Pull_Quote --block \  --prop "quote:string:required" --prop "attribution:string"

A partial is the unit of markup, a PHP class plus a view template. --block also exposes it in the editor; leave it off for partials you only compose from other partials, which is most of them.

Declared properties arrive in the view as plain local variables:

code
<blockquote class="pull-quote">	<p><?php echo esc_html( $quote ); ?></p>	<?php if ( ! empty( $attribution ) ) : ?>		<cite><?php echo esc_html( $attribution ); ?></cite>	<?php endif; ?></blockquote>

wonderpress partial list shows everything the CLI has made, and flags any block it did not write as (no manifest). WordPress registers those too, and the CLI cannot manage or remove them.

6. Check it in the editor

Open any page and insert your block. You should see:

  • the block in the inserter, under a category named after your project
  • the block’s actual design rather than a grey placeholder

If you get a placeholder, the editor script did not load. Check that the theme’s vendor/ directory exists and that the browser console is clean. The preview works by asking WordPress to render the block over REST, so the PHP partial stays the only source of markup.

7. Let your agents in

wonderpress init already wrote AGENTS.md at the environment root, a one-line CLAUDE.md that points at it, and MCP server configs for Claude Code, Cursor, VS Code, and Codex. Open the environment root in your editor of choice and approve the wonderpress MCP server when asked. See Agents and MCP.

Where to go deeper

  • Common workflows: chunked recipes, including the full composed-page-template build
  • Partials: the authoring model and the manifest-first workflow
  • Page templates: composition, editor locks, and template manifests
  • Working with ACF: installing ACF and locating field groups