You should be able to develop AngularJS without having to set anything up. This is an opinionated workflow in developing front-end project with AngularJS. If you have an opinion on a best practice to employ, please send in a pull request!
For AngularJS development, angular-seed is a great starting point. ngBoilerplate is a fantastic improvement over angular-seed. Though you still need to install a bunch of dependencies and tinker with the Gruntfile somewhat.
Rather than handling everything as a monolithic asset pipeline, ng-brunch
offloads the assembly workflow to Brunch. You need
additional language support? Check out the Brunch plugins
page, do a
npm install, and
- Entirely Grunt-based: you only need one interface
- Docco-style documentation that expects JSDoc
- Bower-powered package management
- Component.io for modularity with private repositories
- Dead-easy, drop-in support of your favorite preprocessors and tools with Brunch. See supported file types for more info
- Heroku for staging. This project can host itself on Heroku out of the box
- Follow CoffeeScript Style Guide
- Follow general CSS notes, advice, and guidelines
- Commits follow AngularJS Git Commit Message Conventions
- Use IcoMoon for application graphic assets in SVG
This is simply a boilerplate.
git clone or
git remote add this repository
to continue. And then:
- I assume you have Node.js/NPM
- You need Grunt:
npm install -g grunt-cli
- You also need Bower:
npm install -g bower
- Install Pygments so that Docker can
generate documentation for you, docco-style:
pip install pygments
- Get NPM deps:
- Get Bower deps:
app/assets/index.html, remember to configure your project by playing around with the
Configuration is done via the
window.CURVE_APP global object. Available
name: The application name that will be registered with Angular. Use this other than hard-coding your application name as that saves you from having to go into the loader and hard-code the name there. When changing the name in
index.html, you must also change it in
app/assets/_dev/test_setup.jsso that Karma has the same configuration as in normal environment.
base: This is the base URL to load the rest of the assets. Default to the current domain
element: This is the root element that the loader will bootstrap on. Default to the
gruntto get Karma running, watching for file changes, and a server running in the background
localhost:8888in the newly Karma-opened browser to view your app
- Start watching for file changes
- Spin up a local webserver on
- Start up Karma at
Server watch mode. Like development mode but without test server (i.e.
Karma). Files are updated and served on
Test mode. This is like development mode with a local webserver and Karma, except that it runs only once, designed for continuous integration
Compile the app
Watch for file changes in source and re-compile. This is a
grunt compile that
runs on file change.
Build the app in production mode (compiled + minified + uglified). When
building, everything under
public/_dev directory will be removed, so
non-production code (e.g. testing setup code) would live happily in
This resets the project to its pristine state.
Build the project and push to a remote server.
grunt push:s3pushes to S3
Release a new version. It does a few things:
- Perform a full build
- Rebuild documentation using Docker
- Bump version: see version bumping
- Build changelog: see changelog building
- Make a commit with version number, semvar style
- Tag the commit with version number
- Push to remote
After having set up the project, the file structure would look like:
app/ -> Anything specific to the app goes here app/assets/ -> Anything here is copied over to top-level directory as-is app/assets/index.html -> The index page app/assets/loader.js -> This is the bootstrapper that starts it all app/common/ -> Run before everything else in `app/` app/application.coffee -> The top-level controller app/application.spec.coffee -> Sample test cases for ApplicationController app/index.coffee -> The entry point, where module definition takes place bower_compoennts/ -> Downloaded Bower components etc/karma.conf.coffee -> The Karma configuration file node_modules/ -> downloaded NPM modules public/ -> The built files lives here bower.json -> Bower dependency declaration Gruntfile.coffee -> Gruntfile configuration LICENSE -> Pretty self-explanatory package.json -> NPM dependency declaration README.md -> This document
angular-curve loads everything asynchronously. Here's what it does to bootstrap the application:
index.htmlsets all the required parameters specific to the app (via
window.CURVE_APP, see the Configuration section)
loader.jsthen fill in the blanks for parameters that are not provided values; then make the LazyLoad library available; then loads all the style and script files
- AngularJS then bootstraps the application on the base element, default to
- At this point, Angular has control and
index.coffeeis run, then
application.coffeeand so forth
Supported file types
Anything found in the Brunch plugin ecosystem is supported! By default this application supports:
- Literate CoffeeScript:
Add more by running
npm install --save yourDesiredFileTypeHere-brunch.
Search on NPM with
yourDesiredFileTypeHere brunch for the correct NPM module.
Or visit the plugin directory
to hunt for your gems!
If you add a new template preprocessor, remember to add the relevant extensions
bower.json as angular-curve needs to know
which files are templates to prepend
*.spec.coffee) are compiled into the file
- Style files are compiled into one CSS file
Custom build paths
You can designate specific source files to be built to a specific output file.
For instance, angular-curve by default builds angular-mocks to the file
public/vendor_test.js. angular-mocks should not be part of the general
vendor.js file because it is not needed in production.
You may optionally define your own build paths by modifying the
file. Specifically, add the output file name without extension as the key of
splitTo with the value being an array of files to build to the
specified output file. angular-curve will exclude these files from any of the
normal output files:
after may be used in an
order attribute. Files at the paths
specified in those two attributes are placed either before or after the rest of
the script files.
The following configuration would put the content of
app/welcome.js (this first) into
Because developing in Angular requires many external libraries, package management should be automated using Bower. Follow these steps:
- Find the package you want by running
bower search <package-name>
bower install --save <package-name>
- That's it! :D
Remember that Bower provides a powerful
bower link facility. If you are
including another Bower-enabled repo, simply run
bower link in that repo's
root directory and then
bower link <nameAsInBowerJsonHere> in the dependent
directory. Locally linked repos greatly simplify the development process.
App file structure
There is no convention here. Scripts, styles, and markups are compiled to
public/. Anything under
assets/ is treated as assets and are transferred
as-is to the top-level directory under
Source maps of the compiled files are available in development mode.
- compass: configure Compass by defining
$GEM_HOMEon your command-line or in
config.coffee. Check sass-brunch for more info
- Docker: generate documentation on build. Note
that Docker only recognizes JSDoc declaration when it's in a block-style
### ... ###in CoffeeScript)
- autoprefixer: uses Can I use to autoprefix your CSS
- cache manifest: you should always include a manifest so that the browser knows what to cache. angular-curve uses appcache-brunch to build the manifest
Documentation is generated into the
doc/ directory. However, generated files
are not checked into source. You must deal with the output yourself. In the
future, this will push directly to a configured AWS S3 bucket (#9).
Staging on Heroku
This project is Heroku-ready. Simply add a Heroku multipack buildpack:
heroku config:set BUILDPACK_URL=https://github.com/ddollar/heroku-buildpack-multi