angular-cli

Angular-CLI

Prototype of a CLI for Angular 2 applications based on the ember-cli project.

Note

This project is very much still a work in progress.

We still have a long way before getting out of our alpha stage. If you wish to collaborate while the project is still young, check out our issue list.

Prerequisites

The generated project has dependencies that require Node 4 or greater.

Table of Contents

• Installation
• Usage
• Generating a New Project
• Generating Components, Directives, Pipes and Services
• Generating a Route
• Creating a Build
• Running Unit Tests
• Running End-to-End Tests
• Deploying the App via GitHub Pages
• Support for offline applications
• Commands autocompletion
• CSS preprocessor integration
• Known Issues

Installation

BEFORE YOU INSTALL: please read the prerequisites

npm install -g angular-cli

Usage

ng --help

Generating and serving an Angular2 project via a development server

ng new PROJECT_NAME
cd PROJECT_NAME
ng serve

Navigate to http://localhost:4200/. The app will automatically reload if you change any of the source files.

You can configure the default HTTP port and the one used by the LiveReload server with two command-line options :

ng serve --port 4201 --live-reload-port 49153

Generating other scaffolds

You can use the ng generate (or just ng g) command to generate Angular components:

ng generate component my-new-component
ng g component my-new-component # using the alias

# components support relative path generation
# if in the directory src/app/feature/ and you run
ng g component new-cmp
# your component will be generated in src/app/feature/new-cmp
# but if you were to run
ng g component ../newer-cmp
# your component will be generated in src/app/newer-cmp

You can find all possible blueprints in the table below:

Scaffold	Usage
Component	ng g component my-new-component
Directive	ng g directive my-new-directive
Pipe	ng g pipe my-new-pipe
Service	ng g service my-new-service

Generating a route

You can generate a new route by with the following command (note the singular used in hero):

ng generate route hero

This will create a folder with a routable component (hero-root.component.ts) with two sub-routes. The file structure will be as follows:

...
|-- app
|   |-- hero
|   |   |-- hero-detail.component.html
|   |   |-- hero-detail.component.css
|   |   |-- hero-detail.component.spec.ts
|   |   |-- hero-detail.component.ts
|   |   |-- hero-list.component.html
|   |   |-- hero-list.component.css
|   |   |-- hero-list.component.spec.ts
|   |   |-- hero-list.component.ts
|   |   |-- hero-root.component.spec.ts
|   |   |-- hero-root.component.ts
|   |   |-- hero.service.spec.ts
|   |   |-- hero.service.ts
|   |-- ...
|-- app.ts
|-- route-config.ts
...

By default the cli will add the import statements for HeroList and HeroDetail to hero-root.component.ts:

@RouteConfig([
  {path:'/', name: 'HeroList', component: HeroListComponent, useAsDefault: true},
  {path:'/:id', name: 'HeroDetail', component: HeroDetailComponent}
])

The generated route-config.ts file is also updated with the following:

// DO NOT EDIT THIS FILE
// IT IS AUTO GENERATED BY ANGULAR-CLI
import {HeroRoot} from './hero/hero-root.component';

export const CliRouteConfig = [
  {path:'/hero/...', name: 'HeroRoot', component: HeroRoot}
];

Visiting http://localhost:4200/hero will show the hero list.

There is an optional flag for skip-router-generation which will not add the route to the CliRouteConfig for the application.

Creating a build

ng build

The build artifacts will be stored in the dist/ directory.

Running unit tests

ng test

Tests will execute after a build is executed via Karma

If run with the watch argument --watch (shorthand -w) builds will run when source files have changed and tests will run after each successful build

Running end-to-end tests

ng e2e

Before running the tests make sure you are serving the app via ng serve.

End-to-end tests are ran via Protractor.

Deploying the app via GitHub Pages

You can deploy your apps quickly via:

ng github-pages:deploy --message "Optional commit message"

This will do the following:

• creates GitHub repo for the current project if one doesn't exist
• rebuilds the app at the current HEAD
• creates a local gh-pages branch if one doesn't exist
• moves your app to the gh-pages branch and creates a commit
• edit the base tag in index.html to support github pages
• pushes the gh-pages branch to github
• returns back to the original HEAD

Creating the repo requires a token from github, and the remaining functionality relies on ssh authentication for all git operations that communicate with github.com. To simplify the authentication, be sure to setup your ssh keys.

Linting and formatting code

You can lint or format your app code by running ng lint or ng format respectively. This will use the lint/format npm script that in generated projects uses tslint/clang-format.

You can modify the these scripts in package.json to run whatever tool you prefer.

Support for offline applications

By default a file manifest.appcache will be generated which lists all files included in a project's output, along with SHA1 hashes of all file contents. This file can be used directly as an AppCache manifest (for now, index.html must be manually edited to set this up).

The manifest is also annotated for use with angular2-service-worker. Some manual operations are currently required to enable this usage. The package must be installed, and worker.js manually copied into the project src directory:

npm install angular2-service-worker
cp node_modules/angular2-service-worker/dist/worker.js src/

Then, the commented snippet in index.html must be uncommented to register the worker script as a service worker.

Commands autocompletion

To turn on auto completion use the following commands:

For bash:

ng completion >> ~/.bashrc
source ~/.bashrc

For zsh:

ng completion >> ~/.zshrc
source ~/.zshrc

Windows users using gitbash:

ng completion >> ~/.bash_profile
source ~/.bash_profile

CSS Preprocessor integration

We support all major CSS preprocessors:

• sass (node-sass)
• less (less)
• compass (compass-importer + node-sass)
• stylus (stylus)

To use one just install for example npm install node-sass and rename .css files in your project to .scss or .sass. They will be compiled automatically.

The Angular2App's options argument has sassCompiler, lessCompiler, stylusCompiler and compassCompiler options that are passed directly to their respective CSS preprocessors.

Known issues

This project is currently a prototype so there are many known issues. Just to mention a few:

• All blueprints/scaffolds are in TypeScript only, in the future blueprints in all dialects officially supported by Angular will be available.
• On Windows you need to run the build and serve commands with Admin permissions, otherwise the performance is not good.
• Protractor integration is missing.
• The initial installation as well as ng new take too long because of lots of npm dependencies.
• Many existing ember addons are not compatible with Angular apps built via angular-cli.
• When you ng serve remember that the generated project has dependencies that require Node 4 or greater.

Development Hints for hacking on angular-cli

Working with master

git clone https://github.com/angular/angular-cli.git
cd angular-cli
npm link

npm link is very similar to npm install -g except that instead of downloading the package from the repo, the just cloned angular-cli/ folder becomes the global package. Any changes to the files in the angular-cli/ folder will immediately affect the global angular-cli package, allowing you to quickly test any changes you make to the cli project.

Now you can use angular-cli via the command line:

ng new foo
cd foo
npm link angular-cli
ng server

npm link angular-cli is needed because by default the globally installed angular-cli just loads the local angular-cli from the project which was fetched remotely from npm. npm link angular-cli symlinks the global angular-cli package to the local angular-cli package. Now the angular-cli you cloned before is in three places: The folder you cloned it into, npm's folder where it stores global packages and the angular-cli project you just created.

Please read the official npm-link documentation and the npm-link cheatsheet for more information.

License

MIT