UNPKG

11.1 kBMarkdownView Raw
1## Angular CLI
2
3<!-- Badges section here. -->
4[![Dependency Status][david-badge]][david-badge-url]
5[![devDependency Status][david-dev-badge]][david-dev-badge-url]
6
7[![npm](https://img.shields.io/npm/v/%40angular/cli.svg)][npm-badge-url]
8[![npm](https://img.shields.io/npm/v/%40angular/cli/next.svg)][npm-badge-url]
9[![npm](https://img.shields.io/npm/l/@angular/cli.svg)][license-url]
10[![npm](https://img.shields.io/npm/dm/@angular/cli.svg)][npm-badge-url]
11
12[![Join the chat at https://gitter.im/angular/angular-cli](https://img.shields.io/gitter/room/nwjs/nw.js.svg)](https://gitter.im/angular/angular-cli?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
13
14[![GitHub forks](https://img.shields.io/github/forks/angular/angular-cli.svg?style=social&label=Fork)](https://github.com/angular/angular-cli/fork)
15[![GitHub stars](https://img.shields.io/github/stars/angular/angular-cli.svg?style=social&label=Star)](https://github.com/angular/angular-cli)
16
17
18## Note
19
20If you are updating from a beta or RC version, check out our [1.0 Update Guide](https://github.com/angular/angular-cli/wiki/stories-1.0-update).
21
22If you wish to collaborate, check out [our issue list](https://github.com/angular/angular-cli/issues).
23
24Before submitting new issues, have a look at [issues marked with the `type: faq` label](https://github.com/angular/angular-cli/issues?utf8=%E2%9C%93&q=is%3Aissue%20label%3A%22type%3A%20faq%22%20).
25
26## Prerequisites
27
28Both the CLI and generated project have dependencies that require Node 8.9 or higher, together
29with NPM 5.5.1 or higher.
30
31## Table of Contents
32
33* [Installation](#installation)
34* [Usage](#usage)
35* [Generating a New Project](#generating-and-serving-an-angular-project-via-a-development-server)
36* [Generating Components, Directives, Pipes and Services](#generating-components-directives-pipes-and-services)
37* [Updating Angular CLI](#updating-angular-cli)
38* [Development Hints for working on Angular CLI](#development-hints-for-working-on-angular-cli)
39* [Documentation](#documentation)
40* [License](#license)
41
42## Installation
43
44**BEFORE YOU INSTALL:** please read the [prerequisites](#prerequisites)
45
46### Install Globally
47```bash
48npm install -g @angular/cli
49```
50
51### Install Locally
52```bash
53npm install @angular/cli
54```
55
56To 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 `node_modules` and `.bin` folders are created in the directory where `npm install @angular/cli` was run upon completion of the install command.
57
58Alternatively, you can install [npx](https://www.npmjs.com/package/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.
59
60### Install Specific Version (Example: 6.1.1)
61```bash
62npm install -g @angular/cli@6.1.1
63```
64
65## Usage
66
67```bash
68ng help
69```
70
71### Generating and serving an Angular project via a development server
72
73```bash
74ng new PROJECT-NAME
75cd PROJECT-NAME
76ng serve
77```
78Navigate to `http://localhost:4200/`. The app will automatically reload if you change any of the source files.
79
80You can configure the default HTTP host and port used by the development server with two command-line options :
81
82```bash
83ng serve --host 0.0.0.0 --port 4201
84```
85
86### Generating Components, Directives, Pipes and Services
87
88You can use the `ng generate` (or just `ng g`) command to generate Angular components:
89
90```bash
91ng generate component my-new-component
92ng g component my-new-component # using the alias
93
94# components support relative path generation
95# if in the directory src/app/feature/ and you run
96ng g component new-cmp
97# your component will be generated in src/app/feature/new-cmp
98# but if you were to run
99ng g component ./newer-cmp
100# your component will be generated in src/app/newer-cmp
101# if in the directory src/app you can also run
102ng g component feature/new-cmp
103# and your component will be generated in src/app/feature/new-cmp
104```
105You can find all possible blueprints in the table below:
106
107Scaffold | Usage
108--- | ---
109[Component](https://angular.io/cli/generate#component) | `ng g component my-new-component`
110[Directive](https://angular.io/cli/generate#directive) | `ng g directive my-new-directive`
111[Pipe](https://angular.io/cli/generate#pipe) | `ng g pipe my-new-pipe`
112[Service](https://angular.io/cli/generate#service) | `ng g service my-new-service`
113[Class](https://angular.io/cli/generate#class) | `ng g class my-new-class`
114[Guard](https://angular.io/cli/generate#guard) | `ng g guard my-new-guard`
115[Interface](https://angular.io/cli/generate#interface) | `ng g interface my-new-interface`
116[Enum](https://angular.io/cli/generate#enum) | `ng g enum my-new-enum`
117[Module](https://angular.io/cli/generate#module) | `ng g module my-module`
118
119
120
121
122angular-cli will add reference to `components`, `directives` and `pipes` automatically in the `app.module.ts`. If you need to add this references to another custom module, follow these steps:
123
124 1. `ng g module new-module` to create a new module
125 2. call `ng g component new-module/new-component`
126
127This should add the new `component`, `directive` or `pipe` reference to the `new-module` you've created.
128
129### Updating Angular CLI
130
131If 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 `angular-cli` to `@angular/cli`:
132```bash
133npm uninstall -g angular-cli
134npm uninstall --save-dev angular-cli
135```
136
137To update Angular CLI to a new version, you must update both the global package and your project's local package.
138
139Global package:
140```bash
141npm uninstall -g @angular/cli
142npm cache verify
143# if npm version is < 5 then use `npm cache clean`
144npm install -g @angular/cli@latest
145```
146
147Local project package:
148```bash
149rm -rf node_modules dist # use rmdir /S/Q node_modules dist in Windows Command Prompt; use rm -r -fo node_modules,dist in Windows PowerShell
150npm install --save-dev @angular/cli@latest
151npm install
152```
153
154If you are updating to 1.0 from a beta or RC version, check out our [1.0 Update Guide](https://github.com/angular/angular-cli/wiki/stories-1.0-update).
155
156You can find more details about changes between versions in [the Releases tab on GitHub](https://github.com/angular/angular-cli/releases).
157
158
159## Development Hints for working on Angular CLI
160
161### Working with master
162
163```bash
164git clone https://github.com/angular/angular-cli.git
165yarn
166npm run build
167cd dist/@angular/cli
168npm link
169```
170
171`npm link` is very similar to `npm install -g` except that instead of downloading the package
172from the repo, the just built `dist/@angular/cli/` folder becomes the global package.
173Additionally, this repository publishes several packages and we use special logic to load all of them
174on development setups.
175
176Any changes to the files in the `angular-cli/` folder will immediately affect the global `@angular/cli` package,
177meaning that, in order to quickly test any changes you make to the cli project, you should simply just run `npm run build`
178again.
179
180Now you can use `@angular/cli` via the command line:
181
182```bash
183ng new foo
184cd foo
185npm link @angular/cli
186ng serve
187```
188
189`npm link @angular/cli` is needed because by default the globally installed `@angular/cli` just loads
190the local `@angular/cli` from the project which was fetched remotely from npm.
191`npm link @angular/cli` symlinks the global `@angular/cli` package to the local `@angular/cli` package.
192Now the `angular-cli` you cloned before is in three places:
193The folder you cloned it into, npm's folder where it stores global packages and the Angular CLI project you just created.
194
195You can also use `ng new foo --link-cli` to automatically link the `@angular/cli` package.
196
197Please read the official [npm-link documentation](https://docs.npmjs.com/cli/link)
198and the [npm-link cheatsheet](http://browsenpm.org/help#linkinganynpmpackagelocally) for more information.
199
200To run the Angular CLI E2E test suite, use the `node ./tests/legacy-cli/run_e2e` command.
201It 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`).
202
203As part of the test procedure, all packages will be built and linked.
204You will need to re-run `npm link` to re-link the development Angular CLI environment after tests finish.
205
206### Debugging with VS Code
207
208In 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:
209
210```json
211{
212 "type": "node",
213 "request": "launch",
214 "name": "ng serve",
215 "cwd": "<path to an Angular project generated with Angular-CLI>",
216 "program": "${workspaceFolder}/dist/@angular/cli/bin/ng",
217 "args": [
218 "<ng command>",
219 ...other arguments
220 ],
221 "console": "integratedTerminal"
222}
223```
224
225Then you can add breakpoints in `dist/@angular` files.
226
227For more informations about Node.js debugging in VS Code, see the related [VS Code Documentation](https://code.visualstudio.com/docs/nodejs/nodejs-debugging).
228
229### CPU Profiling
230
231In order to investigate performance issues, CPU profiling is often useful.
232
233To capture a CPU profiling, you can:
2341. install the v8-profiler-node8 dependency: `npm install v8-profiler-node8 --no-save`
2351. set the NG_CLI_PROFILING Environment variable to the file name you want:
236 * on Unix systems (Linux & Mac OS X): ̀`export NG_CLI_PROFILING=my-profile`
237 * on Windows: ̀̀`setx NG_CLI_PROFILING my-profile`
238
239Then, just run the ng command on which you want to capture a CPU profile.
240You will then obtain a `my-profile.cpuprofile` file in the folder from wich you ran the ng command.
241
242You can use the Chrome Devtools to process it. To do so:
2431. open `chrome://inspect/#devices` in Chrome
2441. click on "Open dedicated DevTools for Node"
2451. go to the "profiler" tab
2461. click on the "Load" button and select the generated .cpuprofile file
2471. on the left panel, select the associated file
248
249In 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.
250
251## Documentation
252
253The documentation for the Angular CLI is located in this repo's [wiki](https://angular.io/cli).
254
255## License
256
257[MIT](https://github.com/angular/angular-cli/blob/master/LICENSE)
258
259
260[travis-badge]: https://travis-ci.org/angular/angular-cli.svg?branch=master
261[travis-badge-url]: https://travis-ci.org/angular/angular-cli
262[david-badge]: https://david-dm.org/angular/angular-cli.svg
263[david-badge-url]: https://david-dm.org/angular/angular-cli
264[david-dev-badge]: https://david-dm.org/angular/angular-cli/dev-status.svg
265[david-dev-badge-url]: https://david-dm.org/angular/angular-cli?type=dev
266[npm-badge]: https://img.shields.io/npm/v/@angular/cli.svg
267[npm-badge-url]: https://www.npmjs.com/package/@angular/cli
268[license-url]: https://github.com/angular/angular-cli/blob/master/LICENSE
269