Create WordPress Site Editor Theme

A CLI tool that generates a WordPress block theme from the wp-site-editor-theme-scaffold base theme, renamed and ready to build.

Features

• Copies the complete scaffold: theme.json, block templates and parts, PHP patterns, SCSS, @wordpress/scripts build, phpcs/PHPStan/ESLint/Stylelint config, wp-env test sites, CI and release workflows, Playground blueprint
• Rewrites the theme name, slug, text domain, PHP namespace and function prefixes in every file, including workflows, wp-env configs, bin/ scripts, the .pot header and the phpcs ruleset
• Validates every value the same way whether it comes from a prompt or a flag, and escapes it correctly for XML, JSON and gettext
• Writes a fresh README for the new theme
• Fully non-interactive with --yes, for scripts and CI

Requirements

• Node.js 18 or higher for the generator
• The generated theme targets WordPress 6.6+ and PHP 7.4+, and builds on the Node version in its .nvmrc

Usage

NPX (no installation)

npx create-wp-site-editor-theme "My Theme"

Global installation

npm install -g create-wp-site-editor-theme
create-wp-site-editor-theme "My Theme"

Interactive mode

Run without arguments to be prompted for every value:

create-wp-site-editor-theme

You will be asked for the theme name, slug (derived from the name), PHP namespace (PascalCase of the slug), author, author URI, an optional theme URI and a description. Prompts need a terminal; in a pipe or CI, pass the values as options or use --yes.

Command line options

create-wp-site-editor-theme "My Theme" \
  --slug=my-theme \
  --namespace=MyTheme \
  --author="Your Name" \
  --author-uri="https://example.com/" \
  --theme-uri="https://github.com/you/my-theme" \
  --description="A custom WordPress Site Editor theme." \
  --git \
  --install \
  --yes

| Option | Description | | --------------------------------- | ------------------------------------------------------------------------------------------------- | | [theme-name] | Name for your WordPress theme (required with --yes) | | -s, --slug <slug> | Theme slug: lowercase letters, numbers and single hyphens, starting with a letter. Default: derived from the name | | -n, --namespace <namespace> | PHP namespace, PascalCase. Default: derived from the slug | | -a, --author <author> | Theme author name | | -u, --author-uri <uri> | Theme author URI | | -t, --theme-uri <uri> | Theme URI. Empty (the default) removes the line from style.css | | -d, --description <description> | Theme description | | -g, --git | Run git init in the new theme | | -i, --install | Run npm install in the new theme | | -y, --yes | Non-interactive: use defaults for anything not passed and skip the confirmation |

Invalid option values are rejected with a message rather than rewritten. The theme is created in ./<slug>; if generation fails part-way the directory is removed again.

Generated theme

my-theme/
├── .github/              # ci.yml, release.yml, Playground blueprint
├── bin/                  # wp.sh, validate-blocks, seed, smoke, a11y, export scripts
├── inc/setup.php         # Theme setup and asset enqueueing
├── languages/my-theme.pot
├── parts/                # Template parts (thin shells)
├── patterns/             # PHP patterns holding the block markup
├── src/                  # SCSS (and future JS/blocks)
├── templates/            # Block templates
├── .wp-env.json          # Local test site: npm run wp-env:start
├── CLAUDE.md             # Architecture notes for Claude Code
├── functions.php
├── package.json
├── style.css
└── theme.json

After generating:

cd my-theme
npm install
composer install
npm run build          # dist/ is not committed; the theme has no CSS until it is built
npm run start          # watch mode

Then copy or symlink the folder into wp-content/themes/my-theme and activate it, or run npm run wp-env:start for a Docker site with the theme already active. See the generated README and CLAUDE.md for the full command list (linting, block validation, smoke and accessibility checks, releases).

Development of this generator

git clone https://github.com/philhoyt/create-wp-site-editor-theme.git
cd create-wp-site-editor-theme
npm install
npm run prepare-scaffold   # copy the base theme into scaffold/ (see below)
npm test
node bin/cli.js "My Theme Name"

Updating the bundled scaffold

scaffold/ is a copy of the base theme, refreshed from a local clone:

npm run prepare-scaffold                    # default path, or $SCAFFOLD_SOURCE
npm run prepare-scaffold -- ../path/to/clone

The script skips node_modules, .git, vendor, dist, build, plans, .claude, docs and .DS_Store (the list lives in lib/excludes.js, shared with the CLI), renames .gitignore to gitignore because npm never publishes a nested .gitignore (the CLI renames it back), and fails if a required file such as .github/workflows/release.yml is missing. It also runs automatically before npm publish.

Tests

npm test generates themes with awkward input (ampersands, quotes, $&), asserts that nothing from the base theme's identity survives, parses every JSON file, runs php -l over the PHP when PHP is available, checks the non-interactive and validation paths, and verifies the npm tarball contents with npm pack --dry-run.

License

MIT