Quick Tutorial to install Gulp and Gulp-PostCSS to enable CSS Import, Nesting, Variables & Auto Prefix

6 min readJan 18, 2018

Requirements

I assume that you already learn about basic Node.JS and basic CSS, you should already install Node.JS, if you haven’t installed Node.JS then you may visit this site for the “easy to follow guide” to install Node.JS.

Quick Introduction — What is Gulp and Gulp-PostCSS?

In short,

Gulp is a toolkit for automating painful or time-consuming tasks in your development workflow, so you can stop messing around and build something.
PostCSS is a gulp plugin to pipe CSS through several plugins, but parse CSS only once.

In this Tutorial we will use both Gulp and PostCSS to automate process CSS file with @import features, CSS variables and nested CSS to be supported in any browser.

Before we start

When i mention an application Terminal, this doesn’t mean this tutorial is limited to Linux/MacOS only, it would be Command Prompt or Git Bash on Windows, same thing goes for term Directory on Linux/MacOS is the same as Folder in Windows.

Lets start!

Initialize NPM

Create project directory somewhere you’d like to work on, and move working directory into it and type:

$ npm init -y

The -y flag means tell npm to not prompting for package.json’s naming, version, description and other metadata, or you could just run npm init without -y flag if you wanted to.

Install Gulp

Install gulp-cli globally (why?):

$ npm install gulp-cli -g

Let’s try to run below command to check Gulp version and to test whether gulp-cli is successfully installed or failed:

$ gulp -v
[12:02:21] CLI version 2.0.0

If you see something like above, then you’re good to go.
Note: if you failed install Gulp on Linux/MacOS, you might try to prefix sudo before npm command, so it’s like sudo npm install gulp-cli -g.

Now, we should install gulp locally (why?) into the project directory:

$ npm install gulp --save-dev

The -save-dev flag means the gulp will go in DevDependencies area in npm’s package.json file, now we gonna create Gulp Task.

Create Gulp Task

Create new file gulpfile.js in you project directory root, so the structure will be like this:

Now, open gulpfile.js, require gulp dependencies and write default task like so:

Save and the task is created, now run:

$ gulp

Above command will run default task, if the gulpfile.js is correct, this will result:

This mean the default task is run successfully, now let’s install gulp-postcss.

Install gulp-postcss

Type below command to install gulp-postcss:

$ npm install gulp-postcss --save-dev

Since gulp-postcss is only a plugin to pipe CSS, now it’s nothing special it can do, we need gulp-postcss plugin, lets install several gulp-postcss plugins:

$ npm install postcss-simple-vars postcss-nested postcss-import autoprefixer --save-dev

The name for each package function are actually obvious, postcss-simple-vars is a package for CSS Variables, postcss-nested is a package for Nested CSS, postcss-import is for CSS@import features, and autoprefixer is a package for automatic CSS Vendor Prefix for each famous browser engine.

Now, you may remove default task, require gulp-postcss package and every gulp-postcss plugin packages we just installed:

Create gulp-postcss and name it styles task, so the complete gulpfile.js will be:

The starting point of CSS will be in ‘app/assets/styles.css’, and the processed css output will be in ‘app/styles’.
We need to create styles.css and test if the task works, lets create some sample CSS file in app/assets/styles directory, so the directory would be like this:

Let’s create css variables in _variables.css file:

We may test nested CSS in _navbar.css file:

Global CSS style, _global.css:

And import _variables.css, _global.css and _navbar.css files to main CSS file, the styles.css. The order of importing files are very important, the _variables.css file should be on the top, otherwise _navbar.css will fail reading the variables!
let’s jump to styles.css file:

Testing!

Now, lets run styles task:

Before we jump to next step, lets create index.html file in app directory, so we can test the compiled styles.css file right away:

Ok, lets check the output ‘app/styles/styles.css’, the content should be:

Now open file index.html:

Congratulations! you’ve accomplished this tutorial, but is it really finished?Next step will be about gulp-watch, why we need it? let’s find out.

Gulp-watch

Everytime we make changes to styles.css file, we have to run the repetitive routine: run styles task and refresh the browser to see any changes. If the our project is relatively small and change to the files are rare then it’s fine, but what if you write code for big project? you have to run tasks and refresh your browser again and again everytime you make changes to the project, i don’t know about you, but at least for me the routine get tedious fast.

As a developer it’s good practice that we eleminate any unnecessary repetitive routine by automation.

As in this tutorial, we want gulp to watch any changes to files, and automatically run styles task and refresh the browser, so we can get the job done faster and more fun, but how do we accomplish that? this is where gulp-watch come to play, okay let’s begin by install npm package named gulp-watch!

$ npm install gulp-watch --save-dev

Before we write a task watch for watching change and do automation, we have to install browser-sync package, Browsersync works by injecting an asynchronous script tag (<script async>...</script>) right after the <body> tag during initial request, so after the styles.css is compiled, the Browsersync will inject styles.css file to index.html without refreshing our browser, cool right? now let’s install browser-sync:

$ npm install browser-sync --save-dev

Now, open gulpfile.js and require gulp-watch and browser-sync:

Still in gulpfile.js let’s add watch and cssInject task:

Here is what happen:
When we run watch task, the Browsersync will init the configuration, then the task will watch index.html and any CSS files on location ‘app/assets/styles’, if the watch task found any changes, thus browserSync.reload() and cssInject task will be triggered.

You might thinking

when will the styles task triggered to recompile the styles.css file?

After the watch task found changes, it will immediately run the cssInject task. But cssInject task will wait for styles task to complete first, if you look at the cssInject task, you will notice [“styles”] inline with the start of the task, this mean the styles task will go first then the function.

Now switch back to terminal and let’s run watch task:

$ gulp watch

If you see something like this and a browser with localhost address is open instantly, it’s mean you watch task is running successfully.

[20:05:54] Using gulpfile C:\gulp-tutorial\gulpfile.js
[20:05:54] Starting 'watch'...
[20:05:54] Finished 'watch' after 26 ms
[Browsersync] Access URLs:
 --------------------------------------
       Local: http://localhost:3000
    External: http://x.x.x.x:3000
 --------------------------------------
          UI: http://localhost:3001
 UI External: http://x.x.x.x:3001
 --------------------------------------
[Browsersync] Serving files from: app

Just one more problem…

You might aware if you did mistake in css code syntax, the watch task will error and quit immediately, you have to fix the css code and back running watch task again everytime this happen, undoubtedly we want the task to just display error and keep running, let’s fix this.

Open gulpfile.js, and modify styles task:

Now re-run the watch task and test write wrong css syntax intentionally and viola! the watch task keep running and will recompile the styles.css if you correct the syntax.

See the completed project files on GitHub: https://github.com/tonywei92/Gulp-PostCSSTutorialFiles.git

Now, this is end of the tutorial, see you next time in another tutorial guys!