calebds/healthy-gulp-angular

This project is a starting point for AngularJS projects using the Gulp streaming build system. Almost everything important is in gulpfile.js.

For a full discussion of the setup, please refer to the companion blog post.

Installation

Before running any Gulp tasks:

1. Check out this repository
2. Ensure you have node installed
3. Run npm install in the root directory (this will install bower dependencies too)
4. For livereload functionality, install the livereload Chrome extension

Project Structure

The project ships with a directory structure like:

/healthy-gulp-angular
|
|---- package.json
|
|---- bower.json
|
|---- gulpfile.js
|
|---- /app
|     |
|     |---- index.html
|     |---- app.js
|     |
|     |---- /styles
|     |     |
|     |     |---- _settings.scss
|     |     |---- app.scss
|     |
|     |---- /components
|           |
|           ...
|
|---- server.js
|
|---- /devServer
|     |
|     |---- ...
|
|---- (/dist.dev)
|
|---- (/dist.prod)

Let's break this down..

package.json

Server-side (command-line) dependencies.

bower.json

Client-side (browser) dependencies.

gulpfile.js

Where all the Gulp streams and tasks are specified. Tasks are outlined below. This file is discussed in detail in the blog post.

/app

All first-party application source code lives here, including HTML, scripts, and styles of whatever flavor.

/app/index.html

The single page app "shell page". Adapted from Angular Seed. All sources are automatically wired in with gulp-inject.

/app/app.js

The app's main angular module is defined here. This file is always loaded first with gulp-angular-filesort.

/app/components

I like to group my angular scripts by comonent. Each sub-directory here typically contains a directive and a matching html partial.

/app/styles

Custom app styles (I use SASS) live here. There's also a foundation settings file.

server.js

This is the entrypoint for the ExpressJS development server. It respects the environment variable NODE_ENV, taking its value as the directory out of which to serve static resources. It defaults to dist.dev to serve development files, and also accepts dist.prod to serve the production files.

/devServer

The scripts for the development server. I'll typically put mock API responses in here.

Processed Sources

The gulp tasks listed below deal with taking sources from /app and "compiling" them for either development or production. *-dev tasks will output to /dist.dev, and *-prod will output to /dist.prod. Here's an overview of the directory structures for each:

/dist.dev

Sources built for development. Styles are compiled to CSS. Everything else from /app is validated and moved directly in here. Nothing is concatenated, uglified, or minified. Vendor scripts are moved in as well.

/dist.dev
|
|---- /bower_components
|
|---- /components
|     |
|     ...
|
|---- /styles
|     |
|     ...
|
|---- app.js
|
|---- index.html

/dist.prod

Sources built for production. Everything is validated, things are concatenated and uglified. HTML partials are pre-loaded into the angular template cache with gulp-ng-html2js.

/dist.prod
|
|---- /scripts
|     |
|     |---- app.min.js
|     |---- vendor.min.js
|
|---- /styles
|     |
|     |---- app.min.css
|
|---- index.html

Pretty self-explanatory.

Gulp Tasks

All of the following are available from the command line.

Essential ones

These tasks I use as part of my regular developments and deploy scripts:

• gulp watch-dev Clean, build, and watch live changes to the dev environment. Built sources are served directly by the dev server from /dist.dev.
• gulp watch-prod Clean, build, and watch live changes to the prod environment. Built sources are served directly by the dev server from /dist.prod.
• gulp Default task builds for prod. Built sources are put into /dist.prod, and can be served directly.

Sub-tasks

All the subtasks can alo be run from the command line:

HTML

• gulp validate-partials Checks html source files for syntax errors.
• gulp validate-index Checks index.html for syntax errors.
• gulp build-partials-dev Moves html source files into the dev environment.

Scripts

• gulp convert-partials-to-js Converts partials to javascript using html2js.
• gulp validate-devserver-scripts Runs jshint on the dev server scripts.
• gulp validate-app-scripts Runs jshint on the app scripts.
• gulp build-app-scripts-dev Moves app scripts into the dev environment.
• gulp build-app-scripts-prod Concatenates, uglifies, and moves app scripts and partials into the prod environment.

Styles

• gulp build-styles-dev Compiles app sass and moves to the dev environment.
• gulp build-styles-prod Compiles and minifies app sass to css and moves to the prod environment.
• gulp build-vendor-scripts-dev Moves vendor scripts into the dev environment.
• gulp build-vendor-scripts-prod Concatenates, uglifies, and moves vendor scripts into the prod environment.

Index

• gulp build-index-dev Validates and injects sources into index.html and moves it to the dev environment.
• gulp build-index-prod Validates and injects sources into index.html, minifies and moves it to the dev environment.

Everything

• gulp build-app-dev Builds a complete dev environment.
• gulp build-app-prod Builds a complete prod environment.
• gulp clean-build-app-dev Cleans and builds a complete dev environment.
• gulp clean-build-app-prod Cleans and builds a complete prod environment.