diff --git a/aio/content/examples/cli-quickstart/src/app/app.component.ts b/aio/content/examples/cli-quickstart/src/app/app.component.ts index d977bbe40a..1c462d321b 100644 --- a/aio/content/examples/cli-quickstart/src/app/app.component.ts +++ b/aio/content/examples/cli-quickstart/src/app/app.component.ts @@ -2,7 +2,7 @@ import { Component } from '@angular/core'; // #enddocregion import -// #docregion metadata +// #docregion metadata, component @Component({ selector: 'app-root', templateUrl: './app.component.html', @@ -13,4 +13,4 @@ import { Component } from '@angular/core'; export class AppComponent { title = 'My First Angular App!'; } -// #enddocregion title, class +// #enddocregion title, class, component diff --git a/aio/content/guide/quickstart.md b/aio/content/guide/quickstart.md index 4bc09cf860..34adf96e90 100644 --- a/aio/content/guide/quickstart.md +++ b/aio/content/guide/quickstart.md @@ -1,46 +1,51 @@ -# Getting Started +# Getting started -Good tools make application development quicker and easier to maintain than -if you did everything by hand. +Welcome to Angular! Angular helps you build modern applications for the web, mobile, or desktop. -The [**Angular CLI**](https://cli.angular.io/) is a **_command line interface_** tool -that can create a project, add files, and perform a variety of ongoing development tasks such -as testing, bundling, and deployment. - -The goal in this guide is to build and run a simple Angular -application in TypeScript, using the Angular CLI -while adhering to the [Style Guide](guide/styleguide) recommendations that +This guide shows you how to build and run a simple Angular +app. You'll use the [Angular CLI tool](cli "CLI command reference") to accelerate development, +while adhering to the [Style Guide](guide/styleguide "Angular style guide") recommendations that benefit _every_ Angular project. -By the end of the chapter, you'll have a basic understanding of development with the CLI -and a foundation for both these documentation samples and for real world applications. - -And you can also download the example. - -

- Step 1. Set up the Development Environment -

+This guide takes less than 30 minutes to complete. +At the end of this guide—as part of final code review—there is a link to download a copy of the final application code. (If you don't execute the commands in this guide, you can still download the final application code.) +{@a devenv} +{@a prerequisites} +## Prerequisites -You need to set up your development environment before you can do anything. +Before you begin, make sure your development environment includes `Node.js®` and an npm package manager. -Install **[Node.js® and npm](https://nodejs.org/en/download/)** -if they are not already on your machine. +{@a nodejs} +### Node.js -
+Angular requires `Node.js` version 8.x or 10.x. + +* To check your version, run `node -v` in a terminal/console window. + +* To get `Node.js`, go to [nodejs.org](https://nodejs.org "Nodejs.org"). + +{@a npm} +### npm package manager + +Angular, the Angular CLI, and Angular apps depend on features and functionality provided by libraries that are available as [npm packages](https://docs.npmjs.com/getting-started/what-is-npm). To download and install npm packages, you must have an npm package manager. + +This Quick Start uses the [npm client](https://docs.npmjs.com/cli/install) command line interface, which is installed with `Node.js` by default. + +To check that you have the npm client installed, run `npm -v` in a terminal/console window. +{@a install-cli} -**Verify that you are running at least Node.js version `8.x` or greater and npm version `5.x` or greater** -by running `node -v` and `npm -v` in a terminal/console window. -Older versions produce errors, but newer versions are fine. +## Step 1: Install the Angular CLI -
+You use the Angular CLI +to create projects, generate application and library code, and perform a variety of ongoing development tasks such as testing, bundling, and deployment. +Install the Angular CLI globally. - -Then install the [Angular CLI](https://github.com/angular/angular-cli) globally. +To install the CLI using `npm`, open a terminal/console window and enter the following command: @@ -50,101 +55,86 @@ Then install the [Angular CLI](https://github.com/angular/angular-cli) globally. +{@a create-proj} -

- Step 2. Create a new project -

+## Step 2: Create a workspace and initial application +You develop apps in the context of an Angular [**workspace**](guide/glossary#workspace). A workspace contains the files for one or more [**projects**](guide/glossary/#project). A project is the set of files that comprise an app, a library, or end-to-end (e2e) tests. +To create a new workspace and initial app project: -Open a terminal window. +1. Run the CLI command `ng new` and provide the name `my-app`, as shown here: + + ng new my-app -Generate a new project and default app by running the following command: + +2. The `ng new` command prompts you for information about features to include in the initial app project. Accept the defaults by pressing the Enter or Return key. - - ng new my-app +The Angular CLI installs the necessary Angular npm packages and other dependencies. This can take a few minutes. - +It also creates the following workspace and starter project files: +* A new workspace, with a root folder named `my-app` +* An initial skeleton app project, also called `my-app` (in the `src` subfolder) +* An end-to-end test project (in the `e2e` subfolder) +* Related configuration files -The Angular CLI installs the necessary npm packages, creates the project files, and populates the project with a simple default app. This can take some time. +The initial app project contains a simple Welcome app, ready to run. +{@a serve} +## Step 3: Serve the application -
+Angular includes a server, so that you can easily build and serve your app locally. +1. Go to the workspace folder (`my-app`). - -You can add pre-packaged functionality to a new project by using the `ng add` command. The `ng add` command transforms a project by applying the schematics in the specified package. -For more information, see the [Angular CLI documentation.](https://github.com/angular/angular-cli/wiki/add "Angular CLI documentation") - -Angular Material provides schematics for typical app layouts. -See the [Angular Material documentation](https://material.angular.io/guides "Angular Material documentation") for details. - - -
- - -

- Step 3: Serve the application -

- - - -Go to the project directory and launch the server. - +1. Launch the server by using the CLI command `ng serve`, with the `--open` option. cd my-app ng serve --open - - The `ng serve` command launches the server, watches your files, and rebuilds the app as you make changes to those files. -Using the `--open` (or just `-o`) option will automatically open your browser -on `http://localhost:4200/`. +The `--open` (or just `-o`) option automatically opens your browser +to `http://localhost:4200/`. Your app greets you with a message:
- The app works! + Welcome to my-app!
+{@a first-component} -

- Step 4: Edit your first Angular component -

+## Step 4: Edit your first Angular component +[**_Components_**](guide/glossary#component) are the fundamental building blocks of Angular applications. +They display data on the screen, listen for user input, and take action based on that input. +As part of the initial app, the CLI created the first Angular component for you. It is the _root component_, and it is named `app-root`. -The CLI created the first Angular component for you. -This is the _root component_ and it is named `app-root`. -You can find it in `./src/app/app.component.ts`. +1. Open `./src/app/app.component.ts`. +2. Change the `title` property from `'my-app'` to `'My First Angular App'`. -Open the component file and change the `title` property from `'app'` to `'My First Angular App!'`. + + The browser reloads automatically with the revised title. That's nice, but it could look better. - - - - -The browser reloads automatically with the revised title. That's nice, but it could look better. - -Open `src/app/app.component.css` and give the component some style. - - - +3. Open `./src/app/app.component.css` and give the component some style. + +Looking good!
Output of Getting Started app @@ -152,490 +142,43 @@ Open `src/app/app.component.css` and give the component some style. -Looking good! +{@a project-file-review} +## Final code review -## What's next? -That's about all you'd expect to do in a "Hello, World" app. +You can download an example of the app that you created in this Getting Started guide. -You're ready to take the [Tour of Heroes Tutorial](tutorial) and build -a small application that demonstrates the great things you can build with Angular. - -Or you can stick around a bit longer to learn about the files in your brand new project. - - - -## Project file review - -An Angular CLI project is the foundation for both quick experiments and enterprise solutions. - -The first file you should check out is `README.md`. -It has some basic information on how to use CLI commands. -Whenever you want to know more about how Angular CLI works make sure to visit -[the Angular CLI repository](https://github.com/angular/angular-cli) and -[Wiki](https://github.com/angular/angular-cli/wiki). - -Some of the generated files might be unfamiliar to you. - - - -### The `src` folder -Your app lives in the `src` folder. -All Angular components, templates, styles, images, and anything else your app needs go here. -Any files outside of this folder are meant to support building your app. - - -
-
src
-
-
app
-
-
app.component.css
-
app.component.html
-
app.component.spec.ts
-
app.component.ts
-
app.module.ts
-
-
assets
-
-
.gitkeep
-
-
environments
-
-
environment.prod.ts
-
environment.ts
-
-
browserslist
-
favicon.ico
-
index.html
-
karma.conf.js
-
main.ts
-
polyfills.ts
-
styles.css
-
test.ts
-
tsconfig.app.json
-
tsconfig.spec.json
-
tslint.json
-
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- File - - Purpose -
- - `app/app.component.{ts,html,css,spec.ts}` - - - - Defines the `AppComponent` along with an HTML template, CSS stylesheet, and a unit test. - It is the **root** component of what will become a tree of nested components - as the application evolves. - -
- - `app/app.module.ts` - - - - Defines `AppModule`, the [root module](guide/bootstrapping "AppModule: the root module") that tells Angular how to assemble the application. - Right now it declares only the `AppComponent`. - Soon there will be more components to declare. - -
- - `assets/*` - - - - A folder where you can put images and anything else to be copied wholesale - when you build your application. - -
- - `environments/*` - - - - This folder contains one file for each of your destination environments, - each exporting simple configuration variables to use in your application. - The files are replaced on-the-fly when you build your app. - You might use a different API endpoint for development than you do for production - or maybe different analytics tokens. - You might even use some mock services. - Either way, the CLI has you covered. - -
- - `browserslist` - - - - A configuration file to share [target browsers](https://github.com/browserslist/browserslist) between different front-end tools. - -
- - `favicon.ico` - - - - Every site wants to look good on the bookmark bar. - Get started with your very own Angular icon. - -
- - `index.html` - - - - The main HTML page that is served when someone visits your site. - Most of the time you'll never need to edit it. - The CLI automatically adds all `js` and `css` files when building your app so you - never need to add any `