angular.next v0.1.2

<angular-next>Generation Application</angular-next>

Angular.NEXT repository is designed as a forward thinking, next generation Angular 1 baseline application with a gulp component generator that follows the component-based pattern. The patterns and design decisions made in this repository were made with Angular 2 in mind.

By adhering to modularity and componentization of all features and views in the application, Angular.NEXT is prepared for an easy migration from version 1 to 2 once you or your team is ready to make that leap.

In the meantime, Angular.NEXT is built for scale and maintainability in large, complex enterprise applications and one of the biggest advantages and benefits it provides the end user is the ability to scale horizontally in large numbers without affecting the maintainability index of the application.

Why put off to tomorrow what can be done today? The future is here and now with Angular.NEXT.

EXPLAINED WITH CODE

app.js

angular.next() = (ng) => {
    ng.pattern('component-based')
}

gulp.babel.js.js

import es6 from 'js-features';
import babel from 'js-transpiler';
import webpack from 'build-system';
import angular from '1-to-2-migration-plan';
import component from 'component-based-pattern';

let angular = () => es6.next();

angular.task('baseline', (done) => {
    sync(webpack, babel, es6, next, done); 
});

APPLICATION FEATURES:

• Angular
• ES6
• Webpack
• Babel
• Component-Based Pattern

This repository serves as a starter or baseline project for building advanced, complex enterprise Angular applications written with ES6, using Gulp and Webpack for the build process.

• These are its features:
• The best practice in directory / file organization for Angular using the Component-Based Pattern
• A ready-to-go build system for working with ES6
• Gulp Tasks for generating additional boilerplate Angular components
• A full testing system in place
• Stylus support

TABLE OF CONTENTS

• Walkthrough
  • Build System
  • File Structure
  • Testing Setup
• Getting Started
  • Dependencies
  • Installing
  • Running the App
    • Gulp Tasks
    • Testing * Generating Components

WALKTHROUGH

BUILD SYSTEM

Angular.NEXT uses Gulp and Webpack together for its build system.

Webpack handles all file-related concerns:

• Transpiling from ES6 to ES5 with Babel
• Loading HTML files as modules
• Transpiling stylesheets and appending them to the DOM
• Bundling the app
• Loading all modules
• Doing all of the above for *.spec.js files as well

Gulp is the orchestrator:

• Starting and calling Webpack
• Starting a development server
• Refreshing the browser and rebuilding on file changes
• Generating boilerplate for the Angular app

FILE STRUCTURE

I use a componentized approach with Angular.NEXT. This will be the standard with Angular 2 and helpful, if using Angular's new router. Everything is a component. A component is a self-contained concern such as a feature or strictly-defined UI element such as a header, sidebar, or footer. Other characteristic of a component is that it contains its own stylesheet, template, controller, route, service, and test specification. Here's how it looks:

CLIENT

• app/
• app.js * app entry file
• app.html * app template
• common/ * functionality pertinent to several components propagate into this directory
• components/ * where components live
• components.js * components entry file
• home/ * home component
  • home.js * home entry file (routes, configurations, and declarations occur here)
  • home.component.js * home "directive"
  • home.controller.js * home controller
  • home.styl * home styles
  • home.html * home template
  • home.spec.js * home specs (for entry, component, and controller)

TEST SETUP

All tests are also written in ES6. I use Webpack to take care of the logistics of getting those files to run in the various browsers, just like with my client files. This is my test stack:

• Karma
• Webpack + Babel
• Mocha
• Chai

To run tests, type npm test or karma start in the terminal. Read more about testing (below).

GETTING STARTED

DEPENDENCIES

Tools needed to run this app:

• node and npm

Once you have these, install the following as globals: npm install -g gulp karma karma-cli webpack

INSTALLING

• fork this repo
• clone your fork
• npm install to install dependencies

RUNNING THE APP

Angular.NEXT uses Gulp to build and launch the development environment. After you have installed all dependencies, you may run the app. Running gulp will bundle the app with webpack, launch a development server, and watch all files. The port will be displayed in the terminal.

GULP TASKS

Here's a list of available tasks:

• webpack
  • Runs Webpack, which will transpile, concatenate, and compress (collectively, "bundle") all assets and modules into client/bundle.js.
• serve
  • Starts a dev server via browser-sync, serving the client folder.
• watch
  • Listens for file changes, rebuilds with Webpack, then refreshes the browser.
• default * Runs webpack, serve, and watch--in that order.
• component
  • Scaffolds a new Angular component. Read (below) for usage details.

TESTING

To run the tests, run npm test or karma start.

Karma combined with Webpack runs all files matching *.spec.js inside the app folder. This allows us to keep test files local to the component which keeps us in good faith with continuing to build our app modularly. The file spec.bundle.js is the bundle file for all our spec files that Karma will run.

Be sure to define your *.spec.js files within their corresponding component directory. You must name the spec file like so, [name].spec.js. If you don't want to use the .spec.js suffix, you must change the regex in spec.bundle.js to look for whatever file(s) you want.

Mocha is the testing suite and Chai is the assertion library. If you would like to change this, see karma.conf.js.

GENERATING COMPONENTS

Following a consistent directory structure between components offers us the certainty of predictability. We can take advantage of this certainty by creating a gulp task to automate the "instantiation" of our components. The component boilerplate task generates this:

• component-name/
• component-name.js // entry file where all its dependencies load
• component-name.component.js
• component-name.controller.js
• component-name.html
• component-name.styl // scoped to affect only its own template
• component-name.spec.js // contains passing demonstration tests

To generate a component, run gulp component --name componentName

TASK ARGUMENTS AND CONFIGURATION

The parameter following the --name flag is the name of the component to be created.

The component will be created inside client/app/components.

To change this, apply the --parent flag, followed by a path relative to client/app/components/

CODE EXAMPLE

GENERATE COMPONENT TASK

    gulp component --name signUp --parent auth

OUTPUT

    client/app/components/auth/sign-up/
    client/app/components/auth/sign-up/sign-up.js
    client/app/components/auth/sign-up/sign-up.component.js
    client/app/components/auth/sign-up/sign-up.controller.js
    client/app/components/auth/sign-up/sign-up.html
    client/app/components/auth/sign-up/sign-up.styl
    client/app/components/auth/sign-up/sign-up.spec.js

GENERATE COMMON TASK

    gulp common --name footer

OUTPUT

    client/app/common/footer/
    client/app/common/footer/footer.js
    client/app/common/footer/footer.component.js
    client/app/common/footer/footer.controller.js
    client/app/common/footer/footer.html
    client/app/common/footer/footer.styl
    client/app/common/footer/footer.spec.js

IMPORTANT NOTE:

Because the argument to --name applies to the folder name and the actual component name, make sure to camelcase the component names.

An example of this would be gulp component --name teamMembers --parent companyNews

This would produce snake-case file name and directory from the gulp component task.

The output of this would be client/app/components/company-news/team-members