###An AngularJS application Reference Architecture
Build AngularJS applications with CoffeeScript - without the ceremony. By the way, you can write JavaScript too.
- Installing
- Running
- Scripting
- Styling
- Templating
- Structure
- Features
- Configuration
- Contributing
- Changelog
- License
Before running, you must install and configure the following one-time dependencies:
Enter the following in the terminal
Option 1: Using Yeoman Generator (Recommended)
$ npm install -g gulp yo
$ npm install -g generator-fatarrow
$ mkdir my-new-project && cd $_
$ yo fatarrow
Option 2: Clone this repo
$ npm install -g gulp
$ git clone git@github.com:DedicatedWebStar/fatarrow.git
$ cd fatarrow
$ npm install
Here are some useful commands to get started:
Get all commands and options by typing
$ gulp help
Running with With a fake backend ($httpBackend)
$ gulp
With a real backend (gulp will proxy calls to the backend of your choice)
$ gulp --backend
Build for production
$ gulp --prod --no-serve
Run tests on your build server
$ npm test
$ npm test
$ gulp --prod --no-serve
# deploy to a path (configuration in /config/locationConfig.coffee)
$ gulp deploy
# deploy to S3 (configurtion in /config/s3Config.coffee)
$ gulp deploy --target s3
Your choice of scripting languages.
- JavaScript
- Babel
- CoffeeScript
- LiveScript
- TypeScript
Your choice of styling languages.
Your choice of templating engines.
- File extensions supported by fatarrow:
- Scripts:
.coffee
,.js
,.ls
,.ts
,.es6
- Styles:
.less
,.css
,.scss
- Templates:
.html
,.haml
,.jade
- Scripts:
(Note: to keep the example succint, .coffee
, .html
and .less
extensions are used below. However, all of the file extensions listed above can be used, and even can be mix-and-matched.)
The root directory generated for a fatarrow app:
├── e2e/ ├── config/ ├── src/ │ ├── components/ │ │ └── comp/ │ │ │ ├── test │ │ │ ├── └── comp.spec.coffee │ │ │ ├── comp.coffee │ │ │ └── comp.html │ │ │ └── comp.backend.coffee │ │ │ └── comp.less │ ├── app/ │ │ ├── app.coffee │ │ ├── appRoutes.coffee │ │ └── views.backend.coffee │ ├── home/ │ │ ├── homeController.coffee │ │ ├── homeRoutes.coffee │ │ └── home.html │ ├── img/ │ │ └── angularjs.jpg │ └── index.html ├── tasks/ ├── bower_components/ ├── nodes_modules/ ├── .bowerrc ├── .gitignore ├── bower.json ├── gulpfile.coffee ├── package.json
Explanation of the folders:
src/app
: Angular module for the app. All app level config should go here.src/home
: Each feature of the app should go in its own folder. It should contain all scripts, styles, templates and tests within the feature folder.src/components
: Reusable components (directives, factories, styles, etc.)e2e
: Protractor tests. They should also be separated by features/components.config
: Configurtion for gulp tasks broken up by each task.
- Fake data: Running
gulp
will include the.backend.coffee
files and therefore Angular's $httpBackend will be utilized. This should be used for backendless development. - Real data: Running
gulp --backend
will proxy all backend calls to the backend of your choice. See below for configuration instructions. - Production build: Running
gulp --prod
will produce builds for production. This includes:- ngAnnotate : make your angular code minification proof
- ngClassify : CoffeeScript classes for angular
- minification : JS, CSS and HTML
- image minification: images from teh
img
folder are compressed - rev: minified files are rev'ed for browser cache busting
- templatecache : take all angular templates and include them in the minified scripts
- deploy: deploy to a path or to AWS S3. see above for commands.
- Dev Workflow:
- watch : watch your
src
folder and rebuild and reload automatically - linting : lint
.js
and.coffee
files. style checking and fixing with JSCS - test : run e2e (protractor) and unit (karma) tests
- browserSync : test on multiple devices simultaneously
- newer: only process changed files
- HTML5Mode: Angular's html5Mode is supported on the BrowserSync server. Be sure to configure your production web server. HTMO5Mode is turned on by default. See Angular's documentation to turn it off for browser compatibility.
- plato: perform code visualization, static analysis, and complexity analysis
- watch : watch your
- .jscsrc: options for JSCS. See reference
- .jshintrc: options for jsHint. See reference
(Note: Configuration for the rest of the gulp plug-ins lives in the config
folder.)
- app.coffee
APP_NAME
: name of the angular module for the app
- bower.coffee
BOWER_COMPONENTS
: consume dependencies from bower by specifying dependency name, version, dependency type (scripts, styles, etc.) and a list of files to be consumed (cherry picking files).
- coffeeLint.coffee: options for linting CoffeeScript. See reference
- e2e.coffee: options for protractor. See reference.
- karma.coffee: options for karma. See reference
- languages.coffee: disable compilers not in use to optimize your build
- less.coffee: options for the less compiler. See reference
- locationDeploy.coffee: deploy app to a path
- plato.coffee: options for plato. See reference
- s3Deploy.coffee: options to deploy to AWS S3. See reference
SCRIPTS
: load order for scripts- server.coffee: options for browser-sync development server
PROXY_CONFIG
: proxy backend calls during development with connect-modrewrite. See referencePORT
: run app on a specific port (default: 8181)
STYLES
: load order for styles
You need three pieces of information for each Bower component to include in your app.
- The Bower component name (e.g. restangular)
- The version of the component (e.g. 1.4.0)
- The files within the component to include in your app (e.g. restangular.min.js)
The following will include the restangular component, version 1.4.0, and place the dist/restangular.min.js
file in the vendor/scripts
directory. By default, all Bower components will be placed in the vendor
directory.
BOWER_COMPONENTS =
'restangular': '1.4.0':
scripts: 'dist/restangular.min.js'
If load order is important, include a reference to the file in the SCRIPTS section.
The following will ensure restangular is loaded prior to app.js
.
SCRIPTS =
'**/angular.min.js'
'**/restangular.min.js'
'**/app.js'
'**/*.js'
For AngularJS components, include a reference to the module within your application. For example:
angular.module('app', ['restangular']);
See CONTRIBUTING.md
See CHANGELOG.md
See LICENSE