Angular Core Dependency: ^1.5.0
Module License: MIT
Added by: Sam Deering
npm installfrom the root directory
gulp dev(may require installing Gulp globally
npm install gulp -g)
gulp prodtask (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 devduring development. More information below)
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.
This boilerplate uses the latest versions of the following libraries:
Along with many Gulp libraries (these can be seen in either
package.json, or at the top of each task in
The AngularJS files are all located within
/app/js, structured in the following manner:
/controllers _index.js (the main module on which all controllers will be mounted, loaded in main.js) example.js /directives _index.js (the main module on which all directives will be mounted, loaded in main.js) example.js /services _index.js (the main module on which all services will be mounted, loaded in main.js) example.js 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)
Controllers, services, directives, etc. should all be placed within their respective folders, and will be automatically required via their respective
bulk-require. Most other logic can be placed in an existing file, or added in new files as long as it is required inside
Dependency injection is carried out with the
ng-annotate library. In order to take advantage of this, a simple comment of the format:
/** * @ngInject */
needs to be added directly before any Angular functions/modules. The Gulp tasks will then take care of adding any dependency injection, requiring you only to specify the dependencies within the function call and nothing more.
SASS, standing for 'Syntactically Awesome Style Sheets', is a CSS extension language adding things like extending, variables, and mixins to the language. This boilerplate provides a barebones file structure for your styles, with explicit imports into
app/styles/main.scss. A Gulp task (discussed later) is provided for compilation and minification of the stylesheets based on this file.
require('modules') in all of your files in the same manner as you would on the backend in a node.js environment. The bundling and compilation is then taken care of by Gulp, discussed below.
Gulp is a "streaming build system", providing a very fast and efficient method for running your build tasks.
Gulp is used here to provide a very basic node/Express web server for viewing and testing your application as you build. It serves static files from the
build/ directory, leaving routing up to AngularJS. All Gulp tasks are configured to automatically reload the server upon file changes. The application is served to
localhost:3002 once you run the
gulp task. To take advantage of the fast live reload injection provided by browser-sync, you must load the site at the proxy address (within this boilerplate will by default be
localhost:3000). To change the settings related to live-reload or browser-sync, you can access the UI at
require('module')statements, compiling the files as necessary.
require()statements in your code, mapping them to
bower_componentswhen necessary. This allows you to use and include bower components just as you would npm modules.
The resulting file (
main.js) is placed inside the directory
Just one plugin is necessary for processing our SASS files, and that is
gulp-sass. This will read the
main.scss file, processing and importing any dependencies and then minifying the result. This file (
main.css) is placed inside the directory
Any images placed within
/app/images will be automatically copied to the
build/images directory. If running
gulp prod, they will also be compressed via imagemin.
When any changes are made to the
index.html file, the new file is simply copied to the
/build/ directory without any changes occurring.
/app/views/, on the other hand, go through a slightly more complex process. The
gulp-angular-templatecache module is used in order to process all views/partials, creating the
All of the Gulp processes mentioned above are run automatically when any of the corresponding files in the
/app directory are changed, and this is thanks to our Gulp watch tasks. Running
gulp dev will begin watching all of these files, while also serving to
localhost:3002, and with browser-sync proxy running at
localhost:3000 (by default).
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.
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
A Gulp tasks also exists for running the test framework (discussed in detail below). Running
gulp test will run any and all tests inside the
/test directory and show the results (and any errors) in the terminal.
All of the tests can be run at once with the command
gulp test. However, the tests are broken up into two main categories:
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. The command
npm run-script preprotractor should be run once before running any Protractor tests (in order to update the webdrivers used by Selenium).
Unit tests are used to test a single module (or "unit") at a time in order to ensure that each module performs as intended individually. In AngularJS this could be thought of as a single controller, directive, filter, service, etc. That is how the unit tests are organized in this boilerplate.
An example test is provided for the following types of AngularJS modules:
Testing AngularJS directives becomes a bit more complex involving mock data and DOM traversal, and so has been omitted from this boilerplate. This can be read about in detail here.
All unit tests are run with
gulp unit. When running unit tests, code coverage is simultaneously calculated and output as an HTML file to the
Module stats last updated: 2017-03-12 16:00:03