Commands to start development env

🚦 Start Here: Vite or Webpack?

Before you run any command, make sure you know whether the project uses Vite or Webpack. This affects how you build and deploy.

🔎 How to check:

• Open package.json

• Look inside the scripts section:

  • If you see commands with vite → ✅ You’re using Vite

  • If you see webpack or a custom command like build:webpack → 🛠️ You’re using Webpack

🔗 See Before running for more info.

🧱 If the Project Uses Webpack

Webpack projects manage everything from package.json scripts, including building and deploying.

🔧 Example Webpack Scripts

"scripts": {
  "virtual": "webpack serve --config webpack.dev.js --open",
  "local": "webpack --config webpack.prod.js",
  "production": "webpack --config webpack.prod.js",
  "dev-full": "gulp deploy_full",
  "stg-hash": "gulp deploy_hash",
  "prd-file": "gulp deploy_file --file"
}

🧪 Development and Build

→ Starts a live dev server (local preview) npm run virtual

→ Builds the project and creates dist npm run local or npm run production

🚀 Deployment by environment

→ Full deployment to development npm run dev-full

→ Deploy hash build to staging npm run stg-hash

→ Upload a single file to production npm run prd-file

📝 These are pre-configured shortcuts that run the correct Gulp tasks for each environment.

📦 If the Project Uses Project Vite

In your package.json, you’ll find these scripts:

"scripts": {
  "virtual": "cross-env NODE_ENV=virtual vite",
  "local": "NODE_ENV=local vite build",
  "build": "NODE_ENV=production vite build"
}

🔹 npm run virtual

Starts the project in a special “virtual” environment. Useful for development and testing with real data or mock content.

🔹 npm run local

Builds the project using local settings. It prepares the output files but does not upload or preview anything.

🔗 Want to understand the difference? See virtual vs local environments for more info. Virtual vs Local

🔹 npm run build

Builds the project with production settings. It creates a folder called dist and adds a short code (hash) of three characters to the filenames, like main.ab2.js.

🔁 After this, you must update the hash file and deploy it using the correct Gulp command below.

🚀 Upload (Deploy) the Project

All the following commands use this format:

gulp <task> --dev|stage|production

You must always choose where you want to deploy:

--dev = development

--stage = staging

--production = live production

🔸 gulp ddist —dev|stage|production

Uploads everything inside the dist folder.

🔸 gulp ddisthash —dev|stage|production

Uploads the dist folder and the hash folder (which includes the version info). 👉 This is what you normally run after npm run build.

🔸 gulp dfm —dev|stage|production

Deploy all flexible modules (custom reusable blocks).

🔸 gulp dall —dev|stage|production

Deploy all files (PHP, JS, assets, modules…).

🔸 gulp dphp —dev|stage|production

Deploy only the PHP files.

🔸 gulp ds —dev|stage|production —path file|folder

Deploy just one file or one folder.

🔸 gulp remove —dev|stage|production —path file|folder

Deletes a file or folder from the server.

🔧 Extra Tools

🔹 nvm use

Switches your Node.js version to the one your project needs. Important if you’re switching between different projects or machines. Example:

nvm use 21

To check the version use node -v

🔹 npm cache clean —force

Sometimes npm gives errors. This command clears the cache.

✅ Common Workflow: Step-by-Step Guide

Follow these steps every time you want to work on the project and deploy your changes:

• 1. 🔍 Check if the project uses Vite or Webpack
• 2. 🧱 Make sure you’re using the right Node version
• 3. 🛠️ Start the Project
• 4. 🧾 Update the hash file
• 5. 🚀 Upload your changes