Getting Started Guide

This guide is designed to help you quickly set up the development environment for the WP Scratch theme. Whether you are starting fresh or returning to the project after a break, follow these steps to get back to a working state.

Prerequisites

Before you begin, ensure you have the following installed:

Local WordPress Environment: We recommend LocalWP.
Node.js & NPM: Required for Tailwind CSS and build tools. Download from nodejs.org.
Visual Studio Code: Recommended IDE.
PowerShell: Required for running the utility scripts (standard on Windows).

Step-by-Step Setup

1. Clone & Install

Clone the Repository: Clone this theme repository into your local WordPress site's themes directory (e.g., .../app/public/wp-content/themes/wp-scratch).
Open in VS Code: Open the wp-scratch folder in Visual Studio Code.
Scaffold Configuration: If this is a fresh clone, you might be missing local configuration files (like .env, tailwind.config.js, etc.). We have a utility script to generate these for you.

Run the following command in your terminal:
```
npm run scaffold
```
This will generate a /generated folder containing all necessary config files. You can then copy the ones you need into the root directory.
Install Dependencies: Now that your package.json is ready (or generated), install the Node.js dependencies:
```
npm install
```
This downloads Tailwind CSS, PostCSS, and other build tools into node_modules.

2. Configure Environment

Setup .env: If you haven't already, create a .env file in the theme root (or copy from /generated/.env).
- SITE_URL: Update this to match your LocalWP site URL (e.g., http://wp-scratch.local). This is critical for the "Critical CSS" generation.
- FTP Credentials: If you plan to use the deployment script, add your FTP details here.
Tailwind Configuration: Ensure tailwind.config.js exists in the root. This file controls your design system.
- Tip: If you need to reset to the default configuration, you can grab the boilerplate from /generated/tailwind.config.js after running the scaffold script.

3. Start Development

Start the Watcher: Run the development server to watch for changes in your files and automatically rebuild the CSS:
```
npm run dev
```
You should see a message indicating that Tailwind is watching for changes.
Verify Sync:
- Open src/input.css and add a test style or modify a class in a template file.
- Check style.css to ensure it updated.
- Refresh your local WordPress site to see the changes.

4. Theme Configuration (`theme.json`)

The theme.json file is the source of truth for your WordPress editor styles (colors, fonts, layout).

Syncing: We manually sync theme.json settings with tailwind.config.js to ensure the editor and front-end match.
Colors: Defined in settings.color.palette.
Typography: Defined in settings.typography.

Common Tasks

Create a New Block:

.\scripts\newblock.ps1 -Name "my-new-block"

Build for Production:
```
npm run build
```
This minifies CSS and generates Critical CSS.
Bundle & Deploy:
```
npm run bundle -- -Upload
```
Zips the theme and uploads it to the FTP server defined in .env.

Created: March 17, 2026 • Last Modified: February 22, 2026

Docs Login