ember-rocks

Ember Rocks ( a.k.a em-cli )

An Em(ber) command line utility to help developer(s) build an ambitious web application. It is highly inspired by some awesome open source projects, ember-cli, ember-tools, Web Starter Kit, Gulp.

Getting Started

    npm install -g ember-rocks

After the installation, you should have a global command em available. Try em --help, you should see a list of helper information. Try em generate --help to see a specific command helper information.

Features

• well align with Ember-Cli project
• gulp ( build tool of choice ) build insanely fast via node stream api
• lighting fast development rebuild system
• live reload on all resources
• super powerful generator system
• Sass language support with CSS sourcemap, trace back to original Sass defination
• ES6 ( Next Version of javascript ) with JS sourcemap, trace back to origional ES6 defination
• hackable express server as back end
• Mocha testing framework and BDD should.js style supported by default
• simple command to build a production ready application and ready to be deployed
• tablet and touch device support out of box. Responsive Web Design supported.
• hybird web app on native phone and tablet via Cordova package. For iOS, Andriod, Blackberry, and more

A sample ember app in the Ember Rocks

Ember Rocks comes with a sample application, and user could even have their own set of templates. See Ember Rocks Template Basic for details.

An express (Node.js) server will handle all requests. A fake user api route will read the RESTful json api on the disk, return the data over the wire when Ember app request the data via latest Ember Data library. In real world application, it should be replaced with MongoDB (recommended), CouchDB, etc. It is very easy to integrate with any NoSQL database.

The fully stylish application works on touch and tablet devices out of box. Try to resize your browser into a smaller screen resolution, you should see an animated effect from the left edge which is the most popular choice of mobile application navigation menu. You could tweak the styles and markup to fit your use cases.

Ember-cli is the official Ember app CLI tool (Ember#2.0 and forward). Why am I building another em(ber)-cli?

Ember-Cli is awesome and it is supported by Ember core team. If Ember-Cli is working for you, stick with it; otherwise, you can try Ember-Rocks and continue reading below,

TL;DR

There are a few reasons why I started with this project:

1. There was no official build tool for Ember project when I started in the middle of 2014. But now, Ember core team has announced that Ember-cli is the official build tool to move forward.

2. Ember-cli has chosen broccoli as its build tool. Do not get me wrong, Broccoli is an awesome build tool. I have even chatted with its creator, Jo Liss. She is an awesome engineer. But to me, after I switched from Grunt to Gulp at the end of 2013, I have learned in and out about Gulp and its EcoSystem. I do not want to follow the same path again from Gulp to Broccoli. Essentially, they are the same thing with different approach but solving the same set of problems.

3. Ember-cli has chosen Qunit as its testing tool. I was never a fan of TDD and Qunit. BDD and Mocha framework are always there to cheer me up. This is almost No-Brainer question for me since there is no addon for using Mocha testing framework. But now, Ember-Mocha has released to change the game. In fact, Ember-Mocha also powers Ember-Rocks testing use cases.

4. Ember-cli project is trying to be an universal toolset to fit most of use cases for majority of Ember developers. It is truly amazing to see Ember core team is there for wide range of audience. But I have a set of tools that works well. I will stick with it and also want to have full control over it if I could. Note: If Ember-cli works for you, great, you should stick with it since it supports by Ember core team.

5. Ember-cli has hided lots of complex system scripts and build logics into CLI core. For example, express server is built in so that it is hard to roll in any homebrew middlewares. Exposing Express server is becoming a necessary problem that need to be addressed.

Those are the major reasons why I started Ember-Rocks project. I have built several build systems throughout my professional career and some plugins/libraries for developers. In details below,

After built a large Backbone application (>15000 LOC), I developed a set of developer toolings which fit my customized workflow very well. Ember Rocks approach is my opinionated toolset on building a large scaled Node.js modern web application with Ember.js framework on the client side.

Ember Rocks can be globally installed on your local machine ( tested on Linux based operating system ) via npm install -g ember-rocks. After you have done that, magic happens :). You would have an em command available. Try em --help, em generate --help for a comprehensive guide.

Ember Rocks is chosen gulp as a build tool. In fact, it is powered by gulp under the hook. Ember-cli choose broccoli. The main difference between two awesome build tools is, broccoli use "directory in, directory out" pattern, and gulp use "file in, file out" pattern. gulp takes advantage of Node Stream to pipe files to destination folder. This is the one I perfer for now until broccoli is out of beta. Sorry, Jo Liss, you are awesome.

In addition, technology stack besides Ember.js, I have picked sass as css pre-compiler, autoprefixer as css post-compiler, express as node web application server, and mocha as javascript testing framework. 6to5 used to turn ES6+ code into readable vanilla ES5.

Just like lodash is a project which solve the same problem that underscore does, Ember Rocks is trying to solve similar problem that ember-cli does. I will try to sync the features from ember-cli to Ember Rocks.

What is on my road map? Ember Add-ons, custom components, frequent updates along with Ember releases and more. PRs, Issues, Suggestion are highly welcomed and appreciated.

Quick Start

    em new my-app          # generate a brand new ember app in *my-app* folder 
    cd my-app              # switch to application folder 
    em serve               # start a server, open the new app in browser, livereload all resources 

Usage

    em [command] [options]
 
    Commands:
 
        new [options]      # Creates a new ember application at [dirName] 
           
        g|generate         # Generate a new file with ES6 support in the ember app 
               
        s|serve            # Builds and serves your app, rebuilding on file changes 
 
        m|mobile           # Builds an Cordova application, and ready to deploy to phone or tablet 
           
        b|build            # Release your app and places it into the output path '~/build' 
 
        t|test            # Run client side integration and unit tests, rerun tests on file changes 
       
    Options:
 
        -h, --help     output usage information
        -V, --version  output the version number
 
    Command-Specific Help:
 
        em [command] --help

Guide

Since the project is highly inspired by Ember-Cli, ( both projects even share the same commands but completely different implementation under the hook, i.e. em(ber) new, em(ber) generate, em(ber) g, em(ber) serve, em(ber) build, em(ber) test, etc ), Ember Rocks uses the same modules -- ember resolver, and ember load initializers. Ember Modules system ( client/app/ ) and the resolver guide will apply to Ember Rocks modules and the resolver as well.

• Modules and the Resolver Documentation

( More Coming Soon )

Testing your app

Ember-Rocks testing story is 100% based on Ember Testing Guide so that Guide's methods, properties would apply to your testing story just like Ember default testing framework - QUnit. With a couple of variations, first, it uses Mocha testing framework with the assetion library should.js in BDD style; Second, you could optionally use ES6 syntax inside your tests and it would be transpiled into vanilla javascript in the development phase.

Integration tests are located in the folder client/tests/integration, and Unit tests are located in the folder client/test/unit. You do not have to manually create any new test files since you could simplly use em generate to generate any new tests with pre-defined boilerplate. If you do not know how, use em g --help for more details.

If you have to manually create a test file, name test file anything you want, suffix -test or _test with file extension .js.

You could use future ES6 syntax in tests, and they would be pre-compiled into vanilla javascript before serving in the browsers or phantomjs headless browsers.

Easiest way, the recommended way to run your test

By simply running em test or em t, it would compile your testing files, build the project, launch an express server to take any requests, watch any test file changes and rerun the test again, show the result of the tests.

  em test

Easy way, but requires two different processes and testem installed globally in your system. ( npm install testem -g )

By executing testem command, you get pretty UI in terminal to see exactly what is going on with your tests. testem should automatically launch chrome and phantomjs to run all of your tests.

Note: After em test run, the current processer continues running and watching any existing test files change, and it will rebuild the whole test suite and rerun all the tests.

GotCha: Any new/delete file won't rerun the tests or add to the current test run loop. You need to stop the current processer and rerun the command em test to pick up the new/delete testing files.

  # process 1 
  em test
  
  # process 2 
  cd path/to/root...
  cd build
  testem

Building a web app (desktop and browsers)

  em build
  cd build
  npm install
  npm start
  # Visit your production ready app at http://localhost:3001 

Building a native app (phone and tablet)

  em mobile
  cd build
  npm install
  cd build/cordova  # if in `build` folder, just `cd cordova`. Note: need to be in `cordova` folder to execute `cordova` command 
  cordova platform add ios # require **cordova** executable or `npm install -g cordova` 
  cordova run --emulator # open the native app in simulator ( require xCode installed) 
  npm start  # probably running in the separated terminal tab to serve your application 

Warning:

For running an ios emulator, you need to install ios-sim version 3.0.0 or higher via npm install ios-sim -g before you could run cordova run --emulator

Note:

Originally, I want to have some commands in ember-rocks to symlink some common useful Cordova commands. For example, em mobile --add ios map to cordova platform add ios, em mobile --run map to cordova run --emulator. In this approach, it would add up lots of additional options into the em mobile command. Although it could provide some useful shortcuts like auto cding cordova folder and abstract out some cordova learning curve by staying in em magics, it does add lots of API options to the ember-rocks project. I want to have a very simple API for users to comsume so that I decide to leave those features out of the core of the ember-rocks.

As a mobile application developer, you should be in the ~/build/cordova folder with cordova installed in your computer globally. You could use cordova command primarily to do whatever you want to your ember powered web app. If you have any question with this decision, feel free to create an issue or feature requests so that we could discuss it further.

Coding Styles

Following the coding standard from Ember.js best practice, use coding quality project - JSCS to assert code quality. To verify your own code, first, install jscs global via npm install jscs -g. Then run a test,

Running jscs in a easy way ( Bonus: running jshint and jscs in one shot ):

  # running jscs code quality assertion 
  gulp jscs
 
  # running both jshint and jscs in one command 
  gulp lint

Running jscs in a hard way:

  # make sure that `jscs` installed globally 
  jscs --version  
 
  # client side *.js code quality 
  jscs client/**/*.js
 
  # server side *.js code quality 
  jscs server/**/*.js
  
  # gulpfile.js code quality 
  jscs *.js

Roadmap

• Well-defined structure for each gulp task. User could pick sass, less, stylus etc when run em new command
• Native support Ember Addon system
• Koa replace express server

Deprecated module or Use in your own project

These projects comes with Ember Rocks v0.8.0 or prior, but moving forward, those modules are going to optional installation to speed up the initial scaffolding. We recommend to use them to improve your productivity.

• debug

small debugging utility. tiny node.js debugging utility modelled after node core's debugging technique.

• gulp-cache

A cache proxy task for Gulp. A temp file based caching proxy task for Gulp. It may add back in the future. Or if you like to contribute, submit a PR.

• gulp-changed

Only pass through changed files. It may add back in the future. Or if you like to contribute, submit a PR.

• gulp-size

Display the size of your project. Logs out the total size of files in the stream and optionally the individual file-sizes.

  gulp.src(src, {base: 'server/.'})
    .pipe(gulp.dest(dest))
    .pipe($.size({title: '[-log:] server folder'}));

• psi

PageSpeed Insights with reporting.

Usage example:

var pagespeed = require('psi');
 
// Run mobile and desktop performance tests via Google PageSpeed Insights
// For a production build process, register for an API key from Google Developer Console
// See http://goo.gl/RkN0vE for info key: 'YOUR_API_KEY'
// More Info:  https://www.npmjs.org/package/psi
gulp.task('pagespeed', pagespeed.bind(null, {
  // key: key
  nokey:    'true',
  // Update `url` below to the public URL for your site
  url:      'http://mattmadesign.com',
  // default strategy: desktop. Values: mobile, desktop
  strategy: 'mobile',
  locale:   'en_US'
}));

• gulp-uncss

Remove unused CSS selectors. It is bit of risky to use this module in my opinion. But it is a great one to reduce the size of your style sheet.

Usage example:

 gulp.src(src)
  .pipe(assets)
  .pipe(if('*.js', uglify({preserveComments: 'some'})))
  .pipe(if('*.css', uncss({
     html: src,
     ignore: [ ] // CSS Selectors for UnCSS to ignore
  })))
  .pipe($.if('*.css', csso()))
  .pipe(assets.restore())
  .pipe(useref())
  .pipe(if('*.html', minifyHtml()))
  .pipe(gulp.dest(dest));

Contributing

Anyone can help make this project better - check out the Contributing guide.

Release History

0.9.4 (02/18/15)

• Replace gulp-6to5 to gulp-babel. Due to project 6to5 project renamed to Babel

0.9.3 (02/14/15)

• [BugFix] Unhandled rejection TypeError. Alert user with failure message and warning message when necessary

0.9.2 (02/08/15)

• [Major/Breakage] Update Ember version to v1.10.0, and use HTMLBars instead of handlebars
• Update the gulp-6to5 to v3.0.0, update the 6to5-core the v3.0.0+
• Major rewrites on most of internal modules, huge performance boost, and improved code readability
• Use Promise A plus spec internally to handle inefficient callback hell issues. Take full advantage of Async operation.
• Removed unused gulp-plugins from "devDependencies" of package.json to speed up the initial npm module download time
• Update the module gulp-htmlbars to latest v0.3.0
• [ENHENCEMENT] Sass pre-compiler (gulp sass task) has been dramatically simplified to provide a better and faster css compilation.
• Replaced the testing framework from Mocha to Lab, assertion library from Chai to Code.

0.8.0 (01/24/15)

• [ENHENCEMENT] Used new module gulp-htmlbars which is maintained by author(myself) of ember-rocks. Read more details. By using gulp-htmlbars, successfully removed the dependency of those modules: ember-cli-htmlbars, ember-handlebars, gulp-handlebars

0.7.0 (01/23/15)

• [New Feature] Generator command take an optional flag -T or --test to generate the its unit test file. ex: em g route:post --test
• [ENHENCEMENT] Calling any em commands at root level or anywhere in your project, it will execute the task(s) as you expected.
• Major refactoring generator command and generation process
• [BugFix] When type is route or component, template file is already existed, it won't kill the process. simply output a warning.
• [BugFix] Fixed all jshint errors in the project
• [New Feature] introduce code quality tool jscs, fixed all jscs issues in the project
• [ENHENCEMENT] Update module dependencies and fixed the issue of liftoff 2x / v8flags 2x release
• Updated the project and testing documentation

0.6.0 (Christmas Day, 2014)

• [Major/New Command] em test|em t has been added into the project. It will auto watch/compile/run/rerun all existing integration/unit tests. See em --help from CLI or Testing your app for more details.
• [Major/New Generators] A whole suite of testing generators (integration & unit) have been added into em generate|em g command and followed the existing generator syntax. ex: em g [*-]test(s):[name]. See em g -h in CLI for usage and description. Here is a list of new generators: 'test', 'adapter-test', 'component-test', 'controller-test', 'helper-test', 'initializer-test', 'mixin-test', 'model-test', 'route-test', 'serializer-test', 'transform-test', 'util-test', 'view-test'
• New set of unit tests on generating integration/unit test files have been added for testing the behavior of em g [*-]test:[name] command
• Prepare a sample integration test inside client/tests/integration with two passing tests when run em t at first time
• Global string utility to handle project-wide string transformation
• Update testing documentation in Readme

0.5.2 (12/19/14)

• Using the official gulp-wrap-amd module instead of my fork which has been successfully merged and released to v0.4.0
• Using bower to install almond dependency and remove the custom almond.js script, add shim to support new feature
• Handlebars exists in the global scope and also can be imported as an AMD module

0.5.1 (12/18/14)

• Simplified the way of compiling Handlebars's Htmlbars by forking two modules. gulp-handlebars and gulp-wrap-amd
• Used the official ember-cli-htmlbars repo instead of the fork version
• Update packages' version of 'dependencies' and 'devDependencies', patches and fixes applied on the newer version requirements
• Address/Apply the previous PR by an awesome contributor

0.4.1 (12/14/14)

• [Major/Breakage] Bump up versions - Ember#1.9.0, Handlebars#2.0.0. This is a major update and it will breaks the previous builds. Due to Handerbars#2.0.0 changelogs. Read here and here to see why it is not backward compatible.
• 0.4.0 has an missing typo and fixed in the new release v0.4.1

0.3.1 (12/13/14)

• [ENHENCEMENT] Replace the old gulp-ember-handlebars(deprecated module) with the recommended module gulp-handlebars with Ember-Rocks custom gulp-defined-module to handle AMD module dependencies.
• [BugFix] With the newest Ember#1.9.0 ( Released on 12/8/14 ), it required the new hard dependencies of handlebars#2.0.0, so that bower install dependency will confuse with the right version to install, it breaks the em new command in some sort.

0.3.0 (11/19/14)

• Replace Traceur ES6 compiler with 6to5 compiler. Now, the compiled ember code is clean and readable. In addition, it has a javascript sourcemap support so that it could trace back to the definition of original ES6 source code.
• [BugFix] In the build process, recursive copy server directory issue has been fixed.

0.2.0 (11/14/14)

• Bump up to the latest version for ember#1.8.1, ember-data#1.0.0-beta.11, and ember-resolver#0.1.10
• Replace the deprecated module "gulp-ember-handlebars" with the recommended module "gulp-handlebars"
• [BugFix] sass/css sourcemap can be debugged directly in the chrome devtool with the right path and line number
• [BugFix] livereload script need to be removed in the production environment

0.1.11 (8/20/14)

• Add command for building a Cordova application ( em mobile | em m)

0.1.9 (8/13/14)

• Add command alias ( em server | em s) && ( em build | em b)
• Dev and Prod environment can use npm start to kick out a Node server

0.1.8 (8/7/14)

• Fix sass loading partial resource issue

0.1.7 (8/2/14)

• Add badges, Travis CI, Lisense
• more info on project README
• jshint 100% free on all javascript files
• lots of bug fixes

0.1.0 (8/1/14)

• Initial Release

License

Copyright (c) 2015 Matt Ma

Ember Rocks is MIT Licensed.