search

mattma / ember-rocks

An Em(ber) command line utility to help you build an ambitious web application via `em` command
MIT License
70 stars 5 forks source link

readme

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

NPM NPM download

NPM version Build Status Dependency Status

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

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.

( 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

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.

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

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'
}));

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)

0.9.3 (02/14/15)

0.9.2 (02/08/15)

0.8.0 (01/24/15)

0.7.0 (01/23/15)

0.6.0 (Christmas Day, 2014)

0.5.2 (12/19/14)

0.5.1 (12/18/14)

0.4.1 (12/14/14)

0.3.1 (12/13/14)

0.3.0 (11/19/14)

0.2.0 (11/14/14)

0.1.11 (8/20/14)

0.1.9 (8/13/14)

0.1.8 (8/7/14)

0.1.7 (8/2/14)

0.1.0 (8/1/14)

License

Copyright (c) 2015 Matt Ma

Ember Rocks is MIT Licensed.