If you are updating from a beta or RC version, check out our 1.0 Update Guide.
If you wish to collaborate, check out our issue list.
Before submitting new issues, have a look at issues marked with the
type: faq label.
Both the CLI and generated project have dependencies that require Node 8.9 or higher, together with NPM 5.5.1 or higher.
Table of Contents
- Generating a New Project
- Generating Components, Directives, Pipes and Services
- Updating Angular CLI
- Development Hints for working on Angular CLI
BEFORE YOU INSTALL: please read the prerequisites
npm install -g @angular/cli
npm install @angular/cli
To run a locally installed version of the angular-cli, you can call
ng commands directly by adding the
.bin folder within your local
node_modules folder to your PATH. The
.bin folders are created in the directory where
npm install @angular/cli was run upon completion of the install command.
Alternatively, you can install npx and run
npx ng <command> within the local directory where
npm install @angular/cli was run, which will use the locally installed angular-cli.
Install Specific Version (Example: 6.1.1)
npm install -g @email@example.com
Generating and serving an Angular project via a development server
ng new PROJECT-NAMEcd PROJECT-NAMEng serve
http://localhost:4200/. The app will automatically reload if you change any of the source files.
You can configure the default HTTP host and port used by the development server with two command-line options :
ng serve --host 0.0.0.0 --port 4201
Generating Components, Directives, Pipes and Services
You can use the
ng generate (or just
ng g) command to generate Angular components:
ng generate component my-new-componentng g component my-new-component # using the alias# components support relative path generation# if in the directory src/app/feature/ and you runng g component new-cmp# your component will be generated in src/app/feature/new-cmp# but if you were to runng g component ./newer-cmp# your component will be generated in src/app/newer-cmp# if in the directory src/app you can also runng g component feature/new-cmp# and your component will be generated in src/app/feature/new-cmp
You can find all possible blueprints in the table below:
angular-cli will add reference to
pipes automatically in the
app.module.ts. If you need to add this references to another custom module, follow these steps:
ng g module new-moduleto create a new module
ng g component new-module/new-component
This should add the new
pipe reference to the
new-module you've created.
Updating Angular CLI
If you're using Angular CLI
1.0.0-beta.28 or less, you need to uninstall
angular-cli package. It should be done due to changing of package's name and scope from
npm uninstall -g angular-clinpm uninstall --save-dev angular-cli
To update Angular CLI to a new version, you must update both the global package and your project's local package.
npm uninstall -g @angular/clinpm cache verify# if npm version is < 5 then use `npm cache clean`npm install -g @angular/cli@latest
Local project package:
rm -rf node_modules dist # use rmdir /S/Q node_modules dist in Windows Command Prompt; use rm -r -fo node_modules,dist in Windows PowerShellnpm install --save-dev @angular/cli@latestnpm install
If you are updating to 1.0 from a beta or RC version, check out our 1.0 Update Guide.
You can find more details about changes between versions in the Releases tab on GitHub.
Development Hints for working on Angular CLI
Working with master
git clone https://github.com/angular/angular-cli.gityarnnpm run buildcd dist/@angular/clinpm link
npm link is very similar to
npm install -g except that instead of downloading the package
from the repo, the just built
dist/@angular/cli/ folder becomes the global package.
Additionally, this repository publishes several packages and we use special logic to load all of them
on development setups.
Any changes to the files in the
angular-cli/ folder will immediately affect the global
meaning that, in order to quickly test any changes you make to the cli project, you should simply just run
npm run build
Now you can use
@angular/cli via the command line:
ng new foocd foonpm link @angular/cling serve
npm link @angular/cli is needed because by default the globally installed
@angular/cli just loads
@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 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.
You can also use
ng new foo --link-cli to automatically link the
To run the Angular CLI E2E test suite, use the
node ./tests/legacy-cli/run_e2e command.
It can also receive a filename to only run that test (e.g.
node ./tests/legacy-cli/run_e2e tests/legacy-cli/e2e/tests/build/dev-build.ts).
As part of the test procedure, all packages will be built and linked.
You will need to re-run
npm link to re-link the development Angular CLI environment after tests finish.
Debugging with VS Code
In order to debug some Angular CLI behaviour using Visual Studio Code, you can run
npm run build, and then use a launch configuration like the following:
Then you can add breakpoints in
For more informations about Node.js debugging in VS Code, see the related VS Code Documentation.
In order to investigate performance issues, CPU profiling is often useful.
To capture a CPU profiling, you can:
- install the v8-profiler-node8 dependency:
npm install v8-profiler-node8 --no-save
- set the NG_CLI_PROFILING Environment variable to the file name you want:
- on Unix systems (Linux & Mac OS X): ̀
- on Windows: ̀̀
setx NG_CLI_PROFILING my-profile
- on Unix systems (Linux & Mac OS X): ̀
Then, just run the ng command on which you want to capture a CPU profile.
You will then obtain a
my-profile.cpuprofile file in the folder from which you ran the ng command.
You can use the Chrome Devtools to process it. To do so:
- click on "Open dedicated DevTools for Node"
- go to the "profiler" tab
- click on the "Load" button and select the generated .cpuprofile file
- on the left panel, select the associated file
In addition to this one, another, more elaborated way to capture a CPU profile using the Chrome Devtools is detailed in https://github.com/angular/angular-cli/issues/8259#issue-269908550.
The documentation for the Angular CLI is located in this repo's wiki.