Scaffolding a new AngularJS project

This quick guide will help you set up a new project structure using generator-gulp-angular—a Yeoman generator for AngularJS with Gulp—that will generate a structure and some demo code from which you can build up your project.

Yeoman generator for AngularJS + Gulp.
Lets you quickly set up a project with:
• your favorite technologies
• web best practices
• guidelines powered by Google
Gulp provide fast workspace with quick feedback.

Dependencies (part one)

To get started you will need npm — the package manager for JavaScript—and Git installed on your system.

On an Arch Linux based system, provided you have permission to use sudo/root, run:

$ sudo pacman -S git npm

and it will automatically install the packages with their dependencies (libuv, http-parser, nodejs, semver).

npm

When you install JavaScript packages using npm, it installs them, by default, locally within your project directory, but you can also install them globally (using the -g flag), which is useful for command-line apps like yo, gulp, bower.

Rules of thumb of when to use globally vs locally:

• Install globally if the package provides command-line tools
• Install locally if you’re using the package as part of your application
• Install globally and locally if both use-cases apply

npm globally without root

The downside of globally installed packages is that you need to be root (or use sudo) to be able to install them if you don’t change the location where npm stores the global packages on your system. It is recommended that you configure npm to install global packages without the need of root privileges.

Create a new directory in your home directory, for example, where the globally installed packages will be stored:

$ mkdir "${HOME}/.npm-packages"

Tell npm where to store globally installed packages by adding

prefix=${HOME}/.npm-packages

to your ~/.npmrc file:

$ echo "prefix=${HOME}/.npm-packages" >> ~/.npmrc

To ensure your shell will find the installed binaries and man pages, add the following to your .bashrc or .zshrc, depending on the shell you are using:

NPM_PACKAGES="${HOME}/.npm-packages"
PATH="$NPM_PACKAGES/bin:$PATH"
# Unset manpath so we can inherit from /etc/manpath via the `manpath` command
unset MANPATH # delete if you already modified MANPATH elsewhere in your config
export MANPATH="$NPM_PACKAGES/share/man:$(manpath)"

If you are running Mac OS X, the .bashrc file may not yet exist, and the shell will be obtaining its environment parameters from another file, such as .profile or .bash_profile. These files also reside in the user’s home directory, so in this case simply adding the following line to them will instruct the shell to also load the .bashrc file:

source ~/.bashrc

After editing the .bashrc file simply run your .bashrc script for the shell to have the newly set up variables defined (or just reopen your terminal window):

$ source ~/.bashrc

Dependencies (part two)

Now that you have npm set up allowing you to install packages globally without root, you can finally install yo (CLI tool for running Yeoman generators), gulp (streaming build system) and bower (browser package manager):

$ npm install -g yo gulp bower

If you now execute which yo, it should find yo binary:

$ which yo
/home/you/.npm-packages/bin/yo

Install generator-gulp-angular, one of Yeoman generators:

$ npm install -g generator-gulp-angular

and you are ready to finally generate the project!

Generating the project

Create a new directory and change to it:

$ mkdir my-project && cd $_

Run yo gulp-angular and you’ll be presented with a set of questions that will help the generator creating the npm and bower configuration files (package.json and bower.json) with the project dependencies which will then be installed when running npm install and bower install, respectively.

$ yo gulp-angular

The generator will ask you about the AngularJS version you want to use, which Angular modules you want to install, jQuery, resource libraries, routers, UI frameworks, CSS preprocessors, JS preprocessors, and HTML template engines. The details about each technology are out of the scope of this guide and would require an article of their own.

? Which version of Angular do you want? (Use arrow keys)
❯ 1.5.x (stable)
  1.2.x (legacy)

? What Angular modules would you like to have? (ngRoute and ngResource will be addressed after) (Press <space> to select)
❯ ◉ angular-animate.js (enable animation features)
  ◉ angular-cookies.js (handle cookie management)
  ◉ angular-touch.js (for mobile development)
  ◉ angular-sanitize.js (to securely parse and manipulate HTML)
  ◉ angular-messages.js (enhanced support for displaying messages within templates)
  ◉ angular-aria.js (support for common ARIA attributes)

? Do you need jQuery or perhaps Zepto? (Use arrow keys)
❯ jQuery 2.x (new version, lighter, IE9+)
  jQuery 1.x (branch still supporting IE6, 7 and 8)
  ZeptoJS 1.1.x (jQuery compatible but very much lighter)
  None (Angular will use its own jqLite)

? Would you like to use a REST resource library? (Use arrow keys)
❯ ngResource, the official support for RESTful services
  Restangular, an alternative service to handle RESTful requests
  None, $http is enough!

? Would you like to use a router? (Use arrow keys)
❯ UI Router, flexible routing with nested views
  ngRoute, the official router
  Angular 2 new router which is compatible with Angular 1 (experimental)
  None

? Which UI framework do you want?
  Bootstrap, the most popular HTML, CSS, and JS framework
❯ Angular Material, the reference implementation of the Google’s Material Design specification
  Material Design Lite, add a Material Design look and feel to your websites.
  Foundation, “The most advanced responsive front-end framework in the world”
  None

? Which CSS preprocessor do you want? (Use arrow keys)
❯ Sass (Node), Node.js binding to libsass, the C version of the popular stylesheet preprocessor, Sass.
  Sass (Ruby), Original Syntactically Awesome StyleSheets (requires Ruby)
  Less, extends the CSS language, adding features that allow variables, mixins, functions and many other techniques.
  Stylus, supporting both an indented syntax and regular CSS style.
  None, only the good old CSS

? Which JS preprocessor do you want?
  None, I like to code in standard JavaScript.
❯ ES6 (Babel formerly 6to5), ECMAScript 6 compiled with Babel which requires no runtime.
  ES6 (Traceur), ECMAScript 6 compiled with the Traceur compiler from Google.
  CoffeeScript, “a little language that compiles into JavaScript”.
  TypeScript, a typed superset of JavaScript that compiles to plain JavaScript.

? Which HTML template engine would you want? (Use arrow keys)
❯ None, I like to code in standard HTML.
  Jade (*.jade)
  Haml (*.haml)
  Handlebars (*.hbs)

Let yo install all the required dependencies for the configuration specified (it will run npm install and bower install for you). At the end you will be presented with this message:

It’s time to use Gulp tasks:
- `$ gulp` to build an optimized version of your application in folder dist
- `$ gulp serve` to start BrowserSync server on your source files with live reload
- `$ gulp serve:dist` to start BrowserSync server on your optimized application without live reload
- `$ gulp test` to run your unit tests with Karma
- `$ gulp test:auto` to run your unit tests with Karma in watch mode
- `$ gulp protractor` to launch your e2e tests with Protractor
- `$ gulp protractor:dist` to launch your e2e tests with Protractor on the dist files

Running the project

Use gulp serve to have a development server running and serving your project:

$ gulp serve
[12:39:53] Using gulpfile ~/my-project/gulpfile.js
[12:39:53] Starting ‘scripts’…
[12:39:53] Starting ‘styles’…
[12:39:54] gulp-inject 2 files into index.scss.
[12:39:54] Finished ‘styles’ after 765 ms
[12:39:57] Time: 3720ms
 Asset Size Chunks Chunk Names
index.module.js 14.4 kB 0 [emitted] main
[12:39:57] Finished ‘scripts’ after 4.53 s
[12:39:57] Starting ‘scripts:watch’…
[12:39:57] Starting ‘inject’…
[12:39:57] gulp-inject 1 files into index.html.
[12:39:57] gulp-inject 1 files into index.html.
[12:39:57] Finished ‘inject’ after 56 ms
[12:39:58] Time: 1027ms
 Asset Size Chunks Chunk Names
index.module.js 34.8 kB 0 [emitted] main
[12:39:58] Finished ‘scripts:watch’ after 1.04 s
[12:39:58] Starting ‘watch’…
[12:39:58] Finished ‘watch’ after 36 ms
[12:39:58] Starting ‘serve’…
[12:39:58] Finished ‘serve’ after 58 ms
[12:39:58] webpack is watching for changes
[BS] [BrowserSync SPA] Running…
[BS] Access URLs:
 — — — — — — — — — — — — — — — — — -
 Local: http://localhost:3000/
 External: http://10.0.2.15:3000/
 — — — — — — — — — — — — — — — — ---
 UI: http://localhost:3001
 UI External: http://10.0.2.15:3001
 — — — — — — — — — — — — — — — — — -
[BS] Serving files from: .tmp/serve
[BS] Serving files from: src

It will open the page for you (http://localhost:3000/) on your default browser.

File structure

The newly generated project has the following file structure. You can create new components at src/app/components (and then import them in index.modules.js) and set new routes in index.route.js.

my-project
├── bower_components — bower local packages (by bower install)
│   ├── (17 directories)
│   └── …
├── bower.json — bower config. and browser dependencies
├── e2e
│   ├── main.po.js
│   └── main.spec.js
├── gulp — streaming build system partial configs.
│   ├── build.js
│   ├── conf.js
│   ├── e2e-tests.js
│   ├── inject.js
│   ├── scripts.js
│   ├── server.js
│   ├── styles.js
│   ├── unit-tests.js
│   └── watch.js
├── gulpfile.js — streaming build system main config.
├── karma.conf.js — (JavaScript test runner) config.
├── node_modules — npm local packages (by npm install)
│   ├── (795 directories)
│   └── …
├── package.json — npm config. and project dependencies
├── protractor.conf.js — (end-to-end testing for AngularJS) config.
└── src
    ├── app
    │   ├── components
    │   │   ├── githubContributor
    │   │   │   ├── githubContributor.service.js
    │   │   │   └── githubContributor.service.spec.js
    │   │   ├── malarkey
    │   │   │   ├── malarkey.directive.js
    │   │   │   ├── malarkey.directive.spec.js
    │   │   │   └── malarkey.scss
    │   │   ├── navbar
    │   │   │   ├── navbar.directive.js
    │   │   │   ├── navbar.directive.spec.js
    │   │   │   ├── navbar.html
    │   │   │   └── navbar.scss
    │   │   └── webDevTec
    │   │       ├── webDevTec.service.js
    │   │       └── webDevTec.service.spec.js
    │   ├── index.config.js
    │   ├── index.module.js
    │   ├── index.route.js
    │   ├── index.run.js
    │   ├── index.scss
    │   └── main
    │     ├── main.controller.js
    │     ├── main.controller.spec.js
    │     └── main.html
    ├── assets
    │   └── images
    │       ├── angular-material.png
    │       ├── angular.png
    │       ├── babel.png
    │       ├── browsersync.png
    │       ├── gulp.png
    │       ├── jasmine.png
    │       ├── karma.png
    │       ├── node-sass.png
    │       ├── protractor.png
    │       └── yeoman.png
    ├── favicon.ico
    └── index.html

From here you can build up your project. Have fun!