Introduction
WordPress automation and WPGulp are some of those tools that, once you discover them and start using them, you wonder how you ever worked without them. This was the case for our lead developer at S-Tier Dev, as well, and it was well into his career. That being said, we noticed that many beginner and intermediate developers are unfamiliar with WPGulp and its concepts and use cases, so here is a detailed guide on how to start.
About WPGulp
WPGulp is an essential tool for WordPress theme developers looking to streamline their workflow. It is not the only tool of this kind, but it is our tool of choice.
The best features of implementing the WPGulp workflow are:
The ability to write your CSS code using SCSS syntax and organize your code in separate files and folders can significantly make writing and editing code much easier, and on top of that, it can save you a lot of development time.
Another amazing feature is the implementation of browsersync, which allows automatic reloading of the browser tab where your website is opened as soon as you save one of your SCSS, JS, or PHP files.
This guide will walk you through setting up and using WPGulp, ensuring you can efficiently manage and automate tasks in your theme development process.
Step 0: Local, node.js and NPM
If you’ve done WordPress development in the past, you’re probably familiar with Local, node.js, and NPM, and you have already used them. If not, you will need to install those in order to begin your development with WPGulp on your local machine/server.
Local (or Local by Flywheel, as it was previously called) is a local server emulator with a user-friendly interface that allows you to install a WordPress site in a matter of minutes and run it locally without the need for purchasing a host and/or a domain.
Node.js and NPM are also required to be installed on your machine. For optimal compatibility, we recommend using version 14.19.3. You can download the installer on the official node website: https://nodejs.org/en/blog/release/v14.19.3.
From this page, you can choose the appropriate installer for your version of the OS.
Note: This step is done only once, and it is installed globally. The following steps are repeated for each theme or child theme you make.
Step 1: Navigate to your theme
Navigate to your WordPress theme or child theme directory.
Example: D:\Local Sites\s-tier-dev\app\public\wp-content\themes\stier
Start a terminal app, such as GitBash, in your themes folder, or if you’re using a code editor with terminal integrated into it, drag and drop your theme in the editor and run a terminal from there.
Step 2: Installing WPGulp
When your terminal is opened and ready to use, run the following command that will install the necessary files in your theme.
npx wpgulp
You will notice a couple of files and folders inserted in your theme, but the only one you should worry about is ‘wpgulp.config.js’. We will edit this file to accommodate the location of the files and folders we will use for writing the code, so WPGulp knows what files to watch and compile.
Step 3: Create SASS(SCSS) & JS folders and files
In the root of your theme, create a SASS folder, and inside the folder, create a style.scss file.
The Style.css file will contain the basic meta of your theme and will import all the SCSS files we will use for writing our styles.
In theory, we can write all of our code here, but in order for our theme, the code organization, and ease of use, we will not do that; instead, we should separate our code into specific files. Example: header.scss, homepage.scss, footer.scss, etc.
Now let us create the files mentioned and include them in the style.scss.
After we create them, we should include them by adding the following line in style.scss for each file we created.
@import 'name-of-the-file';
Replace ‘name-of-the-file’ with the file name you want to include/import e.g., header.scss, homepage.scss, footer.scss, etc. You can import as many files as you need to keep your theme file system neat and organized.
We will do something similar for the JavaScript, but we will not have as many steps as for the CSS.
We need to create a JS folder in the root of our theme. Whichever JS file is inserted in this folder will be automatically compiled.
In the next step, we will edit the ‘wpgulp.config.js’ file in order to ‘tell’ it where to look for our files.
Step 3: Edit ‘wpgulp.config.js’
Change the following lines:
Line 15: – The URL of our local website
const projectURL = 'wpgulp.local';
– From: wpgulp.local
– To: URL of your local website
Line 24: – The path to main style.scss file
const styleSRC = './assets/css/style.scss';
– From: ./assets/css/style.scss
– To: ./sass/style.scss
Line 48: – Path to folder containing your JS files
const jsCustomSRC = './assets/js/custom/*.js';
– From: ./assets/js/custom/*.js
– To: ./js/*.js
Line 51: – Location where you want your main JS file to be placed after compiling
const jsCustomDestination = './assets/js/';
– From: ./assets/js/
– To: ./
Line 54: – Desired name of the compiled .js file that you will include/use in your theme
const jsCustomFile = 'custom';
You can keep the same file name, or you can change it to your liking.
Line 68: – Here we’re ‘telling’ browsersync which SCSS files to watch and refresh the browser tab when the file changes
const watchStyles = './assets/css/**/*.scss';
– From: ./assets/css/**/*.scss
– To: ./sass/**/*.scss
Line 73: – Same thing for JS files
const watchJsCustom = './assets/js/custom/*.js';
– From: ./assets/js/custom/*.js
– To: ./js/*.js
By following these steps, you’ve successfully integrated WPGulp into your WordPress theme development workflow. This setup will help you automate repetitive tasks, allowing you to focus more on the creative aspects of theme design and development.
The last thing we need to do, and we need to repeat this every time we’re starting to work on the theme, is to run the following command in our terminal app:
npm start
In the image above, you can see the approximate process that will happen in your terminal after you run the npm start command. In the second green box, you see the local and external URLs, and those URLs are where the magic happens.
The Local URL is the one that you open on the machine where the website is located, and the External URL you can open on any machine (mobile, laptop, tablet, TV) that is connected to the same network as your local machine. All the browsers will be refreshed automatically, and all changes you make to your files will be shown instantly.
Conclusion
This guide provides a basic overview and should be tailored further based on your specific theme development needs and the complexity of your projects. The steps we covered are the ones that you will use in most, if not all, projects, but these are not the only features WPGulp contains.
Also, for the purposes of simplifying and understanding how WPGulp works, we changed some paths that were not required to be changed. You can leave all paths as they are by default, create SCSS and JS files and folders based on the default configuration, and only change the project URL. But our approach will help you better understand WPGulp and wpgulp.config.js so you can adjust them to your needs and manage more complex projects in the future.
When you finish a couple of projects and master the steps we underlined in this post, you can check out the rest of the wpgulp.config.js file to see other features WPGulp provides. All of them are commented on, and if you followed and understood this post, you will not have any issues understanding the rest of the features.
Bonus
The bonus feature that we would like to cover is the one that we personally use on each project, but it is not a must. It is the generation of the theme ZIP file. The following command will generate a ZIP with your theme files, but it will not include the WPGulp files that are not necessary for the theme functionality and are only used for development.
The command:
npm run zip
You can change the name of the ZIP generated on line 81 of the wpgulp.config.js file, and it should correspond to the name of the theme you’re building.
const zipName = 'file.zip';
– From: file.zip
– To: your-theme-name.zip
We’re not going to cover other less-used functionalities, but here are some of them:
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