Skip to content
Terra Docs
Blog

How to Deploy a Vite WordPress Theme

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

⚠️ Note: If your project uses Webpack, the deploy process is different. See below for how to identify the type of project and where to get more info.

🧭 Is It a Vite or Webpack Project?

Section titled “🧭 Is It 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.

🔗 You should always confirm this by reviewing the project setup guide:
https://terradocs.netlify.app/wp/terra-framework/before-running/

📦 Deployment

Section titled “📦 Deployment”

Inside your theme project, you’ll find a file named sftpConfig.js.
All deploy operations are routed through this configuration file to ensure consistency and reduce risk.

The available Gulp tasks have been simplified and standardized. Here are the main commands you can run:

📁 Gulp Tasks

Section titled “📁 Gulp Tasks”

  • gulp ddist --dev|stage|production
    → Upload all project files.

  • gulp ddisthash --dev|stage|production
    → Upload only the /dist and /hash directories.

  • gulp dfm --dev|stage|production
    → Deploy all flexible modules.

  • gulp dall --dev|stage|production
    → Deploy everything in the project.

  • gulp dphp --dev|stage|production
    → Deploy only PHP files.

  • gulp ds --dev|stage|production --path footer.php
    → Deploy a specific file.

  • gulp ds --dev|stage|production --path folder/
    → Deploy a specific folder.

  • gulp remove --dev|stage|production --path footer.php
    → Remove a specific file or folder from the server.

🔁 Reminder: Always update the hash in define-hash.php (or similar) whenever you generate a new dist folder after making changes to JS or CSS.

🛑 Excluding Files from Upload

Section titled “🛑 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

Section titled “🧠 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.

💬 When in doubt, confirm with the lead developer before deploying to stage or production.