ember-rocks0.9.5 • Public • Published
Ember Rocks ( a.k.a em-cli )
npm install -g ember-rocks
After the installation, you should have a global command
em --help, you should see a list of helper information.
em generate --help to see a specific command helper information.
- 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
- 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,
There are a few reasons why I started with this project:
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.
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.
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.
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.
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 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.
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.
em new my-app # generate a brand new ember app in *my-app* foldercd my-app # switch to application folderem serve # start a server, open the new app in browser, livereload all resources
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 apps|serve # Builds and serves your app, rebuilding on file changesm|mobile # Builds an Cordova application, and ready to deploy to phone or tabletb|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 changesOptions:-h, --help output usage information-V, --version output the version numberCommand-Specific Help:em [command] --help
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) 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
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 with file extension
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.
Easy way, but requires two different processes and
testem installed globally in your system. (
npm install testem -g )
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.
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 1em test# process 2cd path/to/root...cd buildtestem
Building a web app (desktop and browsers)
em buildcd buildnpm installnpm start# Visit your production ready app at
Building a native app (phone and tablet)
em mobilecd buildnpm installcd build/cordova # if in `build` folder, just `cd cordova`. Note: need to be in `cordova` folder to execute `cordova` commandcordova 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
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
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.
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,
jscs in a easy way ( Bonus: running jshint and jscs in one shot ):
# running jscs code quality assertiongulp jscs# running both jshint and jscs in one commandgulp lint
jscs in a hard way:
# make sure that `jscs` installed globallyjscs --version# client side *.js code qualityjscs client/**/*.js# server side *.js code qualityjscs server/**/*.js# gulpfile.js code qualityjscs *.js
- Well-defined structure for each
gulptask. User could pick
stylusetc when run
- 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.
small debugging utility. tiny node.js debugging utility modelled after node core's debugging technique.
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.
Only pass through changed files. It may add back in the future. Or if you like to contribute, submit a PR.
Display the size of your project. Logs out the total size of files in the stream and optionally the individual file-sizes.
PageSpeed Insights with reporting.
var pagespeed = ;// 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 for info key: 'YOUR_API_KEY'// More Info:gulp;
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.
Anyone can help make this project better - check out the Contributing guide.
- Replace gulp-6to5 to gulp-babel. Due to project 6to5 project renamed to Babel
- [BugFix] Unhandled rejection TypeError. Alert user with failure message and warning message when necessary
- [Major/Breakage] Update
v1.10.0, and use
- Update the
gulp-6to5to v3.0.0, update the
- 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
npmmodule download time
- Update the module
gulp-htmlbarsto 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.
- [ENHENCEMENT] Used new module
gulp-htmlbarswhich is maintained by author(myself) of
ember-rocks. Read more details. By using
gulp-htmlbars, successfully removed the dependency of those modules:
- [New Feature] Generator command take an optional flag
--testto generate the its unit test file. ex:
em g route:post --test
- [ENHENCEMENT] Calling any
emcommands 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
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 thas been added into the project. It will auto watch/compile/run/rerun all existing integration/unit tests. See
em --helpfrom CLI or Testing your app for more details.
- [Major/New Generators] A whole suite of testing generators (integration & unit) have been added into
em gcommand and followed the existing generator syntax. ex:
em g [*-]test(s):[name]. See
em g -hin 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/integrationwith two passing tests when run
em tat first time
- Global string utility to handle project-wide string transformation
- Update testing documentation in Readme
- 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
almonddependency and remove the custom almond.js script, add shim to support new feature
Handlebarsexists in the global scope and also can be imported as an AMD module
- 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
- [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
- [ENHENCEMENT] Replace the old
gulp-ember-handlebars(deprecated module) with the recommended module
gulp-handlebarswith Ember-Rocks custom
gulp-defined-moduleto 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 installdependency will confuse with the right version to install, it breaks the
em newcommand in some sort.
- [BugFix] In the build process, recursive copy server directory issue has been fixed.
- 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
- Add command for building a Cordova application (
- Add command alias (
em s) && (
- Dev and Prod environment can use
npm startto kick out a Node server
- Fix sass loading partial resource issue
- Add badges, Travis CI, Lisense
- more info on project README
- lots of bug fixes
- Initial Release
Copyright (c) 2015 Matt Ma
Ember Rocks is MIT Licensed.