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
you're set.
This is simply a boilerplate. git clone
or git remote add
this repository
to continue. And then:
npm install -g grunt-cli
npm install -g bower
pip install pygments
npm install
bower install
app/assets/index.html
, remember to configure your project by playing
around with the window.CURVE_APP
global variable.Configuration is done via the window.CURVE_APP
global object. Available
configuration:
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.js
so
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 domainelement
: This is the root element that the loader will bootstrap on.
Default to the document.body
elementgrunt
to get Karma running, watching for file changes, and a server
running in the backgroundlocalhost:8888
in the newly Karma-opened browser to view your appgrunt
Development mode:
localhost:8888
localhost:9876
grunt server
Server watch mode. Like development mode but without test server (i.e.
Karma). Files are updated and served on localhost:8888
grunt test
Test mode. This is like development mode with a local webserver and Karma, except that it runs only once, designed for continuous integration
grunt compile
Compile the app
grunt watch
Watch for file changes in source and re-compile. This is a grunt compile
that
runs on file change.
grunt build
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
public/_dev
.
grunt clean
This resets the project to its pristine state.
grunt push:target
Build the project and push to a remote server.
Sub-commands:
grunt push:s3
pushes to S3grunt release
Release a new version. It does a few things:
origin
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.html
sets all the required parameters specific to the app (via
window.CURVE_APP
, see the Configuration section)loader.js
then fill in the blanks for parameters that are not provided
values; then make the LazyLoad library
available; then loads all the style and script filesdocument.body
index.coffee
is run, then
application.coffee
and so forthAnything found in the Brunch plugin ecosystem is supported! By default this application supports:
.css
, .js
(duh!).coffee
.litcoffee
.sass
.less
.styl
.hbs
.eco
.jade
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
to curve.templates.extensions
in bower.json
as angular-curve needs to know
which files are templates to prepend app.js
.
Under the app
directory:
public/app.js
*.spec.js
and *.spec.coffee
) are
compiled into the file public/spec.js
public/app.css
public/app.js
.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 bower.json
file. Specifically, add the output file name without extension as the key of
the object 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: app.js
and vendor.js
.
A before
and 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/somewhere/called/home.js
and app/welcome.js
(this first) into
public/local.js
and app/where/am/i.js
into public/remote.js
.
...
"curve": {
"javascripts": {
"order": {
"before": {
"app/welcome.js"
}
},
"splitTo": {
"local": [
"app/somewhere/called/home.js",
"app/welcome.js",
],
"remote": [
"app/where/am/i.js"
]
}
}
}
...
Because developing in Angular requires many external libraries, package management should be automated using Bower. Follow these steps:
bower search <package-name>
bower install --save <package-name>
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.
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 public/
.
Source maps of the compiled files are available in development mode.
$GEM_HOME
on your command-line or in config.coffee
. Check
sass-brunch for more info/* ... */
in JavaScript and ### ... ###
in CoffeeScript)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).
This project is Heroku-ready. Simply add a Heroku multipack buildpack:
heroku config:set BUILDPACK_URL=https://github.com/ddollar/heroku-buildpack-multi