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