angular-auth-seed: A JavaScript repository from safris

angular-auth-seed

The complete basic auth pattern, and seed for AngularJS

Why do we keep reinventing the wheel? The authentication patten has been done and done again 1,000,000 times. Instead of spending the first two weeks of development on the authentication requirement, get a jump-start on your business logic immediately.

This project is based on angular-seed, with the addition of a complete and functional basic auth pattern. The added features include registration, login, and forgot password functionality.

This project is the countepart (the front-end component) of the jax-rs-auth-seed project. Together, these two projects provide you with a fully functional platform for authenticated applications based on AngularJS and Java's JAX-RS 2.0.

NOTE: This project is intended for someone looking for a platform with a front-end and back-end component.

This project has been configured with a build setup based on Gulp for workflow management, Karma for unit testing, Protractor for end-to-end testing, LESS for a CSS pre-processor, template pre-caching using gulp-angular-templatecache, app.js concatenation and minification for production builds.

Created with the highest standard of development in mind, this project uses best practices and patterns to empower the developer to write code that is clear, cohesive, and easily testable.

The angular-auth-seed project is a complete solution, intended to be bug-free and an instant "plug-and-play" base to get you started quickly and easily. Preconfigured to install the Angular framework, development prerequisites, and testing tools for instant web deployment gratification, this solution can be used to quickly bootstrap your Angular project and dev environment.

Demo

To see the jax-rs-auth-seed project in action, please see the demo here.

Getting Started

To get you started, you can simply clone the angular-auth-seed repository. A detailed walkthrough is described below.

Prerequisites

git - The version control system client needed to clone the angular-auth-seed repository.
Node.js - The JavaScript runtime for the development tools.

Clone `angular-auth-seed`

Clone the angular-auth-seed repository using git:

git clone git@github.com:SevaSafris/angular-auth-seed.git
cd angular-auth-seed

If you want to start a new project without the angular-auth-seed commit history, then you can do:

git clone --depth=1 git@github.com:SevaSafris/angular-auth-seed.git <your-project-name>

The depth=1 tells git to only pull down one commit worth of historical data.

Install Dependencies

The angular-auth-seed project has two kinds of dependencies:

1. Tools for development

The tools are necessary to create the environment for the project to be installed, developed, tested, and deployed.

bower - The client-side package manager needed to install Angular framework libraries.

npm -g install bower

This installs bower in the npm's global context, making it available on the $PATH for CLI execution.

gulp - The automation tool used to build, run, and test the application.

npm -g install gulp

This installs gulp in the npm's global context, making it available on the $PATH for CLI execution.

npm dependencies - The tools needed in the development process.

npm install

This installs npm dependencies in the node_modules subdirectory of the project's root.

Java Development Kit (JDK) - In order to run the end-to-end tests, you will also need to have Java installed on your machine. Check out the section on end-to-end testing for more info.

2. Angular framework libraries

The runtime platform of the application.

bower dependencies - The framework and supplementary libraries.

bower install

This installs bower dependencies in the app/lib path off the project's root.

NOTE: The app/lib directory is the custom path configured for bower to install its components, as specified in the .bowerrc file in the project's root. By default, this path would be bower_components, and is overridden to make it easier to serve the files from a web server.

Run the Application

The project is preconfigured with a simple development web server, which can be easily started with:

gulp start

Now browse to the app at localhost:3000.

Once started, gulp will watch for changes made to the src paths (configured in gulpfile.js), and will automatically recompile the relevant application assets.

Build and Development Workflow

The angular-auth-seed project uses gulp for workflow management, which refers to gulpfile.js for definitions of the following tasks:

build:index - Copy and interpolate src/index.html to app directory.

--prod: Generates index.html for production server deployment.
--scheme <SCHEME>: Override API scheme (http|https).
--host <HOST>: Override API host (localhost:8080|mycompany.com|...).
default: Generates index.html for localhost deployment.

build:html - Pre-cache html templates located in src/template/**/*.html to app/js/templates.js.
clean:html - Remove app/js/templates.js.
build:css - Translate LESS templates in src/less/**/*.less to app/css directory.
clean:css - Remove app/css directory.
build:js - Build JavaScript source.

--prod: Concatenate, annotate, minify and uglify JavaScript source files located at src/js/**/*.js, as well as the html templates at src/template in app/js/app.min.js, and create sourcemap in app/js/app.min.js.map.
default: Concatenate and annotate JavaScript source files located at src/js/**/*.js in app/js/app.js, and create sourcemap in app/js/app.js.map.

clean:js - Remove app/js.
test:unit - Run unit tests and put reports in test directory. See here for more details.

--watch: Run unit tests in "watch mode".
default: Run unit tests in "singleRun mode".

clean:test:unit - Remove app/test directory.
test:e2e - Run end-to-end tests. See here for more details.
test - Run test:unit and test:e2e tasks.
clean - Run clean:css, clean:html, clean:js, and clean:test:unit tasks.
build - Run build:index, build:css, build:html, and build:js tasks.
start - Run build task; start watching for changes on the src.js, src.less, and src.html paths; start the development webserver.

Concatenation, Annotation, and Pre-Caching

The angular-auth-seed project is designed with cohesion in mind. The build workflow pushes a lot of complexity of the JavaScript loading and template pre-caching to "build time", instead of "run time". This allows developers to catch errors before the applicatioin is loaded in the browser -- errors that would otherwise be realized once the application is executed. To accomplish this, the project has been configured with the Gulp Workflow Manager to concatenate and annotate the JavaScript source to app/js/app.js, and pre-cache the html templates to app/js/templates.js for development, and otherwise into a single app/js/app.min.js for production (with the --prod argument passed to gulp).

When developing, the webserver is bootstrapped by watch tasks that detect changes to source files, CSS, and templates. When a change is detected, the relevant task is performed to regenerate the appropriate compiled asset. When executed, the compilation tasks send messages to the OS's notification system upon successful execution.

Adding Dependencies with Bower

Bower is the dependency management tool used to import client-side code, modules, and frameworks. When installing a new package via bower, you must include the package's main file to be loaded by your application. This is most commony done by editing index.html in most projects. However, in this project, this is different, because all JavaScript and html template resources are combined (concatenated, annotated, and pre-cached) into a single app/js/app.js (or app/js/app.min.js for --prod builds) file. To include newly installed bower packages to the build, you must edit the lib array defined in the // Paths section of gulpfile.js.

Production Builds

For production builds, you can execute the same gulp tasks, but with a --prod argument. This will automatically update your index.html files with the paths of the minified and uglified app.min.js.

Directory Layout

.bowerrc            --> `bower` configuration
.gitignore          --> `git` ignored paths
.jshintrc           --> `jshint` configuration
.travis.yml         --> Travis Cl configuration
bower.json          --> `bower` specification for project
gulpfile.js         --> `gulp` specification for project
karma.conf.js       --> `Karma` unit test tool configuration
package.json        --> `npm` specification for project
protractor.conf.js  --> `Protractor` end-to-end test tool configuration
README.md           --> this file
app/                --> distribution path of the application assets
src/                --> application source files
  index.html        --> app layout file (parameterized for `gulp build:index`)
  js/               --> JavaScript source files
    app.js          --> application module, configuration, and initialization
    controllers.js  --> controller modules
    directives.js   --> directive modules
    factories.js    --> factory modules
    providers.js    --> provider modules
    services.js     --> service modules
  less/             --> LESS CSS source files
    app.less        --> main LESS file
  template/         --> html templates
    about.html      --> About page
    contact.html    --> Contact page
    home.html       --> Home page
    login.html      --> Login page
    profile.html    --> Profile page
    reset.html      --> Reset Password page
    template.html   --> general template
    component/      --> template components
      footer.html   --> footer component
      navbar.html   --> navbar component
      sidebar.html  --> sidebar component
    modal/          --> templates for modal overlays
      loading.html  --> loading overlay
  test/             --> application test sources
    e2e/            --> end-to-end test sources
      login.js      --> end-to-end test for login
    unit/           --> unit test sources
      factories.js  --> unit test for factory modules

Testing

There are two kinds of tests in the angular-auth-seed application: Unit tests and end-to-end tests.

Running Unit Tests

The angular-auth-seed app contains example unit tests. The tests are written in Jasmine, which runs with the Karma test runner. A Karma configuration file is provided, and is integrated to the gulp workflow manager.

The unit tests are located at src/test/unit.
The configuration is found in karma.conf.js, as well as gulpfile.js.

To run the unit tests as a single execution, use gulp to launch the tests:

gulp unit:test

This script will start the Karma test runner to execute the unit tests in "singleRun mode".

The "singleRun mode" is useful if you want to check that a particular version of the code is operating as expected.

Karma is initially configured to use the PhantomJS runtime for testing, to make the execution as unintrusive as possible. Note, running PhantomJS with singleRun = true will cause the process to hang for up to 30s before it quits. This is a known issue that is still pending to be fixed.

Karma can also be configured to watch the source and test files for change. When executed in "watch mode", Karma will watch for changes and re-run tests automatically. To launch the tests in "watch mode", simply:

gulp unit:test --watch

Running unit tests in "watch mode" is the recommended strategy; if your unit tests are being run every time you save a file then you receive instant feedback on any changes that break the expected code functionality.

Unit Test Reports

The unit tests are configured to produce reports of the tests, which are put in the app/test directory off the project's root. These include:

JUnit Report - A JUnit-style report file with test results.
Coverage Report - A code coverage report site.

Running End-to-End Tests

The angular-auth-seed app comes with end-to-end tests, which are also written in Jasmine. These tests are run with the Protractor End-to-End test runner. It uses native events and has special features for Angular applications.

The configuration is found in protractor-conf.js.
The end-to-end tests are found in src/test/e2e.

Protractor simulates interaction with the application and verifies that the application responds correctly. As the application requires a back-end component for end-to-end execution, Protractor must use its webDriver to simulate the back-end functionality.

Before end-to-end tests can execute successfully, the Protractor webDriver must be initialized.

npm run update-webdriver

Once webDriver is configured, ensure that the application is started:

gulp start

Finally, you can run end-to-end tests:

gulp test:e2e

This script will execute the end-to-end tests against the application being hosted in the local development environment.

Note: Under the hood, Protractor uses the Selenium Standalone Server, which in turn requires the Java Development Kit (JDK) to be installed on your local machine. Check this by running java -version from the command line.

If JDK is not already installed, you can download it here.

Updating Angular

Since the Angular framework library code and tools are acquired through package managers (npm and bower) you can use these tools to easily update the dependencies:

npm -g update
npm update
bower update

Serving the Application Files

As Angular is client-side-only technology, you will need to complement your application stack with a back-end component. The angular-auth-seed project is designed to communicate with a server using RESTful APIs. As a complement to the angular-auth-seed project, we provide a similar back-end project that implements the server-side RESTful service providers based on Java's JAX-RS 2.0 specification. The back-end server project can be found here.

Continuous Integration

Travis CI

Travis CI is a continuous integration service, which can monitor GitHub for new commits to your repository and execute scripts such as building the app or running tests. The angular-seed project contains a Travis configuration file, .travis.yml, which will cause Travis to run your tests when you push to GitHub.

You will need to enable the integration between Travis and GitHub. See the Travis website for instructions on how to do this.

Contact

If you have any comments or experience issues, please report them here.

For more information on AngularJS please check out angularjs.org.

License

This project is licensed under the MIT License - see the LICENSE.txt file for details.

safris/angular-auth-seed