Skip to content

Installation and Quick Start

Jump to bottom
Jon Imms edited this page Jun 25, 2026 · 1 revision

Installation & Quick Start

Zero-to-running: install the toolchain, scaffold a theme with create-stratawp, link it to WordPress, and start the hot-reload dev server.

This is the definitive setup guide. Every step is copy-pasteable, with expected results and "if this fails" notes. New to the framework? Skim Core Concepts afterward, or jump straight to Blocks, Patterns & Design Systems.

1. Prerequisites

You need a few tools installed before scaffolding a theme.

Required

Tool Minimum version Check with
Node.js 18 (the monorepo engines field requires >=18.18) node -v
pnpm (recommended) or npm pnpm >=8.0.0 pnpm -v
PHP 8.1 php -v
WordPress 6.7 WP Admin → bottom-right footer, or wp core version
Local WordPress environment — see options below

Run the checks:

node -v
pnpm -v
php -v

Expected output (your exact versions may differ, but they must meet the minimums above):

v20.11.1
8.12.1
PHP 8.2.13 (cli) (built: ...)

Note php -v shows your command-line PHP. Your local WordPress stack may bundle its own PHP version — that's the one that actually runs your theme. Confirm it in your local environment's settings. The scaffolded theme also enforces PHP 8.1+ at runtime (functions.php calls wp_die() on older versions).

Install pnpm (if pnpm -v failed)

npm install -g pnpm

Re-run pnpm -v to confirm.

Tip pnpm is recommended (the monorepo is pinned to pnpm@8.12.1), but npm works too. This guide uses pnpm throughout.

A local WordPress development environment

You need WordPress running locally. Any of these work:

  • Local by Flywheel — easiest for beginners; StrataWP auto-detects its sites.
  • MAMP — StrataWP auto-detects its htdocs installs (macOS).
  • Docker (including @wordpress/env) — fully supported; you'll link the theme manually.
  • Other (Valet, XAMPP, a custom stack) — supported; link manually.

Note where your WordPress lives — you'll need the wp-content/themes/ path if auto-detection doesn't find it. Typical locations:

Environment Typical WordPress root
Local by Flywheel ~/Local Sites/<site>/app/public
MAMP /Applications/MAMP/htdocs/<site>
Docker /var/www/html (inside the container)

Recommended

  • VS Code with the ESLint, Prettier, PHP Intelephense, and TypeScript and JavaScript Language Features extensions.
  • Basic familiarity with JavaScript/TypeScript, React, WordPress Block Themes (FSE), and the command line.

2. Where to work (read this first)

Warning Do not create your theme directly inside wp-content/themes/. Build it in a separate projects folder (e.g. ~/Projects) and let StrataWP symlink it into WordPress. This keeps source control clean and updates painless.

mkdir -p ~/Projects
cd ~/Projects

All commands in this guide run from your development directory, not from inside WordPress.

3. Create a theme with create-stratawp

The fastest path is the interactive scaffolder. create-stratawp is a thin wrapper that installs and runs @stratawp/cli for you — no global install required.

Step 1 — Run the scaffolder

From ~/Projects (outside any WordPress directory):

npx create-stratawp my-theme

Note The wizard asks you for the theme slug (the directory name) as one of its prompts, defaulting it from the theme name you enter. The my-theme you type on the command line is the conventional invocation shown in the package's own docs — but the directory that gets created is whatever you confirm at the slug prompt.

Step 2 — Answer the interactive prompts

The wizard walks you through each choice in order. Here's what each one means and its built-in default:

Prompt Default What it does
Theme name My Awesome Theme Written into style.css and package.json.
Theme slug (directory name) derived from the name The folder created and the theme's text domain. Must be a valid package name.
Description A theme built with StrataWP Written into style.css and package.json.
Author name — Written into style.css and package.json.
Choose a starting template Basic Theme The starting point copied from bundled templates (see below).
CSS Framework UnoCSS Your styling layer. Options: Vanilla CSS (custom properties), Tailwind CSS, UnoCSS, Panda CSS.
Use TypeScript? yes Type-safe blocks and components.
Include testing setup? yes Adds testing scaffolding (see Testing & Quality).
Link this theme to a WordPress installation? yes Symlinks the theme into a detected WP install (runs after files are generated).

Template choices explained:

  • Basic Theme (Recommended) — general-purpose starter (blogs, business sites, learning). Built on the Frost design system with 50+ block patterns, 9 FSE templates, and light/dark variants.
  • Advanced Theme — enterprise features: 4 custom post types (portfolio, team, testimonial, case study), custom blocks (Portfolio Grid, Team Members), an Advanced Layouts component, and a Meta Boxes system.
  • Store Theme — WooCommerce: shop, single-product, archive-product, cart, and checkout templates plus e-commerce patterns.
  • Minimal — start from scratch with a minimal generated structure.

Tip Unsure? A safe beginner pick is Basic Theme, Vanilla CSS, TypeScript: yes. (The wizard's own defaults select UnoCSS for CSS and yes for testing — override them at the prompt if you'd rather start simpler.) You can add a design system later with stratawp design-system:setup.

Step 3 — Let the CLI link WordPress

After the files are generated and dependencies installed, the CLI offers to auto-detect and link your install. It scans for a wp-config.php under:

  • Local by Flywheel sites — ~/Local Sites/<site>/app/public
  • MAMP installations (macOS) — /Applications/MAMP/htdocs/<site>

Select your site from the list and the theme is symlinked into that site's wp-content/themes/ automatically.

If no sites are detected, create the symlink yourself. Run this from your theme directory, pointing at your WordPress themes folder:

ln -s "$(pwd)" /path/to/wordpress/wp-content/themes/my-theme

For Local by Flywheel the path looks like:

ln -s "$(pwd)" ~/Local\ Sites/mysite/app/public/wp-content/themes/my-theme

Verify the link exists:

ls -la /path/to/wordpress/wp-content/themes/

You should see my-theme -> /Users/you/Projects/my-theme in the listing.

What the CLI auto-detects and sets up

In one run, create-stratawp:

  • Copies your chosen template from bundled sources and customizes style.css, package.json, and README.md with your name/description/author/slug.
  • Installs dependencies with pnpm install.
  • Detects your local WordPress install and symlinks the theme in (if you opt in).

4. Move into your theme

cd my-theme

A scaffolded theme (Basic template) looks like this:

my-theme/
├── inc/                      # PHP
│   ├── Components/           # Namespaced theme components (Navigation, Customizer, ...)
│   └── *-generated.php       # Vite-generated block/asset registration
├── patterns/                 # Block patterns (*.php)
├── parts/                    # Template parts (header, footer, ...) (*.html)
├── src/                      # Front-end source
│   ├── blocks/               # Gutenberg blocks
│   ├── css/                  # Plain CSS entry stylesheets
│   ├── scss/                 # SCSS partials + main.scss
│   ├── js/                   # main.ts (front end) + editor.ts (editor)
│   └── icons/                # Icon assets
├── templates/                # FSE templates (*.html)
├── functions.php             # Theme entry point (loads Composer autoloader + inc/Components)
├── style.css                 # Theme header
├── theme.json                # FSE configuration / design system
├── composer.json             # PHP dependencies (autoloading for inc/Components)
├── package.json              # Dependencies and scripts
├── tsconfig.json             # TypeScript config
└── vite.config.ts            # Vite + @stratawp/vite-plugin configuration

Note The PHP components in inc/Components/ are loaded through the Composer autoloader, so run composer install (in addition to pnpm install) if your environment didn't already vendor them.

For a full walkthrough of each directory, see Project Structure.

5. Start the dev server

pnpm dev

Expected: Vite starts and reports the dev server on http://localhost:3000 (the port is fixed via strictPort).

Warning Keep this terminal window open. The dev server must run continuously for hot-reload to work. Open a second terminal tab for other commands.

Note http://localhost:3000 is the Vite dev/HMR server. You still browse and preview your site at your WordPress URL (for example http://localhost:8888 or your Local site's address) — Vite's HMR client is injected into that page.

What HMR gives you

StrataWP's dev server reacts to the kind of change you make:

You change… What happens
CSS / SCSS imported through the JS entry Hot update via Vite HMR (no full reload)
TypeScript / JavaScript Fast rebuild and module update
PHP Full page reload (PHP HMR)
theme.json Full page reload
FSE templates (templates/**) and parts (parts/**) Full page reload

The @stratawp/vite-plugin PHP-HMR watcher sends a full-reload to the browser when any watched PHP file, theme.json, template, or part changes. Edit a file, save, and watch the change appear in your WordPress browser tab.

If pnpm dev fails with "Port 3000 is already in use", free the port or run on another one:

pnpm dev --port 3001

(The dev server uses strictPort, so it errors instead of silently picking a different port.)

6. Activate the theme in WordPress

  1. Open your WordPress site in a browser.
  2. Go to WordPress Admin → Appearance → Themes.
  3. Find your theme (the name you entered in Step 2) and click Activate.

Verify it worked

  • The theme card shows Active in Appearance → Themes.
  • Visit your site's front end — you should see the template you scaffolded.
  • With pnpm dev running, make a small edit (e.g. change a heading in templates/index.html), save, and confirm the page reloads with the change.

If the theme doesn't appear in WordPress admin:

  1. Confirm the symlink exists: ls -la /path/to/wordpress/wp-content/themes/
  2. Confirm style.css has a valid theme header (Theme Name: line).
  3. Check file permissions on the symlink target.

7. What just happened (recap)

In a handful of commands you:

  1. Verified prerequisites — Node 18+, pnpm, PHP 8.1+, WordPress 6.7+.
  2. Scaffolded a theme with npx create-stratawp my-theme, choosing a name/slug, template, CSS framework, TypeScript, and testing.
  3. Linked it to WordPress — auto-detected and symlinked, or linked manually with ln -s.
  4. Started Vite with pnpm dev on http://localhost:3000, enabling HMR for styles and JS/TS and full reloads for PHP, theme.json, templates, and parts.
  5. Activated the theme in WP Admin and confirmed live hot-reload.

You now have a TypeScript-first, Vite-powered Block Theme (FSE) running with hot reload.

8. Next steps

Quick reference

# Create a new theme (run from OUTSIDE any WordPress directory)
npx create-stratawp my-theme

# Inside the theme directory
pnpm dev          # Start dev server (http://localhost:3000) with HMR
pnpm build        # Production build
pnpm preview      # Preview the production build locally
pnpm typecheck    # TypeScript validation (tsc --noEmit)

Troubleshooting

Quick fixes for common setup snags:

Symptom First thing to try
Port 3000 is already in use pnpm dev --port 3001 (or free port 3000)
Hot reload not updating Confirm pnpm dev is running, hard-refresh (Cmd/Ctrl+Shift+R), check the browser console
Theme missing in WP admin Verify the symlink and style.css header (Step 6)
TS2307: Cannot find module rm -rf node_modules && pnpm install, then pnpm typecheck
Build fails rm -rf node_modules dist .vite && pnpm install && pnpm build
PHP class not found / autoload error Run composer install in the theme directory

For the full list, see FAQ & Troubleshooting, or consult the canonical Getting Started guide in the repository.

StrataWP v2.0.0 · GPL-3.0-or-later · Built by Jon Imms Repository · README

Home

Start here

Building themes

Shipping

Extending & contributing

Help

Clone this wiki locally