Credits: WPGulpPro is the evolution of WPGulp by Ahmad Awais. This fork modernizes the original with Node 20/22/24 support, Dart Sass migration, and bug fixes while preserving the zero-config philosophy.

📦 WPGulpPro Can Do THAT™

WPGulpPro is an advanced & extensively documented Gulp.js + WordPress workflow. It can help you kick-start a build-workflow for your WordPress plugins and themes with Gulp.js, save you a lot of grunt work time, follow the DRY (Don't Repeat Yourself) principle, and #0CJS Zero-config JavaScript startup but still configurable via wpgulp.config.js file. It is:

• 🥞 Versioned ✓
• 🤠 Updatable ✓
• 🗃 Set of sane-defaults ✓
• 🔥 Node 20/22/24 Compatible ✓

💻 DEV ENVIRONMENT

• Live reload browser with BrowserSync
• Hotloading styles with CSS Injection

🎨 STYLES

• Sass to CSS conversion (Dart Sass)
• Merging media queries
• Error handling
• Auto-prefixing
• Minification
• Sourcemaps

🌋 JavaScript

• Concatenation
• Minification/uglification
• Babel transpilation for ESNext
• Separate vendor and custom JS files handling

🌁 IMAGES

• Minification/optimization of images
• File types: .png, .jpg, .jpeg, .gif, .svg

💯 TRANSLATION

• Generates .pot translation file for i18n and l10n

👀 WATCHING

• For changes in files to recompile
• File types: .css, .html, .php, .js

Getting Started

⚡️ Quick Overview

Run step #1, #2, and #3 quickly in one go — Run inside local WP install's theme/plugin folder E.g. /wp.local/wp-content/plugins/your-plugin or /wp.local/wp-content/themes/your-theme directory.

# 1— Install WPGulpPro in your WordPress theme/plugin.
npx wpgulppro
# 2— Now configure variables inside the `wpgulp.config.js` file.
# 3— Start your npm build workflow.
npm start

(npx is a package runner tool that comes with npm 5.2+ and higher).

🎛 If you want to study the detailed installation of step #1 , #2, and #3 — then take a look at the steps below.

In case you are an absolute beginner to the world of Node.js, JavaScript, and npm packages — all you need to do is go to the Node's site download + install Node on your system. This will install both Node.js and npm, i.e., node package manager — the command line interface of Node.js.

You can verify the install by opening your terminal app and typing...

node -v
# Results into v20.0.0 or higher — make sure you have Node >= 20 installed.

npm -v
# Results into 10.0.0 or higher — make sure you have npm >= 9 installed.

→ STEP #1 — Download the Required Files

1. In the terminal go to the root folder of your WordPress plugin/theme
2. Run the following command to download all the files from the WPGulpPro repository

It'll take a couple of minutes to install.

npx wpgulppro

(npx is a package runner tool that comes with npm 5.2+ and higher).

⚠️ I'm assuming that there are no previously present similar files in the root of your folder. Otherwise, you need to merge these very carefully. E.g. You can include the scripts, devDependencies in your current package.json file and so on for other files. If you run the above command all similar files will be overwritten.

→ STEP #2 — Editing the Project Variables

Configure the project paths and other variables inside the wpgulp.config.js file. This is a compulsory step.

→ STEP #3 — Start your project

Once the installation is done, you can open your project (WordPress plugin/theme) folder and run the start script.

npm start

# To stop press CTRL (⌃) + C

→ OPTIONAL STEP #4 — More Scripts/Tasks

To optimize images and generate WP POT translation file, or generate a RTL stylesheet you can run the following commands

# To optimize images.
npm run images

# To generate WP POT translation file.
npm run translate

# To generate RTL stylesheets and Sourcemap.
npm run styles-rtl

# To generate theme/plugin zip file without extranious files.
npm run zip

🔧 Alternative Installation (Before npm Release)

The wpgulppro package is not yet published to npm. Use one of these methods instead:

Method 1: GitHub Install (Recommended)

# Navigate to your WordPress theme/plugin folder
cd /path/to/your-theme

# Install directly from GitHub
npm install faisalahammad/WPGulpPro

# Run the installer
npx wpgulppro

Method 2: npm link (Development)

# Clone the repository
git clone https://github.com/faisalahammad/WPGulpPro.git
cd WPGulpPro

# Link globally
npm link

# Navigate to your theme/plugin folder
cd /path/to/your-theme

# Run the installer
wpgulppro

Method 3: ZIP Download

1. Download WPGulpPro ZIP
2. Extract the files to your theme/plugin folder
3. Run npm install

How to Update?

1. Download all the latest files from the WPGulpPro repository by running npx wpgulppro - it will overwrite all the wpgulp files.
2. Open terminal and install WPGulpPro's node dependencies by running the npm install commands in the root folder of your WordPress plugin/theme.

Changelog

Read what's 📦 new, 👌 improved, 🐛 fixed, and if 📖 docs got updated.

👉 Go read the entire changelog at this link — WPGulpPro Changelog →

Nothing's ever complete, so bear with us while we keep iterating towards a better future.

'Coz every night I lie in bed
The brightest colors fill my head
A million dreams are keeping me awake
I think of what the world could be
A vision of the one I see
A million dreams is all it's gonna take
A million dreams for the world we're gonna make ...

... listen to → A million dreams!

FAQ

Why Node 20+ required?

Node 20+ ensures compatibility with modern JavaScript features and security updates. Older Node versions (14, 16, 18) have reached or are approaching End of Life.

What's different from original WPGulp?

| Feature | WPGulp | WPGulpPro | |---------|--------|-----------| | Node Support | Node 10+ | Node 20/22/24 | | Sass Compiler | node-sass (deprecated) | Dart Sass | | Dependencies | Outdated | Latest compatible | | Maintenance | 2019 | Active |

Can I use this with existing WPGulp projects?

Yes, but you'll need to:

1. Backup your wpgulp.config.js
2. Run npx wpgulppro to get new files
3. Restore your custom wpgulp.config.js
4. Run npm install to get new dependencies

How do I migrate from node-sass to Dart Sass?

Dart Sass is a drop-in replacement. If you're using WPGulpPro, it's already configured. For manual migration:

# Remove old node-sass
npm uninstall node-sass

# Install Dart Sass
npm install sass

Image optimization fails for WebP/AVIF?

The gulp-imagemin v7 has limited support for modern formats. Images are processed with smart detection—unsupported formats are skipped. For full WebP/AVIF support, consider using a separate image optimization pipeline.

Connect with the Maintainer

| Platform | Handle | Link | |----------|--------|------| | GitHub | @faisalahammad | github.com/faisalahammad | | Twitter | @faisalahammadwp | twitter.com/faisalahammadwp | | WordPress.org | @faisalahammad | profiles.wordpress.org/faisalahammad | | LinkedIn | @faisalahammad | linkedin.com/in/faisalahammad |

License & Credits

• MIT License — See LICENSE file
• Original WPGulp: Ahmad Awais
• WPGulpPro: Faisal Ahammad

This project is a modernized fork of ahmadawais/WPGulp — inspired by the work of many awesome developers especially those who contribute to this project, Gulp.js, Babel, and many other dependencies as listed in the package.json file. FOSS (Free & Open Source Software) for the win.