Development Setup & Dev Mode

Set up a local development environment and run the ThemePlus build pipeline.

Overview

ThemePlus uses a hybrid build architecture — Vite handles SCSS compilation with HMR in development, and webpack via @wordpress/scripts handles the React admin panel and generates the WordPress dependency manifest. Both pipelines run in parallel during development.

This article is for contributors who want to modify ThemePlus source files. Theme developers integrating ThemePlus into a theme do not need any build tooling.

Requirements

Vite 7 requires Node.js 20.19+ or 22.12+ — Node.js 18 reached end-of-life in April 2025 and is no longer supported. Use node --version to check your current version and upgrade via nodejs.org if needed.

Repository Setup

1. Clone into your plugins folder

cd wp-content/plugins
git clone https://github.com/fronttheme/themeplus.git
cd themeplus

2. Install dependencies

npm install

3. Enable dev mode constants in wp-config.php

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
define( 'WP_ENVIRONMENT_TYPE', 'local' );
define( 'THEMEPLUS_DEV', true );

THEMEPLUS_DEV must be defined in wp-config.php — not in functions.php. It must be a boolean true, not a string.

4. Activate the plugin

Go to Plugins → Installed Plugins in the WordPress admin and activate ThemePlus. Then activate the ThemePlus Demo theme — this gives you a full field registration to develop against.

Running Dev Mode

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

Terminal 1 — Vite (SCSS with HMR):

npm run dev

Starts the Vite dev server on port 3000. Watches src/scss/ for changes and hot-reloads the admin panel styles without a page reload.

Terminal 2 — wp-scripts (React/JSX):

npm run blocks:start

Starts the webpack watcher. Recompiles src/js/admin/ on save and outputs assets/js/admin.js + assets/js/admin.asset.php.

Both watchers must be running simultaneously for all changes to be reflected — Vite handles styles, wp-scripts handles JavaScript.

Build Architecture

admin.asset.php is generated automatically by wp-scripts — it contains a content-hash version string and the full WordPress dependency array (wp-components, wp-element, wp-api-fetch, wp-i18n, react). The plugin reads this file in production for correct cache busting.

Available Scripts

Project Structure

themeplus/
├── src/
│   ├── js/admin/               # React admin panel source
│   │   ├── components/
│   │   │   ├── Fields/         # One file per field type (30 components)
│   │   │   ├── Common/         # FieldRenderer, Dialog, Select, SearchResults
│   │   │   ├── Layout/         # Sidebar, Header, Body, Footer, MainWrapper
│   │   │   ├── Sections/       # Import/Export, Custom Font Uploader
│   │   │   └── DevPanel/       # Developer Panel components
│   │   ├── context/            # React Context — Settings, Theme
│   │   ├── hooks/              # Custom React hooks
│   │   ├── services/           # Google Fonts and Custom Fonts API services
│   │   ├── utils/              # fieldHelpers.js — conditional logic evaluation
│   │   └── App.jsx             # Root application component
│   └── scss/                   # SCSS source — 7-1 modular architecture
├── assets/                     # Compiled output (do not edit directly)
│   ├── css/admin.css           # Built by Vite
│   ├── js/admin.js             # Built by wp-scripts
│   ├── js/admin.asset.php      # wp-scripts dependency manifest
│   └── fonts/fontawesome/      # Bundled FontAwesome 7
├── includes/                   # PHP framework classes
│   ├── classes/core/           # Core framework classes
│   ├── classes/custom-fonts/   # Custom Fonts module
│   ├── config/                 # sample-config.php, default-config.php
│   └── functions/              # Public helper functions
├── languages/                  # themeplus.pot + translations
├── themeplus.php               # Plugin entry point
├── uninstall.php               # Clean removal routine
├── package.json
├── vite.config.mjs
├── webpack.config.js
├── .distignore                 # Files excluded from the release ZIP
└── .gitignore

Building for Production

Run all build steps in order:

npm run build        # SCSS → assets/css/admin.css
npm run blocks:build # React → assets/js/admin.js + admin.asset.php
npm run pot          # Regenerate languages/themeplus.pot
npm run package      # Creates package/themeplus.zip

Or run everything in one command:

npm run package

npm run package runs both builds and the pot generation, then creates a clean ZIP at package/themeplus.zip excluding source files, dev tooling, and git artifacts per .distignore. This ZIP is the distributable plugin — attach it to a GitHub Release or upload to WordPress.org.

What’s excluded from the package ZIP

The .distignore file controls what is excluded:

src/
node_modules/
package.json
package-lock.json
vite.config.mjs
webpack.config.js
.git/
.gitignore
.gitattributes
.distignore
.github/
*.map
README.md
CHANGELOG.md
CONTRIBUTING.md
SECURITY.md

Dev Mode Behaviors

When dev mode is active (see detection logic below), ThemePlus enables:

• Vite HMR — start npm run dev for SCSS hot module replacement in the admin panel
• Developer Panel — appears as the last sidebar section showing field metadata, values, and code snippets
• Console logging — React panel logs state changes, save events, and conditional logic evaluations
• Error boundaries — React component errors show a detailed stack trace overlay instead of silently failing
• Dev-only REST endpoint — /wp-json/themeplus/v1/dev-panel becomes available

Dev Mode Detection

ThemePlus detects dev mode automatically using this priority order:

1. THEMEPLUS_DEV constant — explicit override (highest priority). true forces dev mode on, false forces it off regardless of other conditions
2. WP_DEBUG = true in wp-config.php
3. WP_ENVIRONMENT_TYPE = 'local' — set automatically by Local by Flywheel

You do not need to configure dev mode in your theme’s themeplus_framework_config() — it is detected automatically behind the scenes.

Adding a New Field Type

1. Create the React component in src/js/admin/components/Fields/MyNewField.jsx
2. Export it from src/js/admin/components/Fields/index.js
3. Register it in src/js/admin/components/Common/FieldRenderer.jsx
4. Add SCSS in src/scss/components/_my-new-field.scssand import in src/scss/admin.scss
5. Add a case in ThemePlus_Sanitizer::sanitize_field()for the new type
6. Run npm run dev + npm run blocks:start, open the ThemePlus Demo theme, and verify the field appears correctly in the All Values panel and Developer Panel

See CONTRIBUTING.md for the full six-step guide.

Notes

• Always run npm run package before tagging a release — the compiled assets/ directory is committed to the repository and must match the current source.
• Never set THEMEPLUS_DEV = true in a production or publicly distributed theme — it exposes debug information and loads development assets.
• The Vite dev server (npm run dev) runs on port 3000 and handles only HMR for assets — WordPress page loads still go through your local server as normal.
• If you want to run both watchers in one terminal: npx concurrently "npm run dev" "npm run blocks:start"
• The .pot file in languages/ is a committed source artifact — regenerate it with npm run pot whenever you add or change translatable strings, not as part of every build.