A modular approach to building web apps with Brunch https://brunch.io/skeletons
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Josh Habdas d4807b1167 pass or fail 4 years ago
app The dude abides 4 years ago
generators Less space 4 years ago
jakelib clear bower cache when running bower:clean resolves #42 4 years ago
server space, the final frontier 4 years ago
test pass or fail 4 years ago
vendor Merge remote-tracking branch 'upstream/master' 5 years ago
.editorconfig Merge branch 'develop' of https://github.com/jupl/brunch-toolchain into feature/btc-0.4.0 5 years ago
.gitignore Add IntelliJ related files to gitignore 5 years ago
.travis.yml Don't specify engines that don't work 4 years ago
CHANGELOG.md Use PhantomJS and not detect browsers 4 years ago
Jakefile Move default Jake task to Jakefile 5 years ago
LICENSE Moar goodies for 0.8.7. See CHANGELOG for the deets. 4 years ago
README.md And a whale said Let there be Docker 4 years ago
bower.json clear bower cache when running bower:clean resolves #42 4 years ago
brunch-config.coffee Removing some experimental work 4 years ago
package.json Removing some experimental work 4 years ago

README.md

Brunch with Panache

Dependency Status devDependency Status Build Status

Introduction

BWP is a skeleton for building web applications, specifically single-page applications. It is a modification of btc-chaplin. It leverages node, Brunch, Scaffolt, Bower, Hapi, PhantomJS, Karma, and Jake to provide cross-platform tasks in a simple package. EditorConfig is also provided to help with consistency.

It contains the following differences from its upstream:

  • DRY-style companion app Brunch with Coalescence
  • Docker image to for blazingly fast environment set-up
  • Sass instead of Less
  • Automatic vendor prefixing
  • Handlebars instead of Embedded CoffeeScript templates
  • Support for Handlebars partials
  • Swag helpers available for more powerful Handlebars templates
  • Asset fingerprinting for performance and control
  • Opinionated generators for easier file searching
  • Working Karma test runner
  • NPM shrinkwrap and clean tasks
  • Uses Hapi instead of Express as Node app server
  • Runtime controllable with environment config

For a mobile/Cordova friendly variant, check out this skeleton.

File Structure

├── app                       # App is built here. Look at Brunch for more info.
│   ├── assets                # Static files that are just copied
│   ├── controllers           # Chaplin controllers
│   ├── lib                   # Chaplin utilities and helpers
│   ├── models                # Chaplin models and collections
│   ├── styles                # Application style rule declarations
│   │   ├── _base.scss        # Sass variables and mixins for the application
│   │   └── application.scss  # Application/page styling definition
│   ├── views                 # Chaplin views and collection views
│   ├── application.coffee    # Chaplin application definition
│   ├── initialize.coffee     # Application initialization and script loaders
│   ├── config.coffeeenv      # Environment-specific variables
│   └── routes.coffee         # Route definitions for Chaplin
├── bower_components          # Packages installed by Bower
├── generators                # Generators used by Scaffolt
├── jakelib                   # Unified set of tasks for development
├── node_modules              # Packages installed by NPM
├── public                    # Generated final product
├── server                    # Server configuration
├── test                      # Test-related files
│   ├── assets                # Static assets to run code tests manually
│   ├── code                  # Code-based tests for Karma/manual
│   ├── site                  # Site-based tests for Mocha and WebDriverJS
│   ├── karma.conf.coffee     # Karma configuration for code tests
│   ├── mocha.opts            # Default options for site tests
│   └── setup.js              # Configuration for site tests
├── vendor                    # 3rd party JS/CSS libraries
├── .editorconfig             # EditorConfig definition file for coding styles
├── bower.json                # Listing for Bower dependencies to download
├── brunch-config.js          # Brunch app build configuration
└── package.json              # Project dependencies and configuration

Setup

  1. Install Node.js. Consider using NVM to do this.
  2. Open a terminal window, clone the repo and navigate to the project directory.
  3. Execute the command npm install to install all package dependencies.
  4. Run jake server:dev to download Bower dependencies and start the server.

If the jake command is not available in path, execute npm install -g jake to install it globally.

Notes

npm start / npm test

One-line commands are provided for convenience as well for those that want to start running things as quickly as possible by installing depedencies automatically. Use npm start to download non-development packages and run the build:prod task. Use npm test to download all packages and run both the test:install and test:all tasks.

Server

A basic push state server serving static assets is included by default. You can expand/enhance the server as needed for services and to create a more ambitious application.

Contribution

When making a pull request, make sure to edit the base fork to which you want to contribute (by default it will try and merge with the parent repository from which this one is forked, which we don’t want to do).

Task List

While Brunch/Scaffolt/etc. can be used, Jake commands are provided for a simple and consistent interface. These tasks can be executed using jake. (jake [task]) These are the following available tasks provided out of the box:

Bower

bower:install

Download and preinstall any Bower dependencies in advance. You can run this if you want to download Bower dependencies in advance.

bower:clean

Remove downloaded Bower dependencies. This is useful if you want to reinstall dependencies. (e.g. updated package)

NPM

npm:shrinkwrap

Locks down Node package versions.

npm:clean

Remove downloaded Node dependencies. This is useful if you want to reinstall dependencies. (e.g. updated package)

Extras

These commands add additional features/items to the project that are not included by default.

add:jquery / rem:jquery

Add/remove jQuery to/from the project.

add:lodash / rem:lodash

Add/remove Lo-Dash to/from the project.

add:rivets / rem:rivets

Add/remove Rivets.js to/from the project for binding models and views. No additional configuration is needed if added. To reference a model from a view with rivets use the model object. To access model properties from Rivets by default use :. (ex: model:name equates to model.get('name'))

add:swag / rem:swag

Add/remove Swag helpers for Handlebars templates.

add:exoskeleton / rem:exoskeleton

Add/remove Exoskeleton to/from the project for a more lightweight Backbone. Note that this removes/restores classic Backbone, jQuery, and Lo-Dash. You can use other tasks to add/remove jQuery and Lo-Dash again.

add:davy / rem:davy

Add/remove Davy to/from the project for simple and lightweight Promise support. Add this if you are using Exoskeleton and want support for promises.

Scaffolding

Scaffolding commands are available in the form of gen and del. (syntax ex: jake gen codetest=user) Multiple scaffolds can be specified in a single command, as well as separating names with commas. (ex: jake gen codetest=test1,test2 sitetest=test3) Unit test files are automatically generated for Chaplin items. For Chaplin views, a template and stylesheet is also provided in addition to the code file.

gen / del

List available scaffolds.

gen model=[name] / del model=[name]

Generate/destroy a Chaplin model.

gen collection=[name] / del collection=[name]

Generate/destroy a Chaplin collection. Generating a Chaplin collection will also generate its corresponding model. Specify the name in singular form, as collection will automatically be pluralized.

gen view=[name] / del view=[name]

Generate/destroy a Chaplin view.

gen collection-view=[name] / del collection-view=[name]

Generate/destroy a Chaplin collection view. Generating a Chaplin collection view will also generate the individual item view.

gen controller=[name] / del controller=[name]

Generate/destroy a Chaplin controller.

gen code-test=[name] / del code-test=[name]

Generate/destroy a test file with the given test name for testing code. (ex: unit testing)

gen site-test=[name] / del site-test=[name]

Generate/destroy a test file with the given test name for testing the site. (ex: functional testing)

Testing

Testing commands are available via Jake as defined below. Run npm test to automatically install and run tests.

test:install

Install dependencies for tests. Omitted from package for speedier installs.

test:all [codereporter=progress] [sitereporter=spec]

Run all tests listed below once. For more information on reporters see below.

test:code [reporter=progress] [watch=false]

Run code-based tests (ex. unit tests) using Karma. Karma is preconfigured out of the box to run with PhantomJS and detected browsers. A Karma reporter can be specified with the reporter option. If you run this task with watch=true Karma will auto-run on file changes. Otherwise by default Karma runs once. In addition, if you run a build (see below) with the dev environment the tests are included with a reporter under test to run in browsers. (ex. visit http://locahost:[port]/test)

test:site [reporter=spec] [watch=false]

Run site-based tests (ex. system tests) using Mocha and WebDriverJS. A Brunch server is started up temporarily to interact with the site. A Mocha reporter can be specified with the reporter option. If you run this task with watch=true Mocha will auto-run on file changes with nodemon. Otherwise by default Mocha runs once. The global method getDriver is provided to get a setup and built driver. WebDriverJS’ use of Promises can be combined with Mocha as Promised to handle asynchronous behavior easily. ex:

describe 'Sample', ->

  before ->
    @driver = getDriver()

  it 'Has a proper title', ->
    @driver.get('http://localhost:3333').then =>
      @driver.getTitle()
    .then (title) ->
      expect(title).to.equal('Chapless Brunch')

  after ->
    @driver.quit()

Building

These commands are used to assemble the application, generating the necessary JS/CSS and adding assets. Use dev mode to keep readable JS/CSS, plus include source maps as well as tests under the test folder. Use prod mode to minify/uglify JS/CSS as well as omit source maps and tests. If any Bower dependencies have not been downloaded yet, Bower will first download them.

build:[mode]

Assemble the application once.

watch:[mode]

Assemble the application and continue to watch for changes. Rebuild every time a change is detected.

server:[mode]

Assemble the application and continue to watch for changes. Rebuild every time a change is detected. Also, the application is served locally to open with a browser. This build uses the web environment.

Coffeeenv

A config.coffeeenv file is provided in the app directory. It allows you to set environment variables for the purposes of local development or deployment.

(env) ->

  # Environment options
  # https://github.com/rcs/jsenv-brunch/
  environmentOpts =
    API_HOST: 'http://api.apihost.com'

  # Set allowed environment options
  for key, value of env
    switch key
      when 'API_HOST' then environmentOpts.API_HOST = value

  environmentOpts

This allows you to run a command with the environment variable:

API_HOST="http://api.untappd.com" jake watch:dev

And access passed variables as a CommonJS module at runtime:

config = require('config')
console.log config.API_URL # => http://api.untappd.com

Libraries

Core

Languages

Framework

Testing Framework

Utilities