Development Setup & Dev Mode

Overview

ThemePlus uses a hybrid build architecture — Vite handles SCSS compilation and the admin panel React app, while wp-scripts (webpack) handles Gutenberg block assets. Both pipelines run in parallel during development. This article covers cloning the repository, installing dependencies, running dev mode, and building for production.

---

Requirements

Tool	Minimum Version
Node.js	18.0.0
npm	9.0.0
PHP	8.0
WordPress	6.0
A local WordPress environment	WP Env, LocalWP, Laragon, or similar

---

Repository Setup

1. Clone the repository

bash

git clone https://github.com/fronttheme/themeplus.git
cd themeplus

2. Install Node dependencies

bash

npm install

This installs both the Vite pipeline dependencies and the @wordpress/scripts package used for block compilation.

3. Place in your WordPress install

The themeplus folder must be located inside your WordPress wp-content/plugins/ directory:

wp-content/
└── plugins/
    └── themeplus/
        ├── src/
        ├── blocks/
        ├── package.json
        └── themeplus.php

Alternatively, symlink the cloned folder into wp-content/plugins/ from anywhere on your machine:

bash

ln -s /path/to/themeplus /path/to/wordpress/wp-content/plugins/themeplus

4. Activate the plugin

Go to Plugins → Installed Plugins in the WordPress admin and activate ThemePlus.

---

Running Dev Mode

Dev mode requires two terminal processes running simultaneously — one for each build pipeline.

Terminal 1 — Vite (SCSS + React panel)

bash

npm run dev

Starts the Vite dev server. Watches src/ for changes and hot-reloads the React options panel and compiles SCSS on save.

Terminal 2 — wp-scripts (Gutenberg blocks)

bash

npm run blocks:start

Starts the webpack watcher for block assets in blocks/. Recompiles block JS and CSS on save.

Both watchers must be running at the same time for all changes to be reflected in the browser.

---

Available Scripts

Script	Command	Description
Dev — Vite	npm run dev	Starts Vite dev server with HMR for React panel and SCSS
Dev — Blocks	npm run blocks:start	Starts wp-scripts watcher for Gutenberg block assets
Build — Vite	npm run build	Production build of the React panel and SCSS
Build — Blocks	npm run blocks:build	Production build of all block assets
Package	npm run package	Runs both production builds and zips the plugin into themeplus.zip

---

Enabling Dev Mode

Set the THEMEPLUS_DEV constant to true in your theme’s functions.php or in wp-config.php:

php

// In functions.php
define( 'THEMEPLUS_DEV', true );

php

// Or tie to WP_DEBUG in wp-config.php
define( 'THEMEPLUS_DEV', defined( 'WP_DEBUG' ) && WP_DEBUG === true );

With THEMEPLUS_DEV enabled:

• Unminified JS and CSS assets are loaded
• The Developer Panel is visible at the bottom of the options panel
• React state changes and save events are logged to the browser console
• React component errors show a detailed stack trace overlay

See Developer Panel for full details on what Dev Mode exposes.

---

Project Structure

themeplus/
├── src/                        # Vite source — React panel + SCSS
│   ├── admin/                  # React options panel app
│   │   ├── components/         # Field components, UI elements
│   │   ├── store/              # Global state (Zustand)
│   │   └── main.jsx            # Panel entry point
│   └── scss/                   # Panel SCSS (BEM)
│       ├── base/
│       ├── components/
│       └── main.scss
├── blocks/                     # Gutenberg block source
│   ├── example-block/
│   │   ├── block.json
│   │   ├── edit.jsx
│   │   ├── save.jsx
│   │   └── style.scss
│   └── index.js
├── dist/                       # Vite build output (committed to repo)
├── build/                      # wp-scripts block build output (committed to repo)
├── includes/                   # PHP — framework core
│   ├── Framework.php           # Main bootstrap class
│   ├── Fields/                 # PHP field registration classes
│   ├── RestApi.php             # REST API endpoint
│   └── Helpers.php             # themeplus_get_option() and helpers
├── sample-config.php           # Example themeplus_init() configuration
├── themeplus.php               # Plugin entry point
├── package.json
└── vite.config.js

---

Building for Production

Run both build pipelines, then package:

bash

npm run build
npm run blocks:build
npm run package

npm run package zips the plugin folder (excluding node_modules, src/, blocks/ source, and other dev files) into themeplus.zip in the project root. This ZIP is the distributable plugin file — attach it to a GitHub Release or upload directly to WordPress.

Files excluded from the package ZIP

node_modules/
src/
.git/
.github/
*.map
package.json
package-lock.json
vite.config.js

---

Adding a New Field Type

1. Create a React component in src/admin/components/fields/MyField.jsx
2. Register it in src/admin/components/fields/index.js
3. Create a PHP registration class in includes/Fields/MyField.php
4. Register the PHP class in includes/Framework.php
5. Add SCSS styles in src/scss/components/_field-my-field.scss and import in main.scss
6. Test with THEMEPLUS_DEV enabled — verify the return value appears correctly in the Developer Panel

---

Notes

• Always run npm run build and npm run blocks:build before committing a release — the dist/ and build/ directories are committed to the repository and must reflect the latest source.
• Never set THEMEPLUS_DEV to true in a production or publicly distributed build — it exposes debug information and loads unoptimized assets.
• The Vite dev server runs on a separate port — it does not serve WordPress pages. All WordPress page loads go through your local server as normal; Vite only handles HMR for the React panel assets.
• If npm run dev and npm run blocks:start both need to run but you only have one terminal, use a process manager like concurrently: npx concurrently "npm run dev" "npm run blocks:start".