Bappi D Great

Gulp tutorial for beginners

In a sentence, Gulp is a task runner.

Gulp makes our life easier. In a development workflow, we need to do some tasks frequently and gulp can do some tasks automatically. Don’t think gulp is a replacement of grunt, but it is being improved very very fast.

Gulp is a task/build runner for development. It allows you to do a lot of stuff within your development workflow. You can compile sass files, uglify and compress js files and much more. The kicker for gulp is that its a streaming build system which doesn’t write temp files.

In this article, I will show you to create a simple WordPress plugin taking advantage of gulp. I am using MAC OS (OS X Yosemite) and MAMP as server.

We will compile sass to css, minify it, concat all the css files into one file, uglify js, concat all js files into one file, run these on changes automatically, create po file for i18n and create the release package as zip.

Let’s start!

First, look at my directory structure:

[gist https://gist.github.com/bappi-d-great/598699df608ce13bbb3c file=”0-directory-structure.txt” /]

In here, index.php is our main plugin file. There are three sass file in scss folder, which will be converted into css where gulp.main.css is the css file and gulp.main.min.css is the minified version. Exactly same for js script as well, gulp.main.min.js is the minified/uglified version of gulp.main.js which is a combination of ajax.js and public.js files. In the lang folder, we will generate out po file. node_modules folder will be auto generated, so is package.json file (we will see), the packages will be in there. We will use the releases folder to store the plugin package as zip. gulpfile.js file is our gulp configuration file.

Install Gulp

You must need Node JS and Node Package Manager (NPM) in your host to use Gulp. If you don’t have yet, please download from their site.

If you have those, let’s install gulp globally that will help us to run the gulp command anywhere in your system.

[gist https://gist.github.com/bappi-d-great/598699df608ce13bbb3c file=”a1-install-global-gulp.txt” /]

I assume you are already in root of the plugin directory in terminal.

Initializing gulp

Run the following command:

[gist https://gist.github.com/bappi-d-great/598699df608ce13bbb3c file=”a2-init-npm.txt” /]

This command will create a package.json file and it will look like:

[gist https://gist.github.com/bappi-d-great/598699df608ce13bbb3c file=”a3-package.json” /]

The command will ask you some question, you can leave to default just pressing enter or you can configure.

Now, we have to install dependencies. Of course, the first dependency is gulp itself:

[gist https://gist.github.com/bappi-d-great/598699df608ce13bbb3c file=”a4-install-gulp-locally.txt” /]

The –save-dev flag asks to install the dependencies locally and you will see the updated package.json file with this dependency.

Now, let’s create gulpfile.js file manually, the file name is strict.

Hello World(?) in Gulp

Open the new created gulpfile.js and start configuring. We have just installed a dependency and to use every dependency, we need to use require function.

[gist https://gist.github.com/bappi-d-great/598699df608ce13bbb3c file=”a5-configure-gulpfile.js” /]

As we know, gulp is a task runner, so we will define some tasks, and gulp will run those tasks. The format of a task declaration is simple:

[gist https://gist.github.com/bappi-d-great/598699df608ce13bbb3c file=”a6-define-gulp-task.txt” /]

So, create our first task:

[gist https://gist.github.com/bappi-d-great/598699df608ce13bbb3c file=”a7-gulp-task-example.txt” /]

And run just “gulp mytask” in the terminal. Please note, in the command example first gulp is my plugin folder name, please do not get confused, sorry for that.

The “gulp mytask” will show the output like:

[gist https://gist.github.com/bappi-d-great/598699df608ce13bbb3c file=”a8-gulp-mytask-output.txt” /]

If we want to use more dependencies (of course we will use), then the default format should be:

[gist https://gist.github.com/bappi-d-great/598699df608ce13bbb3c file=”a9- gulp-default-example.js” /]

Here, src function is used to get the source file, pipe function is used to bind with the dependency functions and dest function refers to the destination folder.

Let’s compile SASS

We have learnt about gulp, now let’s do a real task. We will compile sass file and for that we will need to install a dependency:

[gist https://gist.github.com/bappi-d-great/598699df608ce13bbb3c file=”b10-install-gulp-sass” /]

Add in gulp js file:

[gist https://gist.github.com/bappi-d-great/598699df608ce13bbb3c file=”b11-sass-gulpfile.js” /]

Write the task:

[gist https://gist.github.com/bappi-d-great/598699df608ce13bbb3c file=”b12-sass-gulp.js” /]

Write some sass file in about.scss file like:

[gist https://gist.github.com/bappi-d-great/598699df608ce13bbb3c file=”b13-demo-sass.scss” /]

Now run “gulp sass” in the terminal and you will see the generated css file:

[gist https://gist.github.com/bappi-d-great/598699df608ce13bbb3c file=”b14-output-new.css” /]

Please check, in the task, the task name is sass, so we called “gulp sass”, gave the source file in src function, then used pipe function to run sass dependency function, and then sent to the destination.

This is done for one file, what if we have multiple files? We can do is very easily:

[gist https://gist.github.com/bappi-d-great/598699df608ce13bbb3c file=”b15-sass-multiple-files-gulp.js” /]

Now, if you have 3 sass files, it will generate 3 css files. But we want to combine all those. So, let’s install contact dependency:

[gist https://gist.github.com/bappi-d-great/598699df608ce13bbb3c file=”b16-general-single-css-file-from-multiple-sass-file.txt” /]

And add code in gulp js file:

[gist https://gist.github.com/bappi-d-great/598699df608ce13bbb3c file=”b17-gulp-with-contact.js” /]

See, in pipe function, I used concat funtion and gave a file name. All the css files will be combined and get name gulp.main.css and then sent to the destination folder.

Our next job is to minify the generated css, so install minify module:

[gist https://gist.github.com/bappi-d-great/598699df608ce13bbb3c file=”b18-minify-css.txt” /]

Add code in gulp file:

[gist https://gist.github.com/bappi-d-great/598699df608ce13bbb3c file=”b19-gulp-with-minify.js” /]

This is all similar, here I have also mentioned to make compatible to IE8, that’s totally optional.

Let’s do some auto-prefixing job. Like, if you use “display: flex” in your sass file, it will create all the prefixer for that like – -webkit-flex, -ms-flex etc, cool – heh?

So, install auto-prefixer:

[gist https://gist.github.com/bappi-d-great/598699df608ce13bbb3c file=”c20-auto-pre-fixer.txt” /]

Add in gulp file:

[gist https://gist.github.com/bappi-d-great/598699df608ce13bbb3c file=”c21-gulp-with-pre-fixer.js” /]

Another interesting thing, we are going to add – sourcemap. This is very interesting. To debug css, we always use the browser developer toolbar. But when you use sass to write your css, then in browser inspector, you will see reference to css not sass file. Sourcemap will help you to see the reference of sass file, like the screenshot below:

Install sourcemap then:

[gist https://gist.github.com/bappi-d-great/598699df608ce13bbb3c file=”c21-using-sourcemap.txt” /]

Configure in gulp file:

[gist https://gist.github.com/bappi-d-great/598699df608ce13bbb3c file=”c22-gulp-with-sourcemap.js” /]

We are almost done. Just one thing, after doing minify we need to rename the file to with some suffix, like .min. We will use rename module:

[gist https://gist.github.com/bappi-d-great/598699df608ce13bbb3c file=”c23-rename-file.txt” /]

And now configure:

[gist https://gist.github.com/bappi-d-great/598699df608ce13bbb3c file=”c24-gulp-with-rename.js” /]

Please note, in a step I renamed the task name to “build-css”. So, now run in the terminal “gulp build-css” and see the magic! The minified version and combined version will be generated in the css folder.

As we are familiar with the process now, I will go little faster, if any confusion, please comment below.

Let’s play with JS now

For JS files, we will do almost similar things, except we will uglify instead of minify. It’s same but uglify minifies the variable name and do other compression too.

Install uglify then:

[gist https://gist.github.com/bappi-d-great/598699df608ce13bbb3c file=”c25-uglify.txt” /]

And in gulp file:

[gist https://gist.github.com/bappi-d-great/598699df608ce13bbb3c file=”c26-gulp-uglify.js” /]

Now, run “gulp build-js” in terminal and see the output files in js folder.

Do the above jobs on the fly!

Till now, what we have done, if we make any changes we will need to run the command and check in the browser. How’s about doing it more automatic? Like we will make changes, save and right then the above task will be completed. We will ask gulp to watch for any changes, and if any changes found, run the above two tasks.

We will use “watch” command to ask gulp to watch changes.

[gist https://gist.github.com/bappi-d-great/598699df608ce13bbb3c file=”c27-gulp-watch.js” /]

Check at the very bottom, I have defined the watch task which will watch all css and js files for changes and run the corresponding task.

Create po file

In WordPress, we need to provide po file to the users, so that they can translate the strings in their language. We normally use poedit or glotpress to do this job. But now, we will run a php shell command using gulp.

To do that, we will use WordPress’ makepot tool. So, download the wp-dev using svn:

[gist https://gist.github.com/bappi-d-great/598699df608ce13bbb3c file=”d31-mkpot-tool.txt” /]

And the gulp task will be:

[gist https://gist.github.com/bappi-d-great/598699df608ce13bbb3c file=”d32-pot-gulp.js” /]

Here, /Users/ashokkumarnath/Desktop/pot/wp-dev/tools/i18n/makepot.php is the path to makepot.php file which will create the po file. Please replcae the path with your file path.

wp-plugin is used for plugins, if you are developing a theme, use “wp-theme”.

Then the folder name “lang”, in my case, and the text-domain gtd.po. Change gtd with your text-domain.

Now run “gulp i18n” and see the po file is generated in lang folder.

Final touch and release the plugin!

Now, we will copy the files we need for the plugin and paste to releases folder, under the version name:

[gist https://gist.github.com/bappi-d-great/598699df608ce13bbb3c file=”c28-gulp-copy-to-release.js” /]

The created task name is “build” here. We have asked to copy index.php and recurrsive assets folder into releases/VERSION_NO/ folder.

In last step, we will create zip of the plugin, so we will need zip module:

[gist https://gist.github.com/bappi-d-great/598699df608ce13bbb3c file=”c29-zip-module.txt” /]

And create the zip task:

[gist https://gist.github.com/bappi-d-great/598699df608ce13bbb3c file=”d30-gulp-zip.js” /]

You will see at the bottom, I have created a default task for gulp. The default task will run when you command just “gulp” in the terminal. So, when “gulp” command is run in terminal, I have set ‘build-css’, ‘build-js’, ‘build’, ‘zip’ – all four tasks to be run.

Now, if you just run “gulp”, it will compile the sass, create css, combine, create minify version, combine js files, create minified js file, create po file, copy the plugin files and create the releasable zip.

I have done some more polishing in my final gulpfile.js file:

[gist https://gist.github.com/bappi-d-great/598699df608ce13bbb3c file=”e-final-gulpfile.js” /]

In line 65, I asked to run build task only when build-css and build-js tasks are done, not before that. In line 73, the zip task will run, when the build task is done. This is called task dependency.

So, when you will work on css and js, before start working run “gulp watch” in the terminal, do not break/cancel it so that it can run the build-css and build-js when you make some changes. When you are done, just run “gulp”.

This is the final version of package.json:

[gist https://gist.github.com/bappi-d-great/598699df608ce13bbb3c file=”e-final-package.json” /]

This is the final version of main plugin file:

[gist https://gist.github.com/bappi-d-great/598699df608ce13bbb3c file=”e-final-plugin.php” /]

It may look like little complex, but once you practice 2-3 times, it will be very very easy.

So, be automatic! 🙂