Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

generator-angular-sparkstack

DaftMonk162.0.13

Yeoman generator for creating MEAN stack applications, using MongoDB, Express, AngularJS, and Node

yeoman-generator, mean, mongodb, angularjs, express, scaffold, fullstack, framework, component, front-end, app

readme

AngularJS Full-Stack generator Build Status Gitter chat

Yeoman generator for creating MEAN stack applications, using MongoDB, Express, AngularJS, and Node - lets you quickly set up a project following best practices.

Example project

Generated with defaults: http://fullstack-demo.herokuapp.com/.

Source code: https://github.com/DaftMonk/fullstack-demo

Usage

Install generator-angular-fullstack:

npm install -g generator-angular-fullstack

Make a new directory, and cd into it:

mkdir my-new-project && cd $_

Run yo angular-fullstack, optionally passing an app name:

yo angular-fullstack [app-name]

Run grunt for building, grunt serve for preview, and grunt serve:dist for a preview of the built app.

Prerequisites

  • MongoDB - Download and Install MongoDB - If you plan on scaffolding your project with mongoose, you'll need mongoDB to be installed and have the mongod process running.

Supported Configurations

Client

  • Scripts: JavaScript, CoffeeScript
  • Markup: HTML, Jade
  • Stylesheets: CSS, Stylus, Sass, Less,
  • Angular Routers: ngRoute, ui-router

Server

  • Database: None, MongoDB
  • Authentication boilerplate: Yes, No
  • oAuth integrations: Facebook Twitter Google
  • Socket.io integration: Yes, No

Injection

A grunt task looks for new files in your client/app and client/components folder and automatically injects them in the appropriate places based on an injection block.

  • less files into client/app.less
  • scss files into client/app.scss
  • stylus files into client/app.styl
  • css files into client/index.html
  • js files into client/index.html
  • coffeescript temp js files into client/index.html

Generators

Available generators:

App

Sets up a new AngularJS + Express app, generating all the boilerplate you need to get started.

Example:

yo angular-fullstack

Endpoint

Generates a new API endpoint.

Example:

yo angular-fullstack:endpoint message
[?] What will the url of your endpoint be? /api/messages

Produces:

server/api/message/index.js
server/api/message/message.spec.js
server/api/message/message.controller.js
server/api/message/message.model.js  (optional)
server/api/message/message.socket.js (optional)

Route

Generates a new route.

Example:

yo angular-fullstack:route myroute
[?] Where would you like to create this route? client/app/
[?] What will the url of your route be? /myroute

Produces:

client/app/myroute/myroute.js
client/app/myroute/myroute.controller.js
client/app/myroute/myroute.controller.spec.js
client/app/myroute/myroute.html
client/app/myroute/myroute.scss

Controller

Generates a controller.

Example:

yo angular-fullstack:controller user
[?] Where would you like to create this controller? client/app/

Produces:

client/app/user/user.controller.js
client/app/user/user.controller.spec.js

Directive

Generates a directive.

Example:

yo angular-fullstack:directive myDirective
[?] Where would you like to create this directive? client/app/
[?] Does this directive need an external html file? Yes

Produces:

client/app/myDirective/myDirective.directive.js
client/app/myDirective/myDirective.directive.spec.js
client/app/myDirective/myDirective.html
client/app/myDirective/myDirective.scss

Simple directive without an html file

Example:

yo angular-fullstack:directive simple
[?] Where would you like to create this directive? client/app/
[?] Does this directive need an external html file? No

Produces:

client/app/simple/simple.directive.js
client/app/simple/simple.directive.spec.js

Filter

Generates a filter.

Example:

yo angular-fullstack:filter myFilter
[?] Where would you like to create this filter? client/app/

Produces:

client/app/myFilter/myFilter.filter.js
client/app/myFilter/myFilter.filter.spec.js

Service

Generates an AngularJS service.

Example:

yo angular-fullstack:service myService
[?] Where would you like to create this service? client/app/

Produces:

client/app/myService/myService.service.js
client/app/myService/myService.service.spec.js

You can also do yo angular-fullstack:factory and yo angular-fullstack:provider for other types of services.

Decorator

Generates an AngularJS service decorator.

Example:

yo angular-fullstack:decorator serviceName
[?] Where would you like to create this decorator? client/app/

Produces

client/app/serviceName/serviceName.decorator.js

Openshift

Deploying to OpenShift can be done in just a few steps:

yo angular-fullstack:openshift

A live application URL will be available in the output.

oAuth

If you're using any oAuth strategies, you must set environment variables for your selected oAuth. For example, if we're using Facebook oAuth we would do this :

rhc set-env FACEBOOK_ID=id -a my-openshift-app
rhc set-env FACEBOOK_SECRET=secret -a my-openshift-app

You will also need to set DOMAIN environment variable:

rhc config:set DOMAIN=<your-openshift-app-name>.rhcloud.com

# or (if you're using it):

rhc config:set DOMAIN=<your-custom-domain>

After you've set the required environment variables, restart the server:

rhc app-restart -a my-openshift-app

To make your deployment process easier consider using grunt-build-control.

Pushing Updates

grunt

Commit and push the resulting build, located in your dist folder:

grunt buildcontrol:openshift

Heroku

Deploying to heroku only takes a few steps.

yo angular-fullstack:heroku

To work with your new heroku app using the command line, you will need to run any heroku commands from the dist folder.

If you're using mongoDB you will need to add a database to your app:

heroku addons:add mongohq

Your app should now be live. To view it run heroku open.

If you're using any oAuth strategies, you must set environment variables for your selected oAuth. For example, if we're using Facebook oAuth we would do this :

heroku config:set FACEBOOK_ID=id
heroku config:set FACEBOOK_SECRET=secret

You will also need to set DOMAIN environment variable:

heroku config:set DOMAIN=<your-heroku-app-name>.herokuapp.com

# or (if you're using it):

heroku config:set DOMAIN=<your-custom-domain>

To make your deployment process easier consider using grunt-build-control.

Pushing Updates

grunt

Commit and push the resulting build, located in your dist folder:

grunt buildcontrol:heroku

Bower Components

The following packages are always installed by the app generator:

  • angular
  • angular-cookies
  • angular-mocks
  • angular-resource
  • angular-sanitize
  • angular-scenario
  • es5-shim
  • font-awesome
  • json3
  • jquery
  • lodash

These packages are installed optionally depending on your configuration:

  • angular-route
  • angular-ui-router
  • angular-socket-io
  • angular-bootstrap
  • bootstrap

All of these can be updated with bower update as new versions are released.

Configuration

Yeoman generated projects can be further tweaked according to your needs by modifying project files appropriately.

A .yo-rc file is generated for helping you copy configuration across projects, and to allow you to keep track of your settings. You can change this as you see fit.

Testing

Running grunt test will run the client and server unit tests with karma and mocha.

Use grunt test:server to only run server tests.

Use grunt test:client to only run client tests.

Protractor tests

To setup protractor e2e tests, you must first run

npm run update-webdriver

Use grunt test:e2e to have protractor go through tests located in the e2e folder.

Environment Variables

Keeping your app secrets and other sensitive information in source control isn't a good idea. To have grunt launch your app with specific environment variables, add them to the git ignored environment config file: server/config/local.env.js.

Project Structure

Overview

├── client
│   ├── app                 - All of our app specific components go in here
│   ├── assets              - Custom assets: fonts, images, etc…
│   ├── components          - Our reusable components, non-specific to to our app
│
├── e2e                     - Our protractor end to end tests
│
└── server
    ├── api                 - Our apps server api
    ├── auth                - For handling authentication with different auth strategies
    ├── components          - Our reusable or app-wide components
    ├── config              - Where we do the bulk of our apps configuration
    │   └── local.env.js    - Keep our environment variables out of source control
    │   └── environment     - Configuration specific to the node environment
    └── views               - Server rendered views

An example client component in client/app

main
├── main.js                 - Routes
├── main.controller.js      - Controller for our main route
├── main.controller.spec.js - Test
├── main.html               - View
└── main.less               - Styles

An example server component in server/api

thing
├── index.js                - Routes
├── thing.controller.js     - Controller for our `thing` endpoint
├── thing.model.js          - Database model
├── thing.socket.js         - Register socket events
└── thing.spec.js           - Test

Contribute

See the contributing docs

This project has 2 main branches: master and canary. The master branch is where the current stable code lives and should be used for production setups. The canary branch is the main development branch, this is where PRs should be submitted to (backport fixes may be applied to master).

By seperating the current stable code from the cutting-edge development we hope to provide a stable and efficient workflow for users and developers alike.

When submitting an issue, please follow the guidelines. Especially important is to make sure Yeoman is up-to-date, and providing the command or commands that cause the issue.

When submitting a PR, make sure that the commit messages match the AngularJS conventions.

When submitting a bugfix, try to write a test that exposes the bug and fails before applying your fix. Submit the test alongside the fix.

When submitting a new feature, add tests that cover the feature.

See the travis.yml for configuration required to run tests.

License

BSD license

changelog

v2.0.13 (2014-08-29)

Bug Fixes

  • gen:
    • use bool for bootstrap filters (a5decbc3, closes #496)
    • fix build when not selecting socket.io (fdf063c6)

v2.0.12 (2014-08-25)

Bug Fixes

  • revert multiple strategies per account, which shouldn't go in a patch release

v2.0.11 (2014-08-25)

Bug Fixes

  • app: Use parentheses to fix string concat in config (c6a50ce7, closes #466)
  • gen: use more restrictive version range for ng-component (19698973)

Features

  • socket.io: build socket.io into vendor.js (06f2e46e)
  • docs: Inform users/developers of the canary branch (74693623)
  • gen: make generator tests faster, and easier to run (84acb744)
  • app: add additional node version to travis.yml (e4f00b08)
  • uibootstrap: add basic modal service and template when using uibootstrap (7c14bed4)

v2.0.10 (2014-08-16)

Bug Fixes

  • server: undefined domain env variable causing issues (cb683dde)

v2.0.9 (2014-08-15)

Bug Fixes

  • app:
    • add .idea folder to gitignore (2e1f1182)
    • Missing user response code (c1766604)
    • use '' instead null as URL to open ioSocket (0f0d0fdc)
    • save the version of the generator that was used (2b76b17b)
  • gruntfile: incorrect path to index.html for cdnify (0ad646cb)
  • openshift: fix issues with openshift deployment (ace07238)

Features

  • gen: add automatic demo releases with grunt task (44852233)
  • gruntfile: add grunt buildcontrol tasks to app, for easier deployment (036478df)
  • heroku: provide prompt to set the deployment region (13cd5e7d)
  • server: add sample env config file that can be tracked by git (c9f80bcd)

v2.0.8 (2014-07-31)

Bug Fixes

  • coffee: update socket service to match javascript version (c27cefe2)
  • gen: Fixed missing oauth property in .yo-rc.json after 2.0.5 update (11d324b9)
  • travis: install sass gem if sass is enabled (ceeac27b)
  • twitter: revert mongoose connection change (8675a002)

Features

  • user-management: use the User $resource to populate users for the admin page (708f0729)

v2.0.7 (2014-07-27)

Bug Fixes

  • gruntfile: grunt tasks should run if no local config exists (422d6bca)
  • server: fix setting TTL index on collection : sessions error (0581ed09)

v2.0.6 (2014-07-27)

Bug Fixes

  • app:
    • things made a little bit more responsive (58aa7a48)
  • dependencies: change ngmin to ng-annotate (dd023fa5)
  • bootstrap: removed styles breaking responsiveness for high-res screens (053fedb8)
  • socketio: fallback for servers where socket.handshake.address is not provided (f6a19348)
  • stylus: remove bootstrap css import in stylus when bootstrap is not selected (f7c3d0ad, closes #368)

Features

  • oauth: remove code according to user prompts (316bd9dd)

v2.0.5 (2014-07-17)

Bug Fixes

  • account: add authentication requirement for settings view (9105c0fd, closes #327)
  • app:
    • use correct path for font awesome and glyphicons (1917ba31)
    • wait for currentUser to resolve before checking if logged in on route changes (6d6090d9)
    • bootstrap glyphicons not correctly linked on grunt build (53d193d0)
  • dependencies: include certain dependencies only when answering yes to their respective prompts (040c57de)
  • server:
    • fix seeding of db in test mode causing tests to randomly fail (05f7f433)
    • make user tests run more consistently (addb5061)
    • warnings that express was using deprecated features (8dc2f1e4)
    • missing res param for handleError (eb7d50c8)

Features

  • app:
    • added oath buttons to signup page (a408f58e)
    • upgrade socket.io to use v1.0.6
  • gen:
    • add option for Stylus as a preprocessor (1b90c448)
    • make bootstrap and bootstrap ui optional (f50d0942)

v2.0.4 (2014-07-08)

Bug Fixes

  • app: fix dependency injection minsafe problem in auth service coffeescript. (03742a80)
  • gen: heroku and openshift generators requiring .yo-rc file to work (88ebfc8c)

v2.0.3 (2014-07-04)

Bug Fixes

  • server: only enable sessions if twitter oauth was selected (bcd00dc0)

v2.0.2 (2014-07-02)

Bug Fixes

  • gen:endpoint
    • fix endpoint spec not properly adjusting to users route url
    • fix some valid route urls causing failing tests

v2.0.0 (2014-07-02)

Features

  • app:
    • Follow googles AngularJS project recommendations to make a very modular app structure.
    • New look for generated app
    • Add basic crud interface to app
    • Support for UI Router
    • Support for LESS
    • Built in support for protractor e2e tests
    • Add angular-bootstrap and lodash to default app
    • More consistent and understandable naming conventions for files
  • server:
    • Modular project structure for express server
    • Support for social auths with facebook/twitter/google
    • Role based authentication
    • Replace session based authentication with JWT authentication
    • Optional integration with socket.io
    • Added config file, ignored by git, for setting local environment variables, api keys, secrets.. etc.
  • gruntfile:
    • Optimizations to the gruntfile
    • Automate injection of new scripts into index file with grunt
    • Use ng-templates to concatenate all the html/jade views into the javascript payload
  • gen:
    • Abstract client-side generators into generator-ng-component, use new composition feature of yeoman to keep them available in the generator.
    • Add useful tests to the generator, start using travis CI
    • use .yo-rc file to keep track of generated configurations
    • Add endpoint generator to angular-fullstack, generates model / route / controller / test / socket updates

Breaking Changes

  • New project structure
  • Deprecated value and constant sub generators
  • Sub-generators generate components in a single directory and don't inject themselves into the index file (this is done by a grunt task now)

v1.4.3 (2014-05-25)

Bug Fixes

  • config: fix issue where config.ip is undefined in non-production environments (087f5bca)
  • package: update connect-mongo to correct version
  • app: add require attribute to login.html inputs so it validates on client side
  • gen: use lowercase filenames for scripts

v1.4.2 (2014-04-16)

Bug Fixes

  • gen: typo in heroku generator was preventing it from working on unix based systems (9d3b5738)

v1.4.1 (2014-04-15)

Bug Fixes

  • server:
    • grunt test was incorrectly using dev config, fixes #179 (62d8492f)
    • emails are no longer case sensitive (dafd8db1)

v1.4.0 (2014-04-13)

Features

  • server: updated Express to v4.x
  • app: matching angular dependencies to the latest verison, now that bower excludes pre-releases (94c0c636)
  • gen:
    • Added angular-fullstack:openshift generator, for deploying your app to OpenShift
    • Added angular-fullstack:heroku generator, which improves upon the former :deploy generator for deploying to Heroku

Bug Fixes

  • server: fixed possible DB flushing when mochaTest is called by watch, first call 'env:test' task before 'mochaTest' (2f0320fe)

Breaking Changes

  • The angular-fullstack:deploy generator is deprecated. Instead use angular-fullstack:heroku or angular-fullstack:openshift.

v1.3.3 (2014-03-29)

Features

  • server: enable response compression (1547ac6f)

Bug Fixes

  • config: change default port in config to 9000 (480515f6)
  • gruntfile:
    • update gruntfile to use port from config (c8aa2d5f)
    • workaround imagemin bug by disabling caching (3e435fa7)
  • package: update required generator-karma dependency to the correct version (0c0e8a52)

v1.3.2 (2014-03-01)

Bug Fixes

  • package.json: updated dependencies that were causing issues with npm install (1874cdf1)

v1.3.1 (2014-03-01)

Bug Fixes

  • gruntfile: configured jshint for client tests (4ee92b9a)

v1.3.0 (2014-02-27)

Bug Fixes

  • grunt:
  • server:
    • config all and env specific are now correctly deep merged (31039872)
    • fix configuration so that (express) errorHandler works (0116cb35)

Features

  • app:
    • added grunt serve:debug task that launches the server with a node-inspector tab (de3e7a8b)
    • update to bootstrap sass official (3799c13c)
  • server:
    • added tests for user model (4c894b65)
    • added mocha test configuration (458a2f6a)

v1.2.7 (2014-02-15)

Features

  • server: undefined api routes now return a 404 (ec829fe2)

v1.2.6 (2014-02-14)

Bug Fixes

  • app:
    • redirect to login only on 401s (64b7bace)
    • fixed incorrect css path for usemin in gruntfile (46fca240)
  • grunt: include partial sub-directories in htmlmin (77564ba3)
  • server:
    • fixed connect-mongo error (c12db5b3)
    • livereload now waits for server to finish restarting (71d63f0a)
    • exposed configured passport from passport module (772133de)
    • only require models if they are coffescript or js files (ce2ee236)

Features

  • deps: upgrade angular to 1.2.11, and jquery to 1.11.0 (cd5c3030)
  • app: switched sass-bootstrap to offical bootstrap-sass (024fee88)

v1.2.5 (2014-01-27)

Bug Fixes

  • app:
    • fixed coffee service so it's min-safe (c18c9da4)
    • fixed bootstrap css being imported rather than compass bootstrap (f2739987)
  • server:
    • replaced deprecated bodyparser (788fda04)
    • updated node version dependency (b19a0997)
  • gen: updated generator dependencies (115008d3)

v1.2.4 (2014-01-16)

Bug Fixes

  • grunt: fixed incorrect templating expression (2a59e070)

v1.2.3 (2014-01-16)

Bug Fixes

  • app: fixed jshint warning in user model (f668fdc7)

v1.2.2 (2014-01-16)

Bug Fixes

  • app:
    • replaced bcrypt with crypto for windows users (af20c3ab)
    • added karma dependencies directly to package template (13ea60e7)

v1.2.1 (2014-01-12)

v1.2.0 (2014-01-11)

Features

  • app:
    • restructured project for easier configuration (0a2bf2ab)
    • grunt build now moves all files into dist folder (e6eff5d5)
  • server: added jshint error checking before livereload occurs (7e001d31)
  • gen: added passport question for scaffolding out user account creation (87841064)

Bug Fixes

  • app: removed async dependency (d5636d71)
  • gitignore: fix app/views being ignored by git (7fa82ff9)
  • server:
    • config wasn't added to default project (79c5e027)
    • removed typo and cleaned up extra whitespace (1a132c28)
    • fixed style issues that were tripping up jshint

Breaking Changes

  • grunt heroku is deprecated. Use grunt build instead.

v1.1.1 (2013-12-25)

Bug Fixes

  • views:
    • Replaced deprecated jade tags.

Features

  • app:
    • Updgrade to AngularJS 1.2.6

v1.1.0 (2013-12-22)

Bug Fixes

  • app:
    • only copy CSS if Compass is not installed (7e586745)
    • services use classified names (56a71a83, closes #484)
    • reload JS files in watch (d20f5bd2)
  • build: deselecting ngRoute does remove route stuff (a358c1ae, closes #486)
  • gen:
    • updated all conflicts, and fixed some bugs, from merging with upstream (d07c829d)
    • fix bower install prompt during project gen (706f1336, closes #505)
  • package: fix imagemin for windows users (b3cec228)
  • views:
    • fix ng includes (598c69a5)
    • add compiled views to gitignore (087ede5f)
    • fix incorrect build path for vendor css (0ed2a200)

Features

  • app:
    • add jasmine browser global to test jshintrc (11b6ed42)
    • use lowercase file names (23e5d772, closes #463)
    • use htmlmin for smaller HTML files (2b85a52a, closes #469)
    • use grunt-bower-install for dep management (ba7b5051, closes #497)
    • Enable Node debug mode (83ae4a9e)
  • gen:
    • Added navbar to starting template (b5e94749)
    • additional work for compass support (11cb9943)
    • add Compass support to the initialization process (7fac1194)
    • add welcome message and dep notice for minsafe (f0bb8da2, closes #452)
  • server:
    • Added middleware for development mode that disables caching of script files (c082c81c)
    • Moved express configuration code out of server.js and into config folder to make it a more high level bootstrap.

Breaking Changes

  • Deselecting ngRoute adds controller and ng-include to index.html (a358c1ae)
  • --minsafe flag is now deprecated.
  • grunt server is now deprecated. Use grunt serve instead

v1.0.1 (2013-11-27)

Bug Fixes

  • coffee: updated coffescript templates to point to partials (f98e84ef)

v1.0.0 (2013-11-26)

Bug Fixes

  • build:
    • use test-specifc jshintrc (c00c091b)
    • add webapp upstream features and better coffee (c23acebb)
    • use grunt-newer for styles and jshint (b1eeb68a)
    • standardize comments and comment out uglify:dist (d5d3e458, closes #455)
  • deps: upgrade dependencies (3a57216f)
  • gen:
    • Fixed jshint errors that were breaking grunt task (c6ae81c8)

Features

  • app:
    • Separate client and server watchers (0ff8ffb1)
    • imagemin handles gifs (9341eb9b)
  • gen:
    • added support for jade templates (24a13bfe)
    • Support for server rendering and Angular's HTML5 mode (5ccdeb7a, closes #18, #17)
    • add image file as example (b161c298)
  • build:
    • compile only changed coffeescript files in watch task (4196e379, closes #425)
    • deprecate server in favor of serve (ef056319)

Breaking Changes

  • angular-fullstack:route
  • angular-fullstack:view

Will now generate views and routes in the views/partials folder.

For existing projects:

For generating routes and views, install generator-angular and use it's sub-generators.

They are exactly the same as the generators that you have been using. Example usage: yo angular:route helloworld.

For New projects:

Continue to use angular-fullstack route and view sub-generators.

The reason for this change in folder structure was to support server page rendering.

Closes #18, #17 (5ccdeb7a)

  • grunt server is being deprecated (ef056319)

v0.2.0 (2013-11-13)

Bug Fixes

  • bootstrap: some plugins have ordering dependencies (3da4a130)
  • build: only include sass if sass is selected (597b8b5c, closes #449)
  • css: remove merge conflicts (d558af35)
  • gen:
    • script paths use forward slashes (40aa61dc, closes #410)
    • remove extra "App" from service spec files (4053f11f)
    • options should have descriptions (da001832)
  • styles: update path to icon images (8daad4f2)
  • template: remove redundant closing tag (d1e560e0, closes #441)

Features

  • app:
    • run unit tests when test scripts are changed (94af0b51)
    • update to angular 1.2.0 (77082c6b)
    • reload grunt server when gruntfile is updated (50c6abb9)
    • upgrade to Bootstrap 3.0.1 (59f4b1ba)
  • gen:
    • allow app names to have custom suffix (09f0f7b3)

v0.1.0 (2013-11-12)

Features

  • gen: include MongoDB as an option When selected, sets up database with Mongoose. Repl (280cc84d, closes #2)