The two most popular task runners powered by Node are Gulp<\/a> and Grunt<\/a>. I went with Gulp after a good amount of research, it appeared to have an intuitive way to write tasks. It uses Node streams to manipulate files and JavaScript functions to write the tasks, whereas Grunt uses a configuration object to define tasks \u2014 which might be fine for some, but is something that made me a little uncomfortable. Also, Gulp is a bit faster<\/a> than Grunt because of those Node streams and faster is always a good thing to me!<\/p>\n <\/p>\n So, we’re going to set Gulp up to do a lot of the heavy lifting for WordPress theme development. We’ll cover the initial setup for now, but then go super in-depth on the tasks themselves in another post.<\/p>\n So, how can we use Gulp to power the tasks for a WordPress theme? First off, let\u2019s assume our theme only contains the two files that WordPress requires for any theme: Secondly, let\u2019s assume that our primary goal is to create tasks that help manage our assets, like minify our CSS and JavaScript files, compile Sass to CSS, and transpile modern JavaScript syntax (e.g. ES6, ES7, etc..) into ES5 in order to support older browsers. <\/p>\n Our theme folder structure will look like this:<\/p>\n The only thing we\u2019ve added on top of the two required files is a Inside of that OK, next we want Gulp tasks to a create a new Identifying which Gulp tasks are the best fit for a project will depend on the project\u2019s specific needs. Some tasks will be super helpful on some projects but completely irrelevant on others. I\u2019ve identified the following for us to cover in this post. You\u2019ll see that one or two are more useful in a WordPress context (e.g. the POT task) than others. Yet, most of these are broad enough that you\u2019re likely to see them in many projects that use Gulp to process Sass, JavaScript and image assets.<\/p>\n We will talk about production vs. development modes during the article. Note that we will not create a task to concatenate CSS files. The We will only compile Remember. the For instance, if we change a JavaScript file, then the Scripts task should do its magic and then it would be ideal if the browser refreshed for us automatically so we can see those changes. Further, If we change a PHP file, then let\u2019s simply refresh the browser since PHP files don\u2019t rely on any other tasks in our project. We\u2019ll be using a Gulp plugin called Browsersync<\/a> to handle browser refreshes, but we\u2019ll get to that and other plugins a little later.<\/p>\n As a bonus step for the compress task, if you are creating a theme that you intend to publish on WordPress.org or maybe on a website like ThemeForest, then you probably already know that all functions in your theme must be prefixed with a unique prefix:<\/p>\n So, if you are creating a lot of themes. you’ll need to easily reuse functions in different themes but change the prefix to the name of the theme, to prevent conflicts. We can prefix our functions with a placeholder prefix and then replace all instances of that placeholder in the compress task. For instance, we can choose the string This can also apply to anywhere we use the theme name for example in the text domain:<\/p>\n Here\u2019s how our file structure looks after our tasks complete:<\/p>\n Now that we know what tasks we\u2019re going to use on our project and what they do, let\u2019s get into the process for installing Gulp into the project.<\/p>\n Before we install Gulp, we should make sure that we have Node and npm installed on our machines. We can do that by running these commands in the command line:<\/p>\n …and, we should get some version number as seen here:<\/p>\n Now, let\u2019s point the command line to the theme folder:<\/p>\n …and then run this command to initialize a new npm project:<\/p>\n This will prompt us with some options. The only important option in our case is the On to installing Gulp! First, we\u2019ve got to install Gulp\u2019s command line interface (gulp-cli) globally so we can use Gulp in the command line.<\/p>\n After that, we run this command in order to install Gulp itself in the theme directory:<\/p>\n The current stable release of Gulp is 3.9.1 at the time of this writing, but version 4.0 is already available in the project repository<\/a>.<\/p>\n To make sure everything is installed correctly, we\u2019ll run this command:<\/p>\n Nice! Looks like we\u2019re running version 4.0, which is the latest version at the time of this writing.<\/p>\n Gulp tasks are defined in a a file in called Gulp is JavaScript at its core, so we can define a quick example task that logs something to the console.<\/p>\n In this example, we\u2019ve defined a new task by calling Let\u2019s do that now.<\/p>\n Here\u2019s what we get:<\/p>\n As you can see, we do indeed get the Let\u2019s try running Here\u2019s an example of a task that returns a promise. In this task, we won\u2019t have to call the cb() function because Gulp already knows that the task will end when the promise resolves or returns an error:<\/p>\n Now try and run \u2018gulp promise\u2019 and the task will complete without returning any errors.<\/p>\n Finally, it\u2019s worth mentioning that Gulp accepts a default task that runs by typing Now, typing Whew! Now we know the basics of writing Gulp tasks.<\/p>\n There is one more thing we can do to improve things and that\u2019s enabling ES6 syntax in the Gulpfile. This will allow us to use features like destructuring<\/a>, import statements, and arrow functions, among others.<\/p>\n The first step to use ES6 syntax in the Gulpfile is to rename it from So, let\u2019s install Babel and some of its required packages by running:<\/p>\nArticle Series:<\/h4>\n
\n
Initial theme setup<\/h3>\n
index.php<\/code> and styles.css<\/code>. Sure, most themes are likely to include many more files that this, but that\u2019s not important right now.<\/p>\nthemefolder\/\r\n\u251c\u2500\u2500 index.php\r\n\u251c\u2500\u2500 style.css\r\n\u2514\u2500\u2500 src\/\r\n \u251c\u2500\u2500 images\/\r\n \u2502 \u2514\u2500\u2500 cat.jpg\r\n \u251c\u2500\u2500 js\/\r\n \u2502 \u251c\u2500\u2500 components\/\r\n \u2502 \u2502 \u2514\u2500\u2500 slider.js\r\n \u2502 \u2514\u2500\u2500 bundle.js\r\n \u2514\u2500\u2500 scss\/\r\n \u251c\u2500\u2500 components\/\r\n \u2502 \u2514\u2500\u2500 slider.scss\r\n \u2514\u2500\u2500 bundle.scss<\/code><\/pre>\nsrc<\/code> directory where our original un-compiled assets will live.<\/p>\nsrc<\/code> directory, we have an images<\/code> subdirectory as well as others for our JavaScript and Sass files. And from, there, the JavaScript and Sass subdirectories are organized into components that will be called from their respective bundle<\/code> file. So, for example, bundle.js<\/code> will import and include slider.js<\/code> when our JavaScript tasks run so all our code is concatenated into a single file.<\/p>\nIdentifying Gulp tasks<\/h3>\n
dist<\/code> directory where all of our compiled, minified and concatenated versions of our assets will be distributed after the tasks have completed. Even though we\u2019re calling this directory dist<\/code> in this post because it is short for “distribution,” it could really be called anything, as long as Gulp knows what it is called. Regardless, these are the assets that will be distributed to end users. The src<\/code> folder will only contain the files that we edit directly during development.<\/p>\n\n
bundle.scss<\/code> file in the scss<\/code> subdirectory to bundle.css<\/code> in a css<\/code> directory located in the dist<\/code> directory. This task will also minify the generated CSS file so that its is it\u2019s smallest possible size when used in production.\n<\/ul>\nbundle.scss<\/code> file will act as an entry point for all . <code>scss<\/code> files that we want to include. In other words; any Sass or CSS files you want to include in your project, just import them in the bundle.scss<\/code> file using @import<\/code> statements. For instance, in our example folder, we can use @import .\/components\/slider';<\/code> to import the slider.scss<\/code> file. This way in our task we will have to compile and minify only one file (bundle.css<\/code>).<\/p>\n\n
bundle.js<\/code> from ES6 syntax to ES5, then minify the file for production.<\/li>\n<\/ul>\nbundle.js<\/code>. Any other JavaScript files we want to include will be done using ES6 import statements<\/a>. But in order for those import statements to work on all browsers, we will need to use a module bundler. We\u2019re going to use webpack<\/a> as our bundler. If this is your first time working with it, this primer<\/a> is a good place to get an overview of what it is and does.<\/p>\n\n
src\/images<\/code> and send them to dist\/images<\/code> after the files have been compressed to their smallest size.<\/li>\n\/src\/images<\/code>, \/src\/js<\/code> or \/src\/scss<\/code> and post them to the dist<\/code> directory.<\/li>\n<\/ul>\nsrc<\/code> folder will contain the files that are only used during development and that will not be included in the final theme package. Thus, any assets other than our images, JavaScript and Sass files need to be copied posted to the dist<\/code> folder. For instance, if we have a \/src\/fonts<\/code> folder, we would want to copy the files in there into the dist<\/code> directory so they get included in the final deliverable.<\/p>\n\n
.pot<\/code> (i.e. translation) file from gettext<\/code> calls in the files. This is the most WordPress-centric of all the tasks we\u2019re covering here.<\/li>\n\n
node_modules<\/code>, that in turn, contains files like package.json<\/code> and other configuration files that define our project\u2019s dependencies \u2014 and these files and folders are only needed during development. During production, we can take out the necessary files for our theme and leave the unneeded development files behind. That\u2019s what this task will do; it will create a ZIP file that only contains the necessary files to run our theme.<\/li>\n<\/ul>\nfunction mythemename_enqueue_assets() {\r\n \/\/ function body\r\n}<\/code><\/pre>\n_themename<\/code> as a place holder, and when we compress our theme we will replace all \u2018_themename\u2019 strings to the actual theme name:<\/p>\nfunction _themename_enqueue_assets() {\r\n \/\/ function body\r\n}<\/code><\/pre>\n<?php _e('some string', '_themename'); ?><\/code><\/pre>\n\n
dist<\/code> folder, runs the Styles, Scripts, Images and Copy tasks in development mode (i.e. without minifying any of the assets), then watches for file changes to refresh the browser for us.<\/li>\ndist<\/code> folder should contain the files that are ready for distribution.<\/li>\ndist<\/code> folder are minified and ready for distribution. Then, it will run the Compress task, which bundles all of the production-ready files and folders into a ZIP file. We want a ZIP file because that is the format WordPress recognizes to extract and install a theme.<\/li>\n<\/ul>\nthemefolder\/\r\n\u251c\u2500\u2500 index.php\r\n\u251c\u2500\u2500 style.css\r\n\u251c\u2500\u2500 src\/\r\n\u2514\u2500\u2500 dist\/\r\n \u251c\u2500\u2500 images\/\r\n \u2502 \u2514\u2500\u2500 cat.jpg \/\/ after compression\r\n \u251c\u2500\u2500 js\/\r\n \u2502 \u2514\u2500\u2500 bundle.js \/\/ bundled with all imported files (minified in production)\r\n \u2514\u2500\u2500 scss\/\r\n \u2514\u2500\u2500 bundle.scss \/\/ bundled with all imported files (minified in production)<\/code><\/pre>\nInstalling Gulp<\/h3>\n
node --version<\/code><\/pre>\nnpm --version<\/code><\/pre>\n![\"\"](\"https:\/\/i0.wp.com\/css-tricks.com\/wp-content\/uploads\/2018\/12\/gulp-wp-01.png?ssl=1\")
<\/figure>\ncd path\/to\/your\/theme\/folder<\/code><\/pre>\nnpm init<\/code><\/pre>\npackage name<\/code> option. This is where the name of the theme can be provided \u2014 everything else can stay at their default setting. When choosing the theme name, make sure to only use lowercase characters and underscores while avoiding dashes and special characters since this theme name will be used to replace the functions placeholder that we mentioned earlier.<\/p>\nnpm install --global gulp-cli<\/code><\/pre>\nnpm install --save-dev gulp<\/code><\/pre>\ngulp --version<\/code><\/pre>\n![\"\"](\"https:\/\/i0.wp.com\/css-tricks.com\/wp-content\/uploads\/2018\/12\/gulp-wp-02.png?ssl=1\")
<\/figure>\nWriting Gulp tasks<\/h3>\n
gulpfile.js<\/code> that we\u2019ll need to create and place into the root of our theme.<\/p>\nvar gulp = require('gulp');\r\ngulp.task('hello', function() {\r\n console.log('First Task');\r\n})<\/code><\/pre>\ngulp.task<\/code>. The first argument for this function is the task\u2019s name (hello<\/code>) and the second argument is the function we want to run when that name is entered into the command line which, in this case, should print “First Task” into the console.<\/p>\ngulp hello<\/code><\/pre>\n![\"\"](\"https:\/\/i0.wp.com\/css-tricks.com\/wp-content\/uploads\/2018\/12\/gulp-wp-03.png?ssl=1\")
<\/figure>\nconsole.log('First Task')<\/code> output we want. However, we also get an error saying that our task did not complete. All Gulp tasks require telling Gulp where to end the task, and we do that by calling a function that is passed as the first argument in our task function like so:<\/p>\nvar gulp = require('gulp');\r\ngulp.task('hello', function(cb) {\r\n console.log('First Task');\r\n cb();\r\n})<\/code><\/pre>\ngulp hello<\/code> again and we should get the same output, but without the error this time. <\/p>\ncb()<\/code> is a Node.js callback function that’s often passed into an asynchronous function. There are some cases where we won\u2019t have to call it, such as when a task returns a promise<\/a> or a node stream<\/a>. A node stream is what we will use in the tasks in this post, which means we will see it a lot throughout our article.
<\/br><\/p>\ngulp.task('promise', function(cb) {\r\n return new Promise(function(resolve, reject) {\r\n setTimeout(function() {\r\n resolve();\r\n }, 300);\r\n });\r\n});<\/code><\/pre>\n<\/p>\ngulp<\/code> alone in the command line. All it takes is using “default” as the task name argument.<\/p>\ngulp.task('default', function(cb) {\r\n console.log('Default Task');\r\n cb();\r\n});<\/code><\/pre>\ngulp<\/code> by itself in the command line will run the task.<\/p>\nUsing ES6 in the Gulpfile<\/h3>\n
gulpfile.js<\/code> to gulpfile.babel.js<\/code>. As you may already know, Babel is the compiler<\/a> that compiles ES6 to ES5. <\/p>\nnpm install --save-dev @babel\/register @babel\/preset-env @babel\/core<\/code><\/pre>\n