Development Setup & Dev Mode

OneMeta includes a dev mode that loads JavaScript and CSS directly from the Vite development server (localhost:3000) with Hot Module Replacement (HMR). This means any change you make to a file in src/js/ or src/scss/ is instantly reflected in the browser — no page reload and no manual rebuild needed.

---

Prerequisites

• PHP 8.2+
• Node.js 18+
• npm
• A local WordPress install (e.g. LocalWP, Laragon, MAMP, or Docker)

---

Step 1 — Clone the Repository

Clone OneMeta directly into your WordPress plugins directory:

bash

cd wp-content/plugins
git clone https://github.com/fronttheme/onemeta.git
cd onemeta
npm install

Then go to Plugins in your WordPress admin and activate OneMeta.

---

Step 2 — Enable Dev Mode in wp-config.php

Add the following constants to your wp-config.php above the /* That's all, stop editing! */ line:

php

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

How Dev Mode Works

OneMeta checks two separate constants depending on context:

Context	Condition
Admin builder (JS + CSS)	ONEMETA_DEV_MODE === true
Frontend field assets (JS + CSS)	WP_DEBUG === true AND ONEMETA_DEV_MODE === true

Important: ONEMETA_DEV_MODE must be the boolean true — not the string "true". The admin builder checks ONEMETA_DEV_MODE === true strictly.

When dev mode is active, OneMeta loads scripts from:

• http://localhost:3000/@vite/client
• http://localhost:3000/src/js/admin/main.js
• http://localhost:3000/src/js/frontend/main.js

All scripts are loaded as ES modules (type="module") automatically.

---

Step 3 — Start the Vite Dev Server

bash

npm run dev

You should see output like:

VITE v5.x.x  ready in 300ms

➜  Local:   http://localhost:3000/
➜  Network: use --host to expose

Now open any OneMeta admin page in your browser. Changes to src/js/ or src/scss/ will hot-reload instantly.

---

Step 4 — Make Your Changes

• JavaScript — src/js/admin/ for builder and admin UI, src/js/frontend/ for field rendering and conditional logic
• SCSS — src/scss/ with a modular 7-1 architecture (abstracts, base, components, layout, pages)
• PHP — includes/ with PSR-4 namespacing under OneMeta\

---

Testing the Production Build Locally

Before submitting a pull request, always verify your changes work correctly with the production build. Comment out ONEMETA_DEV_MODE in wp-config.php:

php

// define( 'ONEMETA_DEV_MODE', true );

Then run a production build:

bash

npm run build

The plugin will now load from assets/js/admin.min.js and assets/css/admin.css — exactly as it does for end users. Test all affected functionality before opening your PR.

---

All Build Commands

Command	Description
npm run dev	Start Vite dev server with HMR
npm run build	Production build into assets/
npm run watch	Watch mode — rebuilds on file change, no HMR
npm run pot	Generate .pot translation file
npm run package	Build + create onemeta.zip release package

---

Project Structure

onemeta/
├── src/
│   ├── js/
│   │   ├── admin/          ← Builder, dashboard, settings JS
│   │   │   ├── main.js     ← Admin entry point
│   │   │   ├── builder/    ← Drag & drop, field list, preview, save
│   │   │   ├── settings/   ← Field settings renderers
│   │   │   └── pages/      ← Dashboard, docs page JS
│   │   ├── frontend/       ← Field rendering, media, repeater JS
│   │   │   └── main.js     ← Frontend entry point
│   │   └── shared/         ← Shared utils and components (modal, toast, confirm)
│   └── scss/
│       ├── abstracts/      ← Variables, mixins, functions
│       ├── base/           ← Reset, typography, WP overrides
│       ├── components/     ← Buttons, cards, forms, fields
│       ├── layout/         ← Sidebar, insertion zones, grid
│       ├── pages/          ← Builder, dashboard, docs, about
│       └── frontend/       ← Frontend meta field styles
├── includes/
│   ├── Core/               ← Engine, Renderer, Sanitizer, ConfigLoader, FieldRenderer
│   ├── Admin/              ← Admin UI, builder, assets, AJAX, exporter
│   └── API/                ← REST API
├── assets/                 ← Compiled output (committed to Git)
│   ├── js/
│   └── css/
└── onemeta.php             ← Main plugin file

---

Notes

• The assets/ folder containing compiled JS and CSS is committed to Git — this allows users to install directly from the repository without running a build step
• node_modules/ is gitignored — always run npm install after cloning
• The ../onemeta-packaged/ folder and ../onemeta.zip created by npm run package are outside the plugin directory and never committed