Skip to content

Commit 687f224

Browse files
alan-agius4dgp1130
alan-agius4
authored and
dgp1130
committed
docs(@angular/cli): update @angular/cli package readme
Previously, the `@angular/cli` readme contained a lot of un-needed information for application users (cherry picked from commit fafb9dd)
1 parent c8826a9 commit 687f224

File tree

2 files changed

+50
-271
lines changed

2 files changed

+50
-271
lines changed

‎docs/DEVELOPER.md

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -110,6 +110,53 @@ wait forever for a debugger to attach).
110110

111111
![Intellij IDEA run configurations](images/run-configurations.png)
112112

113+
### VS Code
114+
115+
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:
116+
117+
```json
118+
{
119+
"type": "node",
120+
"request": "launch",
121+
"name": "ng serve",
122+
"cwd": "<path to an Angular project generated with Angular-CLI>",
123+
"program": "${workspaceFolder}/dist/@angular/cli/bin/ng",
124+
"args": [
125+
"<ng command>",
126+
...other arguments
127+
],
128+
"console": "integratedTerminal"
129+
}
130+
```
131+
132+
Then you can add breakpoints in `dist/@angular` files.
133+
134+
For more informations about Node.js debugging in VS Code, see the related [VS Code Documentation](https://code.visualstudio.com/docs/nodejs/nodejs-debugging).
135+
136+
## CPU Profiling
137+
138+
In order to investigate performance issues, CPU profiling is often useful.
139+
140+
### Creating a profile
141+
142+
Node.js 16+ users can use the Node.js command line argument `--cpu-prof` to create a CPU profile.
143+
144+
```bash
145+
node --cpu-prof node_modules/.bin/ng build
146+
```
147+
148+
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.
149+
150+
#### Opening a profile
151+
152+
You can use the Chrome Devtools to process it. To do so:
153+
154+
1. open `chrome://inspect` in Chrome
155+
1. click on "Open dedicated DevTools for Node"
156+
1. go to the "profiler" tab
157+
1. click on the "Load" button and select the generated `.cpuprofile` file
158+
1. on the left panel, select the associated file
159+
113160
## Creating New Packages
114161

115162
Adding a package to this repository means running two separate commands:

‎packages/angular/cli/README.md

Lines changed: 3 additions & 271 deletions
Original file line numberDiff line numberDiff line change
@@ -1,273 +1,5 @@
1-
## Angular CLI
1+
# Angular CLI - The CLI tool for Angular.
22

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.
44

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/[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

Comments
 (0)