Commands to start development env

Before this

Before diving into the commands of a project, make sure you read and understood:

→ What type of project you’re in → What environments are → Deploy guide

---

For Webpack

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

"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

.env.local configuration

For the dist build to work correctly in local, the .env.local file must be properly configured according to the project.

Environment variables may vary between projects, so always make sure you are using the correct .env.local values before running npm run local or npm run production.

Deployment by environment

These are pre-configured shortcuts that run the correct Gulp tasks for each 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

---

For 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.

Learn more

Want to understand the difference between these two commands? Read this

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.

To automatically change these generated hashs into our hash.php document, we added this function to our wp-starter-kit’s viteHelper.js:

export function updateHash(hash) {
    console.log(`Updating hash in hash.php file with new hash: ${hash}`);

    const hashFileRoute = resolve(process.cwd(), "functions/project/hash.php");

    if (fsSync.existsSync(hashFileRoute)) {
        const content = fsSync.readFileSync(hashFileRoute, "utf-8");

        const updatedContent = content.replace(
            /define\(\s*['"]hash['"]\s*,\s*['"][a-zA-Z0-9]*['"]\s*\);/,
            `define('hash', '${hash}');`
        );

        fsSync.writeFileSync(hashFileRoute, updatedContent, "utf-8");
    } else {
        console.log("Hash file not found:", hashFileRoute);
    }
}

If working in an old Vite project

In case you’re working in an old Vite project, you can copy-paste this function into viteHelper.js.

Upload (Deploy) the Project

All the following commands use this format:

gulp <task> --dev|stage|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.

# Use Node.js version 21
nvm use 21

# Check the version use
node -v

npm cache clean —force

Sometimes npm gives errors. This command clears the cache.

---

Video