README

generator-ng-plugin

Yeoman generator to bootstrap AngularJS plugin creation, with integrated demo app, continuous integration system, dependencies and code coverage status.

Demo

Here are live examples of some AngularJS plugins developed with the generator:

Installation & Usage

Requirements

You should already have the following dependencies installed: Node.js(npm), Yeoman, Bower and Grunt. if not:

Install Node.js. This will also install npm, which is the node package manager we are using in the next commands.
Install Yeoman: npm install -g yo
Install Bower: npm install -g bower
Install Grunt: npm install -g grunt-cli

Otherwise, install directly the generator via:

$ npm install -g generator-ng-plugin

Usage

Once installed, simply run the following command:

$ yo ng-plugin

And answer the questions you are prompted to.

Overall Directory Structure

At a high level, the generated structure looks exactly like this:

my-plugin/
  |- .git/
  |- bower_components/
  |- node_modules/
  |- src/
  |  |	|- my-plugin.js
  |  |	|- my-plugin.spec.js
  |  |	|- my-plugin.less
  |  |	|- my-plugin.tpl.html
  |- demo/
  |  |- app/
  |  |	|- app.js
  |  |	|- helpers/
  |  |	|  |- plunker.js/
  |  |	|  |- prettifyDirective.js/
  |  |- less/
  |  |	|- demo.less/
  |  |- index.html
  |- .bowerrc
  |- .editorconfig
  |- .gitattributes
  |- .gitignore
  |- .jshintrc
  |- .travis.yml
  |- bower.json
  |- build.config.js
  |- CHANGELOG.md
  |- changelog.tpl
  |- Gruntfile.js
  |- karma-unit.tpl.js
  |- LICENSE
  |- module.prefix
  |- module.suffix
  |- package.json
  |- README.md

Development

It's now up to you to write your kick-ass AngularJS plugin by modifying generated files in src/ and completing the tests and the demo's index.html.

To ensure your setup works, and during developement, launch grunt:

$ grunt watch

The built files are placed in the build/ directory by default. Open the build/index.html file in your browser and check it out! Because everything is compiled, no XHR requests are needed to retrieve templates, so until this needs to communicate with your backend there is no need to run it from a web server.

Thanks to the integrated LiveReload plugin, you no longer have to refresh your page after making changes!

Versioning

To take full advantage of the generator, use AngularJS's commit message convention. This way, the grunt's changelog task can be used to generate/update the project's CHANGELOG.md file from Git metadata. Only relevant commit messages are considered (take a look at changelog.tpl file to see how it get generated).

Releasing

Once your killer plugin is written, fully tested, it is time to release it:

$ grunt bump-only:[major|minor|patch]*
$ grunt changelog
$ grunt bump-commit

*: you must choose between 'major', 'minor', or 'patch' (see Semantic Versioning for more information)

This will:

update the version of your plugin in bower.json and package.json files
update the CHANGELOG.md file
commit on master branch
create new tag
push to origin

If you want to make your plugin available to everyone, register it on Bower (one-time-only operation) via:

$ bower register REPO_NAME git://github.com/USER_NAME/REPO_NAME.git

Deploying demo app

To deploy your demo application on Github, simply run the following commands:

$ grunt
$ grunt buildcontrol:ghpages

This will push the minified demo application in dist/demo to gh-pages branch.

The demo application is available at : http://USERNAME.github.io/REPO_NAME/

License

Thanks To

The generated files and build system are based on ng-boilerplate by Josh D. Miller.
The generated demo app design is inspired from ui-bootstrap by Angular UI team.
Thanks to them for the great work!

Usage no npm install needed!