Skip to content
This repository has been archived by the owner on Dec 30, 2018. It is now read-only.

Commit

Permalink
bump 1.0.0
Browse files Browse the repository at this point in the history
  • Loading branch information
@vesparny
vesparny committed Oct 29, 2014
1 parent 021bdb4 commit f685676
Show file tree
Hide file tree
Showing 2 changed files with 55 additions and 124 deletions.
16 changes: 13 additions & 3 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -1,17 +1,27 @@
# 1.0.0 (2014-10-29)

### Features

* transition to gulpjs
* removed backend stuff
* e2e testing support with protractor
* using purecss + SMACSS
* following AngularJS styleguide by todd motto

# 0.0.2 (2013-12-11)

## Features
### Features

* grunt unit task

## Bug fixes
### Bug fixes

* docs improvement


# 0.0.1 (2013-12-07)

## Features
### Features

* javascript files continuous linting.
* sass continuous compiling.
Expand Down
163 changes: 42 additions & 121 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,157 +1,78 @@
# [angular-kickstart](http://vesparny.github.io/angular-kickstart/)
rename to angular-kickstart bitly

[![Build Status](https://secure.travis-ci.org/vesparny/angular-kickstart.png)](http://travis-ci.org/vesparny/angular-kickstart)
[![Build Status](https://secure.travis-ci.org/vesparny/angular-kickstart.svg)](http://travis-ci.org/vesparny/angular-kickstart)

**Brought to you by [Alessandro Arnodo](http://alessandro.arnodo.net) [[@vesparny](https://twitter.com/vesparny)]**
http://selenium.googlecode.com/git/docs/api/javascript/index.html

[![Dev dependency status](https://david-dm.org/vesparny/angular-kickstart/dev-status.png)](https://david-dm.org/vesparny/angular-kickstart#info=devDependencies "Dependency status") [![Bitdeli Badge](https://d2weczhvl823v0.cloudfront.net/vesparny/angular-kickstart/trend.png)](https://bitdeli.com/free "Bitdeli Badge")
[![Dev dependency status](https://david-dm.org/vesparny/angular-kickstart/dev-status.png)](https://david-dm.org/vesparny/angular-kickstart#info=devDependencies "Dependency status")

**Speed up your [AngularJS 1.2](http://angularjs.org) development with a complete and scalable build system that scaffolds the project for you. Just focus on your app, angular-kickstart will take care of the rest.**
**Speed up your [AngularJS](http://angularjs.org) development with a complete and scalable gulpjs based build system that scaffolds the project for you. Just focus on your app, angular-kickstart will take care of the rest.**
***

#### See a [demo](http://vesparny.github.io/angular-kickstart/).
#### See a [working demo](http://vesparny.github.io/angular-kickstart/).

##What and Why
### What and Why

angular-kickstart is an opinionated kickstart for single page application development in AngularJS 1.2. It makes your development easy, keeps the structure of the project consistent and allows you to create a fully-optimized production release with a single grunt task. I decided to build this tool because of the lack of a build system that let me develop a single page application while keeping an organized file structure; and in the meantime that allowed me to develop on an index.html file generated at build time, tied to my real backend.
angular-kickstart is an opinionated kickstart for single page application development with AngularJS. It makes your development and testing easy, keeps the structure of the project consistent and allows you to create a fully optimized production release withe ease. After having developed a lot of AngularJS projects I decided to collect here what I've learnt.

##Getting started
### Getting started

Install **node.js**. Then **sass**, **grunt-cli** **karma** and **bower** if you haven't yet.
Install **node.js**. Then **sass**, **gulp** and **bower** if you haven't yet.

$ gem install sass
$ sudo npm -g install grunt-cli karma bower
$ npm -g install gulp bower

After that, install angular-kickstart downloading the [latest release](https://github.com/vesparny/angular-kickstart/releases) (or clone the master branch if you want to run the development version). Unzip the project and cd into it, then install bower and npm dependencies, and run the application in development mode.

$ npm install
$ bower install
$ grunt serve
$ gulp serve

You are now ready to go, your applcation is available at **http://127.0.0.1:8000**. Every request to /api will be proxied to **http://127.0.0.1:8001/api**.
You are now ready to go, your applcation is available at **http://127.0.0.1:3000**.

In the `/backend` folder, you can find two examples of a **RESTFul backend**. One using **Silex PHP micro-framework + SQLite** and another using **expressjs + MongoDB**. Refer to the README.md in each folder to launch the desired backend (or run your own). Then go to **http://127.0.0.1:8000/notes**. You are now ready to start coding.

**Every file you add, edit or delete into the `/webapp` folder will be handled by the build system**.
**Every file you add, edit or delete into the `/client` folder will be handled by the build system**.

When you are ready to build a production release there is a task for that:

$ grunt dist

After the task has finished you can find an optimized version of your project inside the `/build/dist` folder.


##Directory Structure

At a high level, the structure looks roughly like this:

```
angular-kickstart/
├── backend
│   ├── expressjs
│   └── silex
├── build
│   ├── buildfiles
│   │   ├── tasks
│   │   │   └── tpl.js
│   │   ├── utils
│   │   │   └── grunt-connect-html5Mode.js
│   │   ├── external-tasks.js
│   │   ├── module.prefix
│   │   └── module.suffix
│   ├── build.config.js
│   └── karma.config.unit.js
├── webapp
│   ├── src
│   │   ├── app
│   │   │   ├── docs
│   │   │   │   ├── docs.js
│   │   │   │   └── docs.tpl.html
│   │   │   ├── home
│   │   │   │   ├── home.js
│   │   │   │   └── home.tpl.html
│   │   │   ├── notes
│   │   │   │   ├── notes.js
│   │   │   │   ├── notes.tpl.html
│   │   │   │   └── notesService.js
│   │   │   └── app.js
│   │   ├── assets
│   │   │   ├── fonts
│   │   │   │   ├── FontAwesome.otf
│   │   │   │   ├── fontawesome-webfont.eot
│   │   │   │   ├── fontawesome-webfont.svg
│   │   │   │   ├── fontawesome-webfont.ttf
│   │   │   │   └── fontawesome-webfont.woff
│   │   │   ├── img
│   │   │   │   ├── angular-logo.png
│   │   │   │   ├── bower-logo.png
│   │   │   │   └── grunt-logo.png
│   │   │   └── favicon.ico
│   │   ├── common
│   │   │   ├── directives
│   │   │   │   ├── appVersion.js
│   │   │   │   └── plusOne.js
│   │   │   └── interceptors
│   │   │   └── http.js
│   │   └── sass
│   │   ├── app
│   │   │   └── _foundation-custom-vars.scss
│   │   └── main.scss
│   ├── test
│   │   └── app
│   │   └── home
│   │   └── home.spec.js
│   ├── vendor
│   └── index.tpl.html
├── .bowerrc
├── .jshintrc
├── Gruntfile.js
├── bower.json
└── package.json
```

- `backend/` - Fully working RESTful backend, available in 2 versions.
- `build/` - Build files and configuration, the most important files to note are `build.config.js` and `karma.config.unit.js`. These files are the heart of the build system, and they are well commented so take a look for more information.
- `webapp/` the source code of your application, take a look at the modules in this folder, you should structure your application following those conventions, but you can choose another convention as well.
- `.bowerrc` - the Bower configuration file. This tells Bower to install components in the `webapp/vendor/` directory.
- `.jshintrc` - JSHint configuration.
- `Gruntfile.js` - see [The Build System](#thebuildsystem) below.
- `bower.json` - It contains the list of Bower dependencies.
- `build.config.js` - our customizable build settings; see "The Build System" below.
- `package.json` - node.js dependencies.

### <a name="thebuildsystem"></a>The Build System

There are some `tasks` available in `Gruntfile.js`. Every task is defined in `build/external-tasks.js`. You can dig into the file to familiarize yourself with grunt, but you don't have to in order to be getting started with angular-kickstart.

A description of every available task:

* **grunt serve** - When this task runs, the build system will create a version of the application under the `build/tmp/` folder. The build will take care of creating an index.html with js and css (generated from sass) loaded. Every request to `/api` will be proxied to your backend listening to port 8001 by default. Every time you change a file into the `webapp/` folder, the build recompiles every file, and your browser will reload automagically showing you your changes.
* **grunt dist** - This task will run jshint and unit tests under the `webapp/test/` folder (thanks to `karma runner`), and create a fully-optimized version of your code under the `build/dist/` folder. The optimization consists of concatenate, minify and compress js and css files, optimize images, and put every template into a js file loaded by the application.
* **grunt unit** - Just run unit tests.
$ gulp serve:dist

This task will lint your code, optimize css js and images files, run unit tests. After the task has successfully finished, you can find an optimized version of your project inside the `/build/dist` folder.

### Features

* 3 simple task: grunt serve, grunt dist, grunt unit
* JavaScript file continuous linting.
* 5 simple task: `gulp serve`,`gulp serve:dist`, `gulp serve:tdd`, `gulp test:unit`, `gulp test:e2e`
* JavaScript file continuous linting with `jshint`.
* SASS continuous compiling.
* Unit testing ready and configured.
* HTML templates converted into strings and attached to javascript files (to avoid one http call for every template).
* Proxy every request to `/api` (configurable of course) to your backend listening on another port.
* Livereload.
* `Unit` and `e2`e testing support. (for `e2e` testing you need to have a java runtine installed, take a look at [selenium JavaScript api ](http://selenium.googlecode.com/git/docs/api/javascript/index.html) and [protractor](https://github.com/angular/protractor) for more informations.
* HTML templates converted into strings and attached to a single javascript file (to avoid one http call for each template).
* Livereload provided by [browsersync](http://www.browsersync.io/).
* angular module dependencies automatically injected using [ng-annotate](https://github.com/olov/ng-annotate).
* Static resources minification and optimization for production.
* html5mode enabled by default (and fully handled by the build connect middleware).

**See also the CHANGELOG.md file**
### Directory Structure

* `build/` - Build files and configuration, the most important files to note are `build.config.js`, `protractor.config.js` and `karma.config.js`. These files are the heart of the build system
* `client/` the source code and tests of your application, take a look at the modules in this folder, you should structure your application following those conventions, but you can choose another convention as well.
* `.bowerrc` - the bower configuration file. This tells Bower to install components in the `client/src/vendor` directory.
* `.jshintrc` - JSHint configuration.
* `gulpfile` - see [The Build System](#thebuildsystem) below.
* `bower.json` - Contains the list of bower dependencies.
* `package.json` - node.js dependencies.

### <a name="thebuildsystem"></a>The Build System

There are some `tasks` available in `gulpfile.js`. You can dig into the file to familiarize yourself with gulpjs.

### TODO
A description of every available task:

* E2E tests with protractor
* ...
* **gulp serve** - When this task runs, the build will take care of watching filea. Every time you change a file into the `client/` folder, the build recompiles every file, and your browser will reload automagically showing you changes.
You just need to add new JavaScript and css files in the `client/index.html` file.
* **gulp serve:dist** - This task will run jshint and unit tests under the `client/test/unit` folder (thanks to `karma runner`), and create a fully-optimized version of your application under the `build/dist/` folder. The optimization consists of concatenate, minify and compress js and css files, optimize images, and put every template into a js file loaded by the application.
A code coverage report will be available inside the `client/test/unit-results`.
* **gulp serve:tdd** - Just like `gulp serve` but in continuous unit testing environment.
* **gulp test:unit** - For running unit tests one time then exit.
* **gulp test:e2e** - Run end-to-end tests inside the `client/test/e2e` folder with `protractor`. If a test fails, you should find a screenshot of the page inside the `client/test/screenshots` folder.
**Note that you need to have the application running in order to run e2e tests. You can launch this task from another terminal instance.**

### Contributing

Expand Down

0 comments on commit f685676

Please sign in to comment.