angularjs-boilerplate

Based on great boilerplate by jakemmarsh.

View contributors

Getting up and running

1. Clone this repo from https://github.com/mzahor/angularjs-boilerplate.git or use a generator
2. Run npm install from the root directory
3. Run gulp dev (may require installing Gulp globally npm install gulp -g)
4. Your browser will automatically be opened and directed to the browser-sync proxy address
5. To prepare assets for production, run the gulp prod task (Note: the production task does not fire up the express server, and won't provide you with browser-sync's live reloading. Simply use gulp dev during development. More information below)

Now that gulp dev is running, the server is up as well and serving files from the /build directory. Any changes in the /app directory will be automatically processed by Gulp and the changes will be injected to any open browsers pointed at the proxy address.

To run tests:

• gulp test - will run unit tests as well as e2e.
• gulp tdd - will run unit tests and watch for changes, then run tests again in a cycle

This boilerplate uses the latest versions of the following libraries:

• AngularJS
• SASS
• Gulp
• Browserify

Along with many Gulp libraries (these can be seen in either package.json, or at the top of each task in /gulp/tasks/).

AngularJS

AngularJS is a MVW (Model-View-Whatever) Javascript Framework for creating single-page web applications. In this boilerplate, it is used for all the application routing as well as all of the frontend views and logic.

The AngularJS files are all located within /app/js, structured in the following manner:

/common (common functionality for all modules)
    /components (common components)
    /directives (common directives)
    /filters (common filters)
    /services (common services)
/movies (application module, can be many of them)
    /components
        movie.component.js (simple component, contains html and logic)
        movie.component.scss (styling for movie.component)
        movie.component.spec.js (tests for movie.component)
        movies.view.component.html (separate html for component)
        movies.view.component.js (view component, responsible for rendering the
whole route)
        movies.view.component.scss (styling for view component)
        movies.view.component.spec.js (tests for view component)
    /directives (non-component directives)
    /services (services which should contain business logic)
    /filters 
constants.js  (any constant values that you want to make available to Angular)
main.js       (the main file read by Browserify, also where the application is defined and bootstrapped)
on_run.js     (any functions or logic that need to be executed on app.run)
on_config.js  (all route definitions and any logic that need to be executed on app.config)
templates.js  (this is created via Gulp by compiling your views, and will not be present beforehand)

Module organization

Controllers, services, directives, etc. should all be placed within their respective folders, and should be required and mounted via their respective index.js. All modules must export an object of the format:

const MovieComponent = function() {};

export default {
    name: 'MovieComponent',
    // possible options are:
    // 'component', 'service', 'directive', 'filter', 'factory', 'service'
    type: 'component', 
    // this function will be called to get the object for registration
    fn: MovieComponent,
};

Take a look at /movies/index.js for example.

Dependency injection

Dependency injection is carried out with the ng-annotate library. In order to take advantage of this, a simple directive prologue of the format:

function MyService($http) {
  'ngInject';
  ...
}

needs to be added at the very beginning of any Angular functions/modules. The Gulp tasks will then take care of adding any dependency injection, requiring you to only specify the dependencies within the function parameters and nothing more.

Web Server

There are 2 web server tasks:

• gulp testServer - runs Express.js server (port 3003 by default)
• gulp dev - runs browserSync (port 3000 for app, 3001 for browserSync settings)

The first one has basic backend api implementation and is used for protractor. Second one hosts UI files and uses proxy middleware to connect to backend api, which may reside on another server.

Usually you will use gulp dev for development as it rebuils the bundle and reloads the website every time you change a file. You can reconfigure the proxy to point to any backend server you want (see next section).

Api server proxy

There is a simple testServer which exposes /api/movies endpoint. You can run it with gulp testServer. Frontend is connected to it using proxy middleware which resides in browserSync gulp task. Proxy target is configurable, so you can redirect it to any server you want depending on your needs (use proxyTarget property in /gulp/config.js). Test server is also used to run e2e tests. If you want to run your e2e tests with another backend - change baseUrl in protractor.conf.js.

Pre-compressing text assets

When running with gulp prod, a pre-compressed file is generated in addition to uncompressed file (.html.gz, .js.gz, css.gz). This is done to enable web servers serve compressed content without having to compress it on the fly. Pre-compression is handled by gzip task.

Testing

This boilerplate also includes a simple framework for unit and end-to-end (e2e) testing via Karma and Jasmine. In order to test AngularJS modules, the angular.mocks module is used.

All of the tests can be run at once with the command gulp test. However, the tests are broken up into two main categories:

TDD

There is a task for TDD development: gulp tdd

End-to-End (e2e) Tests

e2e tests, as hinted at by the name, consist of tests that involve multiple modules or require interaction between modules, similar to integration tests. These tests are carried out using the Angular library Protractor, which also utilizes Jasmine. The goal is to ensure that the flow of your application is performing as designed from start to finish.

In this boilerplate, two end-to-end test examples are provided:

• routes_spec.js, which tests the functionality of our AngularJS routing
• example_spec.js, which tests the functionality of the example route, controller, and view

More examples can be seen at the above link for Protractor.

All e2e tests are run with gulp protractor.

Notes:

• before running the Protractor tests, the application server must be running (start it with gulp dev)
• the Protractor library used for the end-to-end tests may require installing the Java JDK beforehand.

Production Task

Just as there is the gulp dev task for development, there is also a gulp prod task for putting your project into a production-ready state. This will run each of the tasks, while also adding the image minification task discussed above. There is also an empty gulp deploy task that is included when running the production task. This deploy task can be fleshed out to automatically push your production-ready site to your hosting setup.

Reminder: When running the production task, gulp will not fire up the express server and serve your index.html. This task is designed to be run before the deploy step that may copy the files from /build to a production web server.