Welcome to your project! We've made a number of opinionated choices up front to avoid common pitfalls in JavaScript application architecture. We've also included a few of our favorite helper libraries to handle common problems in development. Everything is modular, tested, and encapsulated. If you don't like something, just swap it out or remove it.
Take a few minutes to get familiar with your project's directory structure. This isn't everything, but it's the important parts:
app.js
defines the node.js application used to run Expressbower.json
is Bower's dependenciesGruntfile.js
is the Grunt configuration file. It reads in config properties and loads all tasks.package.json
contains npm dependenciesREADME.md
is the file that you're readingapp/
contains all frontend application code, including CSS, templates, etc.css/
holds application stylesheetsapp.less
is the master application LESS file which additionally imports all other LESS filesless/
contains sub-LESS filescomponents/
holds individual LESS components to be imported by other LESS files
js/
holds AngularJS application codeapp.js
is the base AngularJS applicationcontrollers/
contains AngularJS controllerscontrollers.js
references all controllers in the application to allow for a single dependency import
directives/
holds AngularJS directives and works likecontrollers/
filters/
is for AngularJS filters and also works likecontrollers/
services/
contains AngularJS services and works like... you guessed itlib/
holds external libraries, e.g.,bower_components/
, packages installed by Bower.
templates/
contains application component HTML templates (often for directives)
dist/
is generated by the Grunt production compilation and will contain a reduced subset of the project's directory structure. It doesn't exist by default.express/
holds Express (server) filesconfig/
holds configuration filesexpress.js
sets Express configuration optionsroutes.js
defines Express routes
routes/
holds Express route controllersapi.js
imports API (data-returning) routesindex.js
defines the base, index-rendering route (single-page app)
views/
defines Express (Jade) views
grunt/
holds Grunt configurationsconfig/
holds individual task configurations, as well as a few special files:appBowerScripts.js
, defining the bower-loaded scripts that should be loaded in each mode (development/test/production)appExternalScripts.js
, defining the externally-hosted scripts that should be loaded in each modeappScripts.js
, defining what application scripts should be imported in each modeappStyles.js
, defining what CSS should be imported in each modeappTemplates.js
, defining what templates will need to be compiled to what location, in each mode
tasks/
holds custom Grunt tasks
node_modules/
holds all of the installed npm modulestest/
holds application test informationconf/
holds Karma and Protractor configuration filese2e
holds end-to-end/integration tests executed by Protractorunit
holds unit test executed by Karma, which should be set up more or less to mirror theapp/js
directory
Frequent development tasks are encapsulated by grunt tasks. These are designed to make your life easier and automate repetitive or time-consuming processes.
grunt
with test:all
every so often while you code and serve:development
when you want to see your work.
Use compile:
with target development
, test
, or production
when you want to create a usable copy of your
application that fits one of those states.
To run your app, run serve:
with one of the same three targets. (You don't need to compile
or anything first;
we'll do that for you.)
test
runs tests in a target's tasks
against the application to check for problems. Specifically:
test:lint
lints/hints your LESS (and resultant CSS) and your JS (all of it)test:unit
runs Karma unit teststest:e2e
runs Protractor end-to-end teststest:all
runs all of 'em above, in order
compile
reads a set of tasks
and executes each to produce some useful output synthesized from some thoughtful input.
compile:development
sets the grunt environment todevelopment
, compiles LESS into CSS, creates thelayout.jade
intermediary files, and compiles the application templates.compile:test
does the same asdevelopment
, but intest
mode (which may or may not differ and doesn't by default for simplicity).compile:production
- sets the grunt environment to
production
, - cleans and recreates a resultant directory,
dist
, - copies and minifies Express (node.js) application files for fastest node.js server execution,
- copies
node_modules
, - compiles LESS into CSS and minifies it,
- optimizes all images,
- copies Bower-referenced JavaScript libraries,
- creates a single, minified
app.min.js
encompassing all frontend application JavaScript code, including all template data statically preloaded into the template cache, - compiles/copies intermediary-free application templates,
- minifies the node.js
app.js
. - Whew!
- sets the grunt environment to
serve
executes the steps needed to run your project by running a set of tasks
.
serve:development
means run my application as it stands right now. It runscompile:development
to do a dev compile,express:development
to start an Express application server, andwatch:expressDevelopment
to keep Express running and watch for file changes that might need to trigger a rebuild.serve:test
means test my application and run it if everything is good. It runstest
, then does the same asserve:development
but intest
mode (which includes the suppression of Express output).serve:production
means test my application, and if it's ready, create a production-ready instance of it and run that. It runstest
, then does the same asserve:development
but inproduction
mode.
We've included grunt-bump
for you and set it up to synchronize your
bower.json
and package.json
versions according to SemVer.
Frontend
- AngularJS
- AngularUI State Router (optionally, or else the standard AngularJS router)
Backend
Design
Management
- npm
- Bower
- Grunt (with a lot of tasks)
- David DM (nothing to install, but we recommend checking it out)
- Travis CI (.travis.yml set up and ready to go)
Testing
- Protractor
- Karma (with a bunch of helper libs)
- Mocha
- Chai
- Chai-as-promised
- Sinon.js
- Sinon-Chai
Helper libraries