[6a3a178] | 1 | ## Angular CLI
|
---|
| 2 |
|
---|
| 3 | <!-- Badges section here. -->
|
---|
| 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
|
---|