Running Virtual vs. Running Local

In our development workflows, we use two main modes to run projects: virtual and local. Understanding the difference between the two is essential for smooth setup, debugging, and deployment.

---

🌐 Virtual Mode

Virtual mode is when you run npm run virtual, which creates a virtual server in WordPress. It’s called “virtual” because the JavaScript and SCSS assets are served from memory, while the PHP files are still present and used.

Characteristics:

• Simulates a WordPress environment with no cache for static files (JS/SCSS) + auto reload for PHP files
• JavaScript and SCSS assets are compiled and served from memory, not from the filesystem.
• PHP files are still present and used, just like in a regular WordPress setup.
• Ideal for frontend development, as it allows quick iteration on styles and scripts.

How to run:

npm run virtual

When working in virtual mode, the system assumes you’re not using real WordPress, and:

define('IS_VIRTUAL_ENV', true);

This variable is correctly set for virtual mode.

---

📦 Local Mode

Local mode is rarely used and involves building the project locally.

How to run:

npm run local

When we run npm run local, a new dist folder or a new theme folder is compiled, depending on the project.

Our build system generates assets (CSS/JS) with hashed filenames.

---

🛠 Updating Hashes

Because filenames are hashed, we need to update the hash reference in PHP when running locally.

1. Go to functions/project/hash.php.php or functions/project/define-hash.php in your project.
2. Replace the old hash with the new one generated after running npm run local.

---

🧭 Set IS_VIRTUAL_ENV to false

After building locally, tell your WordPress instance you’re not in virtual mode:

• Go to functions/project/local-variable.php
• Set:

define('IS_VIRTUAL_ENV', false);

⚠️ This switch ensures the system loads the correct built assets and not mock or dev-only files.

Video