Deploy a Wordpress Theme

Caution

Deploying is not the first step — it’s one of the last.

You should only deploy after you’ve finished working on your task and you’re confident everything works correctly in your local environment.

If this is your first time deploying, it’s highly recommended to do it together with your Project Manager (or a more experienced teammate). Think of the first deploy as a guided step, not something you’re expected to do alone.

This guide outlines how to deploy WordPress themes built with Vite, using our gulp-based workflow.

---

What is a Deploy / Build?

A deploy (sometimes referred to as a build) is the process of taking the work you’ve done locally and making it available in a shared environment, such as dev.

✅ DO	❌ DON’T
Deploy only after finishing your task	Deploy while the feature is half-done
Test everything locally first	Use stage or production as a testing environment
Make sure your changes work as expected	Assume “it probably works”
Deploy only to dev (unless told otherwise)	Deploy to staging or production without telling anyone
Ask your PM before your first deploy	Do your first deploy alone
Deploy when you’re ready for review	Deploy just to “save your progress”
Communicate in Slack after deploying	Deploy without telling anyone
Keep your deploys focused and clean	Deploy unrelated or experimental changes
Double-check forms, animations, and edge cases	Skip QA because “it’s a small change”

---

First: Is it a Vite or Webpack Project?

Info

The deploy process changes depending if it’s a Vite or Webpack project.

To determine whether a project is using Vite or Webpack, check the root of the theme folder:

• Vite projects will have a vite.config.js file.
• Webpack projects will have files like webpack.common.js, webpack.dev.js, or webpack.prod.js.

---

How to deploy?

01. Commit and pull your changes

Before doing anything else:

• Open GitHub (or your Git client)
• Review the files you’ve modified:
  • CSS / JS files
  • PHP files
• Make sure everything is committed
• Always pull the latest changes from the remote repository

02. Make sure you set up is correct

For preventing some errors in the building process, make sure:

• You are using the correct Node version (specified by project. Ask your PM about this):

nvm use 21

• You installed the dependencies:

npm install

03. Understand what hash.php does

Inside the project, you’ll find a file called hash.php (or define-hash.php).

• The hash is a unique string generated from your compiled CSS and JS
• It helps browsers detect changes and avoid loading cached assets
• Every time CSS or JS changes, a new hash must be generated

04. Run the build command

• In the dist/js folder, you’ll see files like main.skf.js.

  • The skf part is the hash
  • This hash represents the latest compiled CSS and JS

• To make a new hash, execute:

npm run build

Some projects use Webpack instead of Gulp, in that case the build command may be:

npm run dev

npm run stage

npm run production

Tip

If no new hash is generated, try making a small change in a .js file (for example, adding a temporary console.log) and run the build again.

• This will make a new hash appear in main.7d2.js.
• Copy-paste that hash into the hash.php file.

In new projects…

In new projects with Vite, npm run build command already uploads the hash in hash.php, so you can skip the copy-paste. You can learn more about this here.

05. Deploy to an environment

In your deploy.md or sftpConfig.js file you’ll find a cheatsheet of the commands you need to use, usually using gulp command.

Here are the main commands you can run:

Command	What it does	When to use it
gulp ddist --dev|stage|production	Uploads all project files	Rarely used. Only when you need to deploy the full project
gulp ddisthash --dev|stage|production	Uploads only the /dist and /hash directories	When you change CSS or JS files
gulp dfm --dev|stage|production	Deploys all flexible modules	When working with flexible or modular content
gulp dall --dev|stage|production	Deploys everything in the project	Use with caution. Only when explicitly needed
gulp dphp --dev|stage|production	Deploys only PHP files	When you change PHP logic or templates
gulp ds --dev|stage|production --path footer.php	Deploys a specific file	When only one file needs to be updated
gulp ds --dev|stage|production --path folder/	Deploys a specific folder	When changes are limited to a single folder

Reminder

This works for most of the projects, but not for all of them. Some of them use these kind of commands (you can find them in the package.json file):

npm run stg-hash

npm run stg-php

---

Excluding Files from Upload

To prevent certain files from being uploaded, make sure they are listed in the filesToExclude constant inside sftpConfig.js.

Example:

const filesToExclude = [
  "!functions/project/hash.php",
  "!functions/project/local/local-variable.php",
  "!public/**/*",
  "!config/**/*",
  "!node_modules/**/*",
  "!src/**/*",
  "!.env.production",
  "!.env.virtual",
  "!gulpfile.js",
  "!package-lock.json",
  "!package.json",
  "!readme.md",
  "!vite.config.js",
  "!documentation/**/*",
];

This ensures that sensitive or non-deployable files are not accidentally pushed to the server.

---

Summary

• Always confirm the project type (Vite vs. Webpack).
• For Vite projects, use the gulp commands defined above.
• Use ddisthash or dphp depending on what has changed.

Tip

When in doubt, confirm with the lead developer before deploying.

---

Video

---