|
1 |
| -## Angular CLI |
| 1 | +# Angular CLI - The CLI tool for Angular. |
2 | 2 |
|
3 |
| -<!-- Badges section here. --> |
| 3 | +The sources for this package are in the [Angular CLI](https://github.com/angular/angular-cli) repository. Please file issues and pull requests against that repository. |
4 | 4 |
|
5 |
| -[![Dependency Status][david-badge]][david-badge-url] |
6 |
| -[![devDependency Status][david-dev-badge]][david-dev-badge-url] |
7 |
| - |
8 |
| -[][npm-badge-url] |
9 |
| -[][npm-badge-url] |
10 |
| -[][license-url] |
11 |
| -[][npm-badge-url] |
12 |
| - |
13 |
| -[](https://gitter.im/angular/angular-cli?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) |
14 |
| - |
15 |
| -[](https://github.com/angular/angular-cli/fork) |
16 |
| -[](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/ [email protected] |
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 |
| -#### Creating a profile |
238 |
| - |
239 |
| -Node.js 16+ users can use the Node.js command line argument `--cpu-prof` to create a CPU profile. |
240 |
| - |
241 |
| -```bash |
242 |
| -node --cpu-prof node_modules/.bin/ng build |
243 |
| -``` |
244 |
| - |
245 |
| -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. |
246 |
| - |
247 |
| -#### Opening a profile |
248 |
| - |
249 |
| -You can use the Chrome Devtools to process it. To do so: |
250 |
| - |
251 |
| -1. open `chrome://inspect` in Chrome |
252 |
| -1. click on "Open dedicated DevTools for Node" |
253 |
| -1. go to the "profiler" tab |
254 |
| -1. click on the "Load" button and select the generated `.cpuprofile` file |
255 |
| -1. on the left panel, select the associated file |
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 |
| 5 | +Usage information and reference details can be found in repository [README](../../../README.md) file. |
0 commit comments