generator-bat

BAT, the Backbone Application Template

A Yeoman generator collection created by marviq.

Ever got tired of having to scaffold your new webapp projects over and over again? Moan no more; Yeoman and BAT will do it for you!

Getting Started

What is Yeoman?

Trick question. It's not a thing. It's this guy:

Basically, he wears a top hat, lives in your computer, and waits for you to tell him what kind of application you wish to create.

Not every new computer comes with a Yeoman pre-installed. He lives in the npm package repository. You only have to ask for him once, then he packs up and moves into your hard drive. Make sure you clean up, he likes new and shiny things.

[sudo ]npm install -g yo

Yeoman Generators

Yeoman travels light. He didn't pack any generators when he moved in. You can think of a generator like a plug-in. You get to choose what type of application you wish to create, such as a BAT webapp.

To install BAT from npm, run:

[sudo ]npm install -g generator-bat

Finally, initiate the main app generator:

yo bat

Some of its subs:

yo bat:view
yo bat:model
yo bat:collection

Or, if you want a head start, even:

yo bat:demo

The Finer Print

Why BAT?

With BAT you can immediately start developing your application instead of worrying about getting your project set up first. The main app generator will provide you with the following out of the box:

• A default project filesystem structure:
  • src/ - a directory for your sources to live in;
  • test/ - a directory to contain your unit tests;
  • dist/ - where all you builds will be assembled;
  • vendor/ - a place for keeping third-party libraries that npm doesn't know how to deliver;
• Project files:
  • Gruntfile.coffee
  • package.json
  • AUTHORS
  • LICENSE (BSD-3-Clause)
  • README.md
  • .editorconfig
  • .gitattributes
  • .gitmessage
  • .jshintrc
  • .coffeelint.json
• Grunt, or rather, a complete and annotated Gruntfile.coffee, set up for Browserify, Compass, code linting, -testing, -minification and -documentation generation;
• Browserify, bundling modular code for the browser, supporting CoffeeScript, Handlebars and browserify shims;
• Backbone.js MVx foundation, including a main router implementation;
• Backbone-Debugger browser plugin engagement (when available), automatically included with debugging builds;
• CoffeeScript coding;
• Compass SASS styling;
• Handlebars HTML templating;
• jQuery browser normalization;
• Basic Internationalisation support;
• YUIDoc code documentation generation;

To scaffold out a new project like that, simply run:

yo bat

Yeoman will ask you some questions, set everything up and install dependencies for you. Wait a bit for him to complete this and you're all set to go.

Additionally, Yeoman can:

• Provide you with a demo webapp implementation showcasing the BAT. It is also possible to get this at a later instant through yo bat:demo;

Sub-generators

BAT also comes with sub-generators that scaffold out new Backbone models, collections and views.

For each of these Yeoman will deliver a neat set of files, set up, YUIDoc code documentation pre-filled and integrated into existing code for as far as he dares to.

View

yo bat:view

Placed into the src/views directory, Yeoman will provide you with *some-view-name*.coffee and *some-view-name*.hbs files, respectively containing the class definition for the *SomeViewName*View and its handlebars template.

Additionally, Yeoman can:

• Create a _*some-view-name*.sass file into the src/sass/views directory and insert an @import for it into src/sass/_views.sass;

Note that for so-called routed views, you would probably want to incorporate this view into your webapp's main router.coffee. Yeoman would have liked to do this for you too but is too afraid to break your code, so he doesn't.

Model

yo bat:model

Yeoman will provide you with a *some-model-name*.coffee file containing the class definition for *SomeModelName*Model and place it into the src/models directory.

Optionally, Yeoman can:

• Cause a singleton instance of the model to be exported instead of the class itself;

Collection

yo bat:collection

Yeoman will provide you with a *some-collection-name*.coffee file containing the class definition for *SomeCollectionName*Collection and place it into the src/collections directory.

Furthermore, Yeoman can:

• Also create the model for this collection;
• Cause a singleton instance of the collection to be exported instead of the class itself;

Demo

BAT also comes packed with a demo webapp implementation showcasing its features. To get this, either answer yes to the relevant prompt from an initial yo bat run, or when you answered no there earlier, invoke:

yo bat:demo

Note: that the latter will result in a few clashes with some of the files produced from the earlier yo bat run. These are however, caveat codor, harmless.

Grunt tasks

After you're all set up, you'll want to build your project; this is where Grunt comes in:

grunt dev

This will first do a development build (all builds will be assembled into the dist directory btw), and then enter a watch-for-changes -> re-build loop.

Grunt can do more than just that; here's a recap of common grunt idioms:

command	description
grunt [default]	shortcut for grunt dist unless the GRUNT_TASKS environment variable specifies a space separated list of alternative tasks to run instead;
grunt dist	does a for-production, non-debugging, all-parts, tested, minified build plus artifacts;
grunt debug	does a for-testing, debugging, all-parts except documentation, tested, as-is build;
grunt dev	does a for-local, debugging, all-parts except documentation, as-is build; (Note that this variant doesn't exit. Instead it'll keep a close watch on filesystem changes, selectively re-triggering part builds as needed)
grunt doc	will build just the code documentation;
grunt lint	will just lint your code;
grunt test	will run your test suite;
grunt test:dev	will run your test suite and will keep monitoring it for changes, triggering re-runs;
grunt --help	will show you all of the above and the kitchen sink;

Unit tests

BAT comes with support for unit testing using Karma, Jasmine and PhantomJS.

Unit testing is an integrated build step in both dist and debug build runs, but can also be run independently as:

grunt test

And as watched, continuous test runs as:

grunt test:dev

The latter invocation, while it is kept running, also offers the opportunity to launch a test suite run in any browser, simply by directing it to this url:

http://localhost:9876/debug.html

Do not forget to open your dev tools and browser console there!

ChangeLog

Refer to the releases on GitHub for a detailed log of changes.

Contributing

Prerequisites

• npm and node
• git flow
• jq

Setup

Clone this repository somewhere, switch to it, then:

$ git config commit.template ./.gitmessage
$ git checkout master
$ git checkout develop
$ git flow init -d
$ ( cd ./.git/hooks && ln -s ../../.git-hooks/git-hook-on-npm-lockfile-change.sh post-checkout )
$ ( cd ./.git/hooks && ln -s ../../.git-hooks/git-hook-on-npm-lockfile-change.sh post-merge )
$ npm run refresh

This will:

• Set up a helpful reminder of how to make a good commit message. If you adhere to this, then a detailed, meaningful CHANGELOG can be constructed automatically;
• Ensure you have local master and develop branches tracking their respective remote counterparts;
• Set up the git flow branching model with default branch names;
• Set up two git hooks to ensure that your node_modules will be synced with the package-lock.json dependency tree definition whenever a git merge or -checkout causes it to change;
• Install all required dependencies, pruned and deduplicated;

Commit

Branching Model

This project uses git flow. Here's a quick cheat sheet.

Commit Message Format Discipline

This project uses conventional-changelog/standard-version for automatic versioning and CHANGELOG management.

To make this work, please ensure that your commit messages adhere to the Commit Message Format. Setting your git config to have the commit.template as referenced below will help you with a detailed reminder of how to do this on every git commit.

$ git config commit.template ./.gitmessage

Release

• Determine what your next semver <version> should be:

  $ version="<version>"
  

• Create and checkout a release/v<version> branch off of develop:

  $ git flow release start "v${version}"
  

• Bump the package's .version, update the CHANGELOG, commit these, and tag the commit as v<version>:

  $ npm run release
  

• If all is well this new version should be identical to your intended <version>:

  $ jq ".version == \"${version}\"" package.json
  

  If this is not the case, then either your assumptions about what changed are wrong, or (at least) one of your commits did not adhere to the Commit Message Format Discipline; Abort the release, and sort it out first.

• Merge release/v<version> back into both develop and master, checkout develop and delete release/v<version>:

  $ git flow release finish -n "v${version}"
  

  Note that contrary to vanilla git flow, the merge commit into master will not have been tagged (that's what the -n was for). This is done because npm run release has already tagged its own commit.

  I believe that in practice, this won't make a difference for the use of git flow; and ensuring it's done the other way round instead would render the use of conventional-changelog impossible.

Publish

To NPM

git checkout v<version>
npm publish
git checkout develop

On GitHub

git push --follow-tags --all

• Go to https://github.com/marviq/generator-bat/releases;
• Click the Draft a new release button;
• Select the appropriate v<version> tag from the dropdown menu;
• You could enter a title and some release notes here; at the very least include a link to the corresponding section in the CHANGELOG as:

  [Change log](CHANGELOG.md# ... )
  

• Click the Publish release button;

ChangeLog

See CHANGELOG for versions >0.1.27; For older versions, refer to the releases on GitHub for a detailed log of changes.

License

BSD-3-Clause

Changelog

1.0.2 (2017-10-20)

Bug Fixes

• generators/{app,demo}/templates: fix non-html5 self-closing tags (d88e8b4)
• generators/app/templates: ensure git hooks don't error-exit when there's nothing to do (3fd33d7)

<a name="1.0.1"></a>