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
- 3rd Party Library Installation
- 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 which will contain the hero component and related test and style files.
The generated route will also be registered with the parent component's @RouteConfig
decorator.
By default the route will be designated as a lazy route which means that it will be loaded into the browser when needed, not upfront as part of a bundle.
In order to visually distinguish lazy routes from other routes the folder for the route will be prefixed with a +
per the above example the folder will be named +hero
.
This is done in accordance with the style guide.
The default lazy nature of routes can be turned off via the lazy flag (--lazy false
)
There is an optional flag for skip-router-generation
which will not add the route to the parent component's @RouteConfig
decorator.
Creating a build
ng build
The build artifacts will be stored in the dist/
directory.
Environments
At build time, the src/client/app/environment.ts
will be replaced by either
config/environment.dev.ts
or config/environment.prod.ts
, depending on the
current cli environment.
Environment defaults to dev
, but you can generate a production build via
the -prod
flag in either ng build -prod
or ng serve -prod
.
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
The index.html file includes a commented-out code snippet for installing the angular2-service-worker. This support is experimental, please see the angular/mobile-toolkit project for documentation on how to make use of this functionality.
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.
3rd Party Library Installation
The installation of 3rd party libraries are well described at our Wiki Page
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
andserve
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