Basic Gulp with APEX

Update April-23-2016: Deprecated this package in favor of APEX Nitro.

Update Feb-28-2015: Added image optimization to the Gulpfile.

Note: I have given a more interactive presentation in January 2015 at @InsumSolutions office about how to integrate Gulp in your APEX workfow.

Visit my Github repo for the source code.

I have discovered task runners in 2014, after seeing the rising popularity of Grunt.

I thought it was okay. The code was somehow complicated, but the outcome was nice: it concatenates files, minifies files, checks for errors, and much more.

Really, who doesn't like automatic stuff? I mean come on... No more JS syntax error? I'm sold!

Then I discovered Gulp.

It offers the same features as Grunt, with simpler coding.

Here a run-down of what's being covered by my Gulpfile:

Error Handling:
Any syntax error you make, Gulp will precisely tell you where, in a user friendly way. Useful isn't it?

Applies for JS & CSS.

File concatenation:
At some point, your JS or CSS is going to get big. Do yourself a favor and modularize your code. I swear you're gonna like looking at it afterwards.

On the other side, the machine doesn't have to deal with your modularization. It's better to have a single HTTP request rather than multiple, right?

Gulp will parse all your files and concatenate them into one single file, making it easier for you to code and easier for the machine to read.

Applies for JS & CSS.

File minification:
Does the machine need your indentation? Or the spaces? No. Minification removes that. It also renames your significant variables names to a, b, c, etc.

I have seen minification do wonders. Really, it can cut your file size down to half... It's worth it, I swear.

Applies for JS & CSS.

File Size Output:
This is more of a "bonus feature", but when Gulp concatenates and minifies your files, it shows you the file size before and after. It's just satisfying.

Applies for JS & CSS.

CSS Autoprefixer:
Do you know CSS vendor prefixes? If you don't, just skip this section.

Still here? Have a look at this:
a { -webkit-transition: -webkit-transform 1s; transition: -ms-transform 1s; transition: transform 1s; }

Isn't that iritating? Why can't we just write this:
a { transition: transform 1s; }

I don't know about you, but I don't want to remember the CSS vendor prefixes...

Gulp Autoprefixer comes to the rescue. You can now just write transition: transform 1s; and it'll parse all the vendor prefixes for you!

Applies for CSS only.

**UPDATE Feb-28-2015 Image Optimization:
Optimizes your image files for better production performance. See screenshot in the Setup section and notice a 38.8% filesize reduction! I compared both images side by side and it looks 100% identical.

The goal:

As you may know, there are so many places where you can put JS & CSS in APEX that eventually you will get lost. Especially for new APEX developpers, you know how messy it can get.

The goal is to get your JS & CSS out of APEX, in a centralized & clean system.

Side note: I saw even more JS & CSS placeholders in APEX 5 EA3. I understand the need for that much flexibility, but it does complicates development and maintenance.

Requirements:

1. Install Node.js
2. Install Dropbox (could be another cloud platform)
3. Basic CLI understanding (Command line interface).

Setup:

1. Go to your Dropbox /Public/ folder and from there, fork my Github repository.
2. Open a command prompt and cd to your project root folder
3. From your project root folder, run:
   • npm install (this is the part where it installs Gulp and its dependencies)
   • npm start
4. Open your favorite text editor, start coding your assets.
5. Replace all the assets from my Github repo with your project assets
   • /Public/basic-gulpfile/client/assets/css/
   • /Public/basic-gulpfile/client/assets/js/
   • /Public/basic-gulpfile/client/assets/vendor/

I explain how to use it in APEX further.

Starting from step (3), Gulp is watching any changes you make to your files, it compiles them and sends them over to the new /build/ folder, automatically.

In the screenshot below:

• demo1.css and demo2.css are compiled to app.css and app.min.css
• demo1.js and demo2.js are compiled to app.js and app.min.js
• anything in /client/assets/vendor/ are copied to /build/assets/vendor/

But first, why Dropbox?

Because we want to be working on a Public folder, meaning that your files will be publicly available through a simple URL.

Yeah okay but where's the benefit??

In APEX! Where else? Now you can have an APEX substitution string that points to your Dropbox folder!

You will actually be able to code directly in your text editor, and upon save, your changes will instantly be reflected on your APEX application!

Isn't that nice??

Usage in APEX:

1. Let's declare an APEX substitution string called: PATH
   with this value: https://dl.dropboxusercontent.com/u/13765392/rnd/gulp/build/ (to be replaced by your Dropbox public path).

2. Go to your page template

3. Add those files:

• <link rel="stylesheet" href="&PATH.assets/css/app#MIN#.css">
• <script src="&PATH.assets/js/app#MIN#.js"></script>

(As pointed by @rimblas, we should use #MIN# for our files, as in app#MIN#.css. Then, under normal run it expands to .min, but in debug mode it will be empty.)

And that's all! Enjoy a faster & cleaner static files handling.

Important notice:

Now obviously... the Dropbox part is meant for development only. When going to production, you carry the /build/ folder somewhere else and change the APEX substitution string.

The effort is minimal, and it's really worthwhile in my opinion.

Happy coding :)