This guide walks you through turning this starter into a working theme: you’ll create a personalized Acme Blog theme, activate it on a local WordPress site, and confirm a source-code edit shows up on the frontend. By the end, you’ll have the theme running locally and a repeatable checklist for the workflows that follow. Run commands from the theme directory unless a step says otherwise.
.nvmrc — use nvm or another Node version manager to select itwp-env routeAn existing local WordPress installation can replace wp-env; Docker is still needed for this repository’s container-based PHP test command.
For a standalone project, run this from the directory that will contain it. Composer gives you a copy without the starter’s Git history and installs its dependencies, so you can skip step 2:
composer create-project rtcamp/theme-elementary acme-blog
cd acme-blog
git init
git add .
git commit -m "chore: start from theme-elementary"
Or clone the repository:
git clone https://github.com/rtCamp/theme-elementary.git acme-blog
cd acme-blog
The theme’s install hook runs npm i during create-project, so have Node 22.22.2 or later active first. The first commit gives the Composer copy a baseline, so git status shows what init changes in step 3.
With nvm, select the project’s Node version:
nvm install
nvm use
If you’re on VIP, follow the VIP local-development guide for project-level setup; this guide covers only the theme-local steps.
composer install
Composer’s install hook also runs npm i, which runs sync-ai. Do not repeat npm installation immediately afterwards. If you used Composer’s --no-scripts option, run npm install separately.
Resolve installation errors before continuing; see initialization troubleshooting.
Review git status and resolve unrelated changes before running:
npm run init
Use Acme Blog as the theme name. For this first walkthrough, keep the examples and the default feature selection: HMR on, Tailwind off. The initialization guide explains each decision, including cleanup and optional Git initialization.
Alternatively, open the clone in your AI assistant and ask:
/init Set up this theme as "Acme Blog". Keep the examples and default features.
Use one route. The AI route can handle dependency installation too if you start it before step 2.
Using a different AI assistant?
/initand/scaffoldare Claude Code skills. AGENTS.md is the tool-agnostic source of truth, with matching Copilot prompts in.github/prompts/; with another tool, describe the task and use the CLI route instead.
Review the resulting style.css, Composer namespace, .wp-scaffold.json, and removed files. Initialization changes the display name; the theme’s directory remains acme-blog. A baseline commit after this review gives you a useful checkpoint before feature development.
For a standalone project, use the bundled wp-env route below. If the theme is inside an existing WordPress repository, skip the bundled wp-env route and start that repository’s environment using its own instructions. Use its activation command and site URL, and run npm run build:dev from the theme directory.
wp-env routeThe committed .wp-env.json mounts the theme, uses PHP 8.2, and sets the development port. The PHP tests run in a separate environment configured by .wp-env.tests.json.
From the theme directory, run:
npm run wp-env start
npm run wp-env run cli -- wp theme activate acme-blog
npm run build:dev
For the standalone wp-env route, open the local site and WordPress admin. A fresh wp-env installation uses admin / password. Under Appearance, confirm Acme Blog is active, then open the Site Editor and check that the theme templates load.
If your folder has another name, use that exact name in the activation command. For an existing WordPress environment, open its configured site and admin URLs; confirm the theme is active and its templates load in the Site Editor there.
Start the theme asset watcher:
npm run start:assets
In src/css/frontend/styles.scss, temporarily add body { outline: 3px solid red; }. Wait for a successful rebuild and refresh the frontend. Remove the rule after checking it. Stop the watcher with Ctrl+C.
Manual refresh works without further configuration. Local development shows how to enable automatic reload, watch custom blocks, run checks, and create a production build.
The theme is now running locally with a source-to-frontend edit confirmed — you’re ready to build on it.
Next, explore the supplied features, generate a feature, or extend the theme manually.