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.

---

🖥️ Local Mode

Local mode is when the project runs connected to a local WordPress instance.

Characteristics:

• Used when you have a full WordPress environment running locally (e.g., via LocalWP or Docker).
• The theme code, assets, and templates are served directly from your machine.
• Great for full-stack development, including PHP, plugin testing, and backend integrations.

How to run:

npm run virtual

---

🌐 Virtual Mode

Virtual mode is when the project is compiled and served independently of WordPress, often used for frontend development only.

Characteristics:

• Simulates WordPress by mocking global variables or using placeholder data.
• Ideal for working on isolated frontend components and styles without needing a running WordPress instance.
• Faster build/start time.

🔄 Virtual Mode Reminder

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

define('IS_VIRTUAL_ENV', true);

⚠️ Asset enqueuing is already smart — it knows which environment you’re in and automatically serves the right files. he project is compiled and served independently of WordPress, often used for frontend development only.

📦 Local Mode

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.

🧩 What is a Hash?

A hash is a short, unique string (e.g., ty7) added to the filename of built assets like:

Project.ty7.js
Style.ty7.css

This is used for cache busting — to ensure browsers always load the latest version of your files.

---

🛠 Updating Hashes

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

1. Go to hash.php or 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 local.php
• Set:

define('IS_VIRTUAL_ENV', false);

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

---