diff --git a/public/docs/_examples/quickstart/ts/app/app.module.ts b/public/docs/_examples/quickstart/ts/app/app.module.ts index b4fc185c24..cd9673617d 100644 --- a/public/docs/_examples/quickstart/ts/app/app.module.ts +++ b/public/docs/_examples/quickstart/ts/app/app.module.ts @@ -2,11 +2,7 @@ import { NgModule } from '@angular/core'; import { BrowserModule } from '@angular/platform-browser'; -import { AppComponent } from './app.component'; - @NgModule({ - imports: [ BrowserModule ], - declarations: [ AppComponent ], - bootstrap: [ AppComponent ] + imports: [ BrowserModule ] }) export class AppModule { } diff --git a/public/docs/_examples/quickstart/ts/app/app.module2.ts b/public/docs/_examples/quickstart/ts/app/app.module2.ts new file mode 100644 index 0000000000..556d3e69b9 --- /dev/null +++ b/public/docs/_examples/quickstart/ts/app/app.module2.ts @@ -0,0 +1,12 @@ +// #docregion +import { NgModule } from '@angular/core'; +import { BrowserModule } from '@angular/platform-browser'; +import { AppComponent} from './app.component' + +@NgModule({ + imports: [ BrowserModule ], + declarations: [ AppComponent ], + bootstrap: [ AppComponent ] +}) + +export class AppModule { } diff --git a/public/docs/_examples/quickstart/ts/app/main.ts b/public/docs/_examples/quickstart/ts/app/main.ts index 4ad787ebfd..e36de73708 100644 --- a/public/docs/_examples/quickstart/ts/app/main.ts +++ b/public/docs/_examples/quickstart/ts/app/main.ts @@ -5,4 +5,5 @@ import { platformBrowserDynamic } from '@angular/platform-browser-dynamic'; import { AppModule } from './app.module'; // #enddocregion import -platformBrowserDynamic().bootstrapModule(AppModule); +const platform = platformBrowserDynamic(); +platform.bootstrapModule(AppModule); diff --git a/public/docs/ts/latest/_data.json b/public/docs/ts/latest/_data.json index c774c59ca0..ad5f75d32f 100644 --- a/public/docs/ts/latest/_data.json +++ b/public/docs/ts/latest/_data.json @@ -15,7 +15,7 @@ "quickstart": { "icon": "query-builder", - "title": "5 Min Quickstart", + "title": "Quickstart", "description": "Get up and running with Angular 2" }, diff --git a/public/docs/ts/latest/index.jade b/public/docs/ts/latest/index.jade index ef50209c3e..fe6c8a9e6c 100644 --- a/public/docs/ts/latest/index.jade +++ b/public/docs/ts/latest/index.jade @@ -3,7 +3,7 @@ div.card-row.docs-landing.layout-align-space-around-center.layout-row.flex md-card.card md-card-content.layout-align-space-between-center.layout-column.flex div - h2.text-headline.text-uppercase 5 Minute Quickstart + h2.text-headline.text-uppercase Quickstart p A short beginner guide explaining the basic concepts of Angular footer diff --git a/public/docs/ts/latest/quickstart.jade b/public/docs/ts/latest/quickstart.jade index 20ff1a90b7..fc1529d8f5 100644 --- a/public/docs/ts/latest/quickstart.jade +++ b/public/docs/ts/latest/quickstart.jade @@ -1,133 +1,122 @@ block includes include _util-fns - var _Install = 'Install' - - var _prereq = 'Node.js' + - var _prereq = 'Node.js and npm' - var _angular_browser_uri = '@angular/platform-browser-dynamic' - var _angular_core_uri = '@angular/core' - - var _stepInit = 4 // Step # after NgModule step + - var _stepInit = 3 // Step # after NgModule step - var _quickstartSrcURL='https://github.com/angular/quickstart/blob/master/README.md' //- TS/Dart shared step counter - var step = _stepInit :marked - Our QuickStart goal is to build and run a super-simple - Angular 2 application in #{_Lang}, and - establish a development environment for the remaining documentation samples - that also can be the foundation for real world applications. + This QuickStart guide demonstrates how to build and run a simple Angular 2 application in #{_Lang}. + It also establishes a common development environment used throughout the code examples in these + guides. .callout.is-helpful header Don't want #{_Lang}? p. - Although we're getting started in #{_Lang}, you can also write Angular 2 apps - in #{_docsFor == 'ts' ? 'Dart' : 'TypeScript'} and JavaScript. - Just select either of those languages from the combo-box in the banner. + Although you're getting started in #{_Lang}, you can also write Angular 2 applications + in JavaScript and #{_docsFor == 'ts' ? 'Dart' : 'TypeScript'}. Use the language selector in the + banner to switch development languages for this guide. +.l-main-section +h1 Overview + +aside.is-right + :marked + The live example link opens the finished application in + Plunker so that you can interact + with the code. You'll find live examples at the start of most sections. :marked - # Try it! - - Try the which loads the sample app - - in plunker - - and displays the simple message: + The QuickStart application has the structure of a real-world Angular application and + displays the simple message: figure.image-display img(src='/resources/images/devguide/quickstart/my-first-app.png' alt="Output of QuickStart app") :marked - # Build this app! + **Try it out**. Here's a link to a . - - [Prerequisite](#prereq): Install #{_prereq} - - [Step 1](#create-and-configure): Create the app’s project folder and - define package dependencies and special project setup - - [Step 2](#root-component): Create the app’s Angular root component -
  • [Step 3](#ngmodule): Create an Angular Module
    • - - [Step !{step++}](#main): Add main.ts, identifying the root component to Angular - - [Step !{step++}](#index): Add `index.html`, the web page that hosts the application - - [Step !{step++}](#build-and-run): Build and run the app - - [Make some changes to the app](#make-some-changes) - - [Wrap up](#wrap-up) + You can also + clone the entire QuickStart application from GitHub. + +h2 Build this application! + +:marked + - [Prerequisite](#prereq): Install #{_prereq}. + - [Step 1](#create-and-configure): Create and configure the project. +
  • [Step 2](#ngmodule): Create your application.
    • + - [Step !{step++}](#root-component): Create a component and add it to your application. + - [Step !{step++}](#main): Start up your application. + - [Step !{step++}](#index): Define the web page that hosts the application. + - [Step !{step++}](#build-and-run): Build and run the application. + - [Step !{step++}](#make-changes): Make some live changes. + - [Wrap up and Next Steps](#wrap-up) - var step = _stepInit // reinitialize step counter for headers to come + .l-main-section#prereq -h2 Prerequisite: #{_prereq} +h1 Prerequisite: Install #{_prereq} block setup-tooling :marked - Install **[Node.js® and npm](https://nodejs.org/en/download/)** - if they are not already on your machine. - .l-sub-section - :marked - **Verify that you are running at least node `v4.x.x` and npm `3.x.x`** - by running `node -v` and `npm -v` in a terminal/console window. - Older versions produce errors. + If Node.js and npm aren't already on your machine, install them. Our examples require node **v5.x.x** or higher and + npm **3.x.x** or higher. To check which version you are using, run `node -v` and `npm -v` + in a terminal window. + +aside.is-right + :marked + To easily copy text from a code example, click the *Copy to Clipboard* icon (content_copy ) in the upper right corner of + the example box. .l-main-section -.callout.is-helpful - header Download the source - :marked - Instead of following each step of these instructions, we can - [download the QuickStart source](!{_quickstartSrcURL}) - from GitHub and follow its brief instructions. +h1#create-and-configure Step 1: Create and configure the project -.l-main-section -button(class="verbose off md-primary md-button md-ink-ripple", type="button", onclick="verbose(false)"). - Hide explanations -button(class="verbose on md-primary md-button md-ink-ripple", type="button", onclick="verbose(true)"). - View explanations -.l-verbose-section - :marked - *Explanations* describe the concepts and reasons behind the instructions. - Explanations have a thin border on the left like *this* block of text. +- var _package_and_config_files = _docsFor == 'dart' ? 'pubspec.yaml' : 'configuration files' - Click *Hide Explanations* to show only the instructions. - Click *View Explanations* to see everything again. - -.l-sub-section - :marked - We'll see many code blocks as we build the QuickStart app. They're all easy to copy and paste: - code-example(format="nocode"). - Click the glyph on the right to copy code snippets to the clipboard ==> - -- var _package_and_config_files = _docsFor == 'dart' ? 'pubspec.yaml' : 'package definition and configuration files' - -.l-main-section#create-and-configure :marked - ## Step 1: Create and configure the project + In this step you will: + * [Create the project folder](#create-the-project-folder) + * [Create #{_package_and_config_files}](#add-config-files) + * [#{_Install} packages](#install-packages) - In this step we: - * [(a) Create the project folder](#create-the-project-folder) - * [(b) Add #{_package_and_config_files}](#add-config-files) - * [(c) #{_Install} packages](#install-packages) - - ### (a) Create the project folder +h2 Create the project folder +:marked + Using a terminal window, create a directory for the project, and change into this + directory. - var _ = _docsFor == 'dart' ? '_' : '-'; code-example(language="sh"). mkdir angular2!{_}quickstart cd angular2!{_}quickstart -h3#add-config-files (b) Add #{_package_and_config_files} +h2#add-config-files Create #{_package_and_config_files} block package-and-config-files - var _tsconfigUri = 'guide/typescript-configuration.html#tsconfig' - - var _typingsUri = 'guide/typescript-configuration.html#!#typings' - p Add the following package definition and configuration files to the project folder: + p Our typical Angular project needs several configuration files: ul li. - #[b package.json] lists packages the QuickStart app depends on and - defines some useful scripts. - See #[a(href="guide/npm-packages.html") Npm Package Configuration] for details. + #[b package.json] identifies npm package dependencies for the project. li. - #[b tsconfig.json] is the TypeScript compiler configuration file. - See #[a(href="#{_tsconfigUri}") TypeScript Configuration] for details. + #[b tsconfig.json] defines how the TypeScript compiler generates JavaScript from the project's + files. li. - #[b typings.json] identifies TypeScript definition files. - See #[a(href="#{_typingsUri}") TypeScript Configuration] for details. + #[b typings.json] provides additional definition files for libraries that the TypeScript + compiler doesn't natively recognize. li. - #[b systemjs.config.js], the SystemJS configuration file. - See discussion #[a(href="#systemjs") below]. + #[b systemjs.config.js] provides information to a module loader about where to find + application modules, and registers all the necessary packages. It also + contains other packages that will be needed by later documentation examples. + + p. + Create each of these files in your project directory. Populate them by pasting in text from + the tabs in the example box below. a#config-files +makeTabs(` @@ -142,82 +131,95 @@ block package-and-config-files systemjs.config.js `) -h3#install-packages (c) #{_Install} packages + p. + Learn more about these configuration files in the + #[a(href="guide/npm-packages.html") Npm Package Configuration] guide and the + #[a(href="#{_tsconfigUri}") TypeScript Configuration] guide. + A detailed discussion of module loading is beyond the scope of this guide. + + .callout.is-helpful + header SystemJS or Webpack? + p. + Although we use SystemJS for illustrative purposes here, it's only one option for loading + modules. Use the module loader that you prefer. For Webpack and Angular, see + Webpack: an Introduction. Or, learn more about SystemJS configuration in general here. + + + h2#install-packages #{_Install} packages block install-packages :marked - We install the packages listed in `package.json` using `npm`. Enter the - following command in a terminal window (command window in Windows): + Using npm from the command line, install the packages listed in `package.json` with the command: code-example(language="sh"). npm install - .l-sub-section - :marked - The `typings` folder could not show up after `npm install`. If so, please install them manually. + :marked + Error messages—in red—might appear during the install, and you might see `npm WARN` messages. As long as there are no `npm ERR!` messages at the end, you can assume success. - code-example(language="sh"). + :marked + You should now have the following structure: + + .filetree + .file angular2-quickstart + .children + .file node_modules ... + .file typings ... + .file package.json + .file systemjs.config.js + .file tsconfig.json + .file typings.json + + + :marked + If the `typings` folder doesn't show up after running `npm install`, you'll need to install it manually with the command: + + code-example(language="sh"). npm run typings install - .alert.is-important - :marked - Scary error messages in red may appear **during** install. - The install typically recovers from these errors and finishes successfully. - .l-verbose-section(class="l-verbose-inherit") - :marked - #### npm errors and warnings - - All is well if there are no console messages starting with `npm ERR!` *at the end* of **npm install**. - There might be a few `npm WARN` messages along the way — and that is perfectly fine. - - We often see an `npm WARN` message after a series of `gyp ERR!` messages. - Ignore them. A package may try to recompile itself using `node-gyp`. - If the recompile fails, the package recovers (typically with a pre-built version) - and everything works. - - Just make sure there are no `npm ERR!` messages at the end of `npm install`. - - .l-verbose-section - :marked - #### Adding the libraries and packages we need with *npm* - Angular application developers rely on the _[npm](https://docs.npmjs.com)_ - package manager to install the libraries and packages their apps require. - The Angular team recommends the starter-set of packages specified in the - `dependencies` and `devDependencies` sections. - See the [npm packages](guide/npm-packages.html) chapter for details. - - #### Helpful scripts - We've included a number of npm scripts in our suggested `package.json` to handle common development tasks: - +makeJson('quickstart/ts/package.1.json',{ paths: 'scripts'}, 'package.json (scripts)')(format=".") - - :marked - We execute most npm scripts in the following way: `npm run` followed by a *script-name*. - Some commands (such as `start`) don't require the `run` keyword. - - Here's what these scripts do: - - * `npm start` - runs the compiler and a server at the same time, both in "watch mode" - - * `npm run tsc` - runs the TypeScript compiler once - - * `npm run tsc:w` - runs the TypeScript compiler in watch mode; - the process keeps running, awaiting changes to TypeScript files and recompiling when it sees them - - * `npm run lite` - runs the lite-server, - a light-weight, static file server with excellent support for Angular apps that use routing - - * `npm run typings` - runs the [*typings* tool](#{_typingsUri}) separately - - * `npm run postinstall` - called by *npm* automatically *after* it successfully completes package installation. - This script installs the [TypeScript definition files](#{_typingsUri}) defined in `typings.json` - :marked - **We're all set.** Let's write some code. + You're now ready to write some code! ++ifDocsFor('ts') + .l-main-section + h1#ngmodule Step 2: Create your application + :marked + You compose Angular applications into closely related blocks of functionality with + [NgModules](guide/ngmodule.html). Angular itself is split into separate Angular Modules. This + makes it possible for you to keep payload size small by only importing the parts of Angular + that your application needs. -.l-main-section#root-component + Every Angular application has at least one module: the _root module_, named `AppModule` here. + + Create the file `app/app.module.ts` with the following content: + + +makeExample('app/app.module.ts')(format='.') + + :marked + This is the entry point to your application. + + Since the QuickStart application is a web application that runs in a browser, your root module + needs to import the + [`BrowserModule`](../latest/api/platform-browser/index/BrowserModule-class.html) + from `@angular/platform-browser` to the `imports` array. + + This is the smallest amount of Angular that is needed for a minimal application to run in the + browser. + + The QuickStart application doesn't do anything else, so you don't need any other modules. In a real + application, you'd likely import [`FormsModule`](../latest/api/forms/index/FormsModule-class + .html) as well as [`RouterModule`](../latest/api/router/index/RouterModule-class.html) and + [`HttpModule`](../latest/api/http/index/HttpModule-class.html). These are introduced in the + [Tour of Heroes Tutorial](../tutorial/). + + +.l-main-section +h1#root-component Step !{step++}: Create a component and add it to your application :marked - ## Step 2: Our first Angular component + Every Angular application has at least one component: the _root component_, named `AppComponent` + here. - Let's create a folder to hold our application and add a super-simple Angular component. + Components are the basic building blocks of Angular applications. A component controls a portion + of the screen—a *view*—through its associated template **Create #{_an} #{_appDir} subfolder** off the project root directory: @@ -231,295 +233,92 @@ p. +makeExample('app/app.component.ts') -.l-verbose-section - :marked - ### AppComponent is the root of the application +:marked + The QuickStart application has the same essential structure as any other Angular component: - Every Angular app has at least one **root component**, conventionally named `AppComponent`, - that hosts the client user experience. - Components are the basic building blocks of Angular applications. - A component controls a portion of the screen — a *view* — through its associated template. + * **An import statement**. Importing gives your component access to + Angular's core [`@Component` decorator function](../latest/api/core/index/Component-decorator + .html). + * **A @Component #{_decorator}** that associates *metadata* with the + `AppComponent` component class: - This QuickStart has only one, extremely simple component. - But it has the essential structure of every component we'll ever write: + - a *selector* that specifies a simple CSS selector for an HTML element that represents + the component + - a *template* that tells Angular how to render the component's view. + * **A component class** that controls the appearance and behavior of a view + through its template. Here, you only have the root component, `AppComponent`. Since you don't + need any application logic in the simple QuickStart example, it's empty. - * One or more [import](#component-import) - statements to reference the things we need. - * A [@Component #{_decorator}](#component-decorator) - that tells Angular what template to use and how to create the component. - * A [component class](#component-class) - that controls the appearance and behavior of a view through its template. + You *export* the `AppComponent` class so that you can *import* it into the application that you + just created. - a#component-import - :marked - ### Import + Edit the file `app/app.module.ts` to import your new `AppComponent` and add it in the + declarations and bootstrap fields in the `NgModule` decorator: - Angular apps are modular. They consist of many files each dedicated to a purpose. - Angular itself is modular. It is a collection of library modules - each made up of several, related features that we'll use to build our application. - - When we need something from a module or library, we import it. - Here we import the Angular 2 core so that our component code can have access to - the `@Component` #{_decorator}. - - +makeExcerpt('app/app.component.ts', 'import') - - h3#component-decorator @Component #{_decorator} - +ifDocsFor('ts') - :marked - `Component` is a *decorator function* that takes a *metadata object* as argument. - We apply this function to the component class by prefixing the function with the - **@** symbol and invoking it with a metadata object, just above the class. - :marked - `@Component` is #{_a} *#{_decorator}* that allows us to associate *metadata* with the - component class. - The metadata tells Angular how to create and use this component. - - +makeExcerpt('app/app.component.ts', 'metadata') - - block annotation-fields - :marked - This particular metadata object has two fields, a `selector` and a `template`. - :marked - The **selector** specifies a simple CSS selector for an HTML element that represents the component. - - >The element for this component is named `my-app`. - Angular creates and displays an instance of our `AppComponent` - wherever it encounters a `my-app` element in the host HTML. - - The **template** specifies the component's companion template, - written in an enhanced form of HTML that tells Angular how to render this component's view. - - >Our template is a single line of HTML announcing "*My First Angular 2 App*". - - >A more advanced template could contain data bindings to component properties - and might identify other application components which have their own templates. - These templates might identify yet other components. - In this way an Angular application becomes a tree of components. - - :marked - ### Component class - At the bottom of the file is an empty, do-nothing class named `AppComponent`. - +makeExcerpt('app/app.component.ts', 'class') - :marked - When we're ready to build a substantive application, - we can expand this class with properties and application logic. - Our `AppComponent` class is empty because we don't need it to do anything in this QuickStart. - +ifDocsFor('ts') - :marked - We **export** `AppComponent` so that we can **import** it elsewhere in our application, - as we'll see when we create `app.module.ts`. - -+ifDocsFor('ts') - .l-main-section#ngmodule - :marked - ## Step 3: Our own `app.module.ts` - - We compose Angular apps into closely related blocks of functionality with [Angular Modules](guide/ngmodule.html). - Every app requires at least one module, the _root module_, that we call `AppModule` by convention. - - Create the file `app/app.module.ts` with the following content: - - +makeExample('app/app.module.ts')(format='.') - - .l-verbose-section - :marked - We're passing metadata to the `NgModule` decorator function: - - 1. `imports` - the _other_ modules that export material we need in _this_ module. - Almost every application's _root module_ should import the `BrowserModule`. - - 1. `declarations` - components and directives that belong to _this_ module. - - 1. `bootstrap` - identifies the _root component_ that Angular should _bootstrap_ when it starts the application. - - We import our lone `app.component.ts` and add it to both the `declarations` and `bootstrap` arrays. - - ### Angular Modules import other modules - Notice that we also add the `BrowserModule` from `@angular/platform-browser` to the `imports` array. - This is the Angular Module that contains all the needed Angular bits and pieces to run our app in the browser. - - Angular itself is split into separate Angular Modules so we only need to import the ones we really use. - - One of the most common ones is `FormsModule`, and soon we'll also see `RouterModule` and `HttpModule`. ++makeExample('app/app.module2.ts', null, title='app/app.module.ts') .l-main-section -h2#main Step !{step++}: Add #[code #[+adjExPath('main.ts')]] +h1#main Step !{step++}: Start up your application block create-main :marked - Now we need something to tell Angular to load the app module. + Now you need to tell Angular to start up your application. + Create the file `app/main.ts` with the following content: +makeExample('app/main.ts') + - var _pBD_bootstrapModule = _docsFor == 'dart' ? _bootstrapModule : 'platformBrowserDynamic().bootstrapModule' -.l-verbose-section + +:marked + This code initializes the platform that your application runs in, then uses the platform to + bootstrap your `!{_AppModuleVsAppComp}`. + + ### Why create separate *main.ts*, app module and app component files? + + App bootstrapping is a separate concern from creating a module or + presenting a view. Testing the component is much easier if it doesn't also try to run the entire application. + + +.callout.is-helpful + header Bootstrapping is platform-specific + :marked - We import the two things we need to launch the application: - - 1. Angular's browser `!{_platformBrowserDynamicVsBootStrap}` function - 1. The application !{_moduleVsRootComp}, `!{_AppModuleVsAppComp}`. - - Then we call `!{_pBD_bootstrapModule}` with `!{_AppModuleVsAppComp}`. - - ### Bootstrapping is platform-specific - - Notice that we import the `!{_platformBrowserDynamicVsBootStrap}` function - from `#{_angular_browser_uri}`, not `#{_angular_core_uri}`. - Bootstrapping isn't core because there isn't a single way to bootstrap the app. - True, most applications that run in a browser call the bootstrap function from - this library. - - But it is possible to load a !{_moduleVsComp} in a different environment. - We might load it on a mobile device with [Apache Cordova](https://cordova.apache.org/) or [NativeScript](https://www.nativescript.org/). - We might wish to render the first page of our application on the server - to improve launch performance or facilitate - [SEO](http://www.google.com/webmasters/docs/search-engine-optimization-starter-guide.pdf). - These targets require a different kind of bootstrap function that we'd import from a different library. - - ### Why create separate *main.ts*, app module and app component files? - - Then main.ts, app module - and the app component files are tiny. - This is just a QuickStart. - We could have merged these files into one and spared ourselves some complexity. - - We'd rather demonstrate the proper way to structure an Angular application. - App bootstrapping is a separate concern from creating a module or - presenting a view. - Mixing concerns creates difficulties down the road. - We might launch the `!{_AppModuleVsAppComp}` in multiple environments with different bootstrappers. - Testing the component is much easier if it doesn't also try to run the entire application. - Let's make the small extra effort to do it *the right way*. + Because the QuickStart application runs directly in the browser, `main.ts` imports the + `!{_platformBrowserDynamicVsBootStrap}` function from `#{_angular_browser_uri}`, not + `#{_angular_core_uri}`. On a mobile device, you might load a !{_moduleVsComp} with + [Apache Cordova](https://cordova.apache.org/) or + [NativeScript](https://www.nativescript.org/), using a bootstrap function that's specific + to that platform. .l-main-section -h2#index Step !{step++}: Add #[code index.html] +h1#index Step !{step++}: Define the web page that hosts the application :marked - In the *#{_indexHtmlDir}* folder + In the *#{_indexHtmlDir}* folder, create an `index.html` file and paste the following lines into it: +makeExample('index.html') -.l-verbose-section - :marked - The `index.html` file defines the web page that hosts the application. - +ifDocsFor('ts') - :marked - The noteworthy sections of HTML are: ++ifDocsFor('ts') +:marked + The noteworthy sections here are: - 1. The JavaScript [libraries](#libraries) - 2. Configuration file for [SystemJS](#systemjs), and a script - where we import and run the `app` module which refers to the `main` file that we just wrote. - 3. The [``](#my-app) tag in the `` which is *where our app lives!* + * JavaScript libraries: `core-js` polyfills for older browsers, the `zone.js` and + `reflect-metadata` libraries needed by Angular, and the `SystemJS` library for module loading. + * Configuration file for `SystemJS`, and a script + where you import and run the `app` module which refers to the `main` file that you just + wrote. + * The [``](#my-app) tag in the `` which is *where your app lives!* - :marked - ### Libraries - We loaded the following scripts - +makeExcerpt('index.html', 'libraries') - :marked - We begin with `core-js`'s ES2015/ES6 shim which monkey patches the global context (window) with essential features of ES2015 (ES6). - Next are the polyfills for Angular2, `zone.js` and `reflect-metadata`. - Then the [SystemJS](#systemjs) library for module loading. - - We'll make different choices as we gain experience and - become more concerned about production qualities such as - load times and memory footprint. - - h3#systemjs SystemJS - :marked - QuickStart uses SystemJS - to load application and library modules. [Earlier](#add-config-files) we - added the `systemjs.config.js` file to the project root. - There are alternatives that work just fine including the well-regarded - [webpack](guide/webpack.html). - SystemJS happens to be a good choice. - But we want to be clear that it was a *choice* and not a *preference*. - - All module loaders require configuration and all loader configuration - becomes complicated rather quickly as soon as the file structure diversifies and - we start thinking about building for production and performance. - - We suggest becoming well-versed in the loader of your choice. - Learn more about SystemJS configuration - here. - - With those cautions in mind, what are we doing in the - QuickStart [`systemjs.config.js` configuration file we added earlier](#config-files)? - First, we create a map to tell SystemJS where to look when we import some module. - Then, we register all our packages to SystemJS: - all the project dependencies and our application package, `app`. - - .l-sub-section - :marked - Our QuickStart doesn't use all of the listed packages - but any substantial application will want many of them - and all of the listed packages are required by at least one of the documentation samples. - - There is no runtime harm in listing packages that we don't need as they will only be loaded when requested. - :marked - The `app` package tells SystemJS what to do when it sees a request for a - module from the `app/` folder. - - Our QuickStart makes such requests when one of its - application TypeScript files has an import statement like this: - +makeExcerpt('app/main.ts', 'import') - :marked - Notice that the module name (after `from`) does not mention a filename extension. - In the configuration we tell SystemJS to default the extension to `js`, a JavaScript file. - - That makes sense because we transpile TypeScript to JavaScript - *before* running the application. - - .l-sub-section - :marked - #### Transpiling in the browser - In the live example on plunker we transpile (AKA compile) to JavaScript in the browser - on the fly. _That's fine for a demo_. - - **Do not transpile in the browser during development or for production**. - - We strongly recommend transpiling (AKA compiling) to JavaScript during a build phase - before running the application for several reasons including: - - * We see compiler warnings and errors that are hidden from us in the browser. - - * Precompilation simplifies the module loading process and - it's much easier to diagnose problems when this is a separate, external step. - - * Precompilation means a faster user experience because the browser doesn't waste time compiling. - - * We iterate development faster because we only recompile changed files. - We notice the difference as soon as the app grows beyond a handful of files. - - * Precompilation fits into a continuous integration process of build, test, deploy. - - :marked - The `System.import` call tells SystemJS to import the `main` file - (`main.js` ... after transpiling `main.ts`, remember?); - `main` is where we tell Angular to launch the application. - We also catch and log launch errors to the console. - - All other modules are loaded upon request - either by an import statement or by Angular itself. - - ### *<my-app>* - - a#my-app - :marked - When Angular calls the `!{_bootstrapModule}` function in main.ts, - it reads the `!{_AppModuleVsAppComp}` metadata, sees that - `AppComponent` is the bootstrap component, - finds the `my-app` selector, locates an element tag named `my-app`, - and renders our application's view between those tags. :marked - ### Add some style - Styles aren't essential but they're nice, and `index.html` assumes we have + ## Add some style + Styles aren't essential, but they're nice, and `index.html` assumes that you have a stylesheet called `styles.css`. - Create a `styles.css` file in the *#{_indexHtmlDir}* folder and start styling, + Create a `styles.css` file in the *#{_indexHtmlDir}* folder, and start styling, perhaps with the minimal styles shown below. +makeExcerpt('styles.css (excerpt)', 'quickstart') @@ -530,47 +329,48 @@ h2#index Step !{step++}: Add #[code index.html] see [styles.css](https://github.com/angular/angular.io/blob/master/public/docs/_examples/styles.css). .l-main-section#build-and-run -h2 Step !{step++}: Build and run the app! +h1 Step !{step++}: Build and run the application block run-app :marked Open a terminal window and enter this command: code-example. npm start +aside.is-right :marked - That command runs two parallel node processes - 1. The TypeScript compiler in watch mode - 1. A static server called **lite-server** that loads `index.html` in a browser - and refreshes the browser when application files change + [Read more](https://github.com/angular/quickstart/blob/master/README.md#npm-scripts) about + other useful npm scripts included in this example's `package.json`. - In a few moments, a browser tab should open and display +:marked + That command runs the following two parallel node processes: + * The TypeScript compiler in watch mode + * A static server called _lite-server_ that loads `index.html` in a browser + and refreshes the browser when application files change + + In a few moments, a browser tab should open and display the following: figure.image-display img(src='/resources/images/devguide/quickstart/my-first-app.png' alt="Output of QuickStart app") -:marked - **Great job!** block build-app //- Nothing for ts. +.l-main-section#make-changes +h1 Step !{step++}: Make some live changes :marked - ## Make some changes - - Try changing the message to "My SECOND Angular 2 app". + Try changing the message in `app/app.component.ts` to "My SECOND Angular 2 App". block server-watching :marked - The TypeScript compiler and `lite-server` are watching. - They should detect the change, recompile the TypeScript into JavaScript, - refresh the browser, and display the revised message. - It's a nifty way to develop an application! + The TypeScript compiler and `lite-server` will detect your change, recompile the TypeScript into JavaScript, + refresh the browser, and display your revised message. - We close the terminal window when we're done to terminate both the compiler and the server. + + Close the terminal window when you're done to terminate both the compiler and the server. .l-main-section +h1#wrap-up Wrap up and next steps :marked - # Wrap up - - Our final project folder structure looks like this: + The final project folder structure looks like this: block project-file-structure .filetree .file angular2-quickstart @@ -589,48 +389,22 @@ block project-file-structure .file tsconfig.json .file typings.json :marked - Here are the file contents: - -block project-files - +makeTabs(` - quickstart/ts/app/app.component.ts, - quickstart/ts/app/app.module.ts, - quickstart/ts/app/main.ts, - quickstart/ts/index.html, - quickstart/ts/package.1.json, - quickstart/ts/tsconfig.1.json, - quickstart/ts/typings.1.json, - quickstart/ts/styles.css, - quickstart/ts/systemjs.config.1.js` - , - ',,,,,,, quickstart,', - `app/app.component.ts, - app/app.module.ts, - app/main.ts, - index.html, - package.json, - tsconfig.json, - typings.json, - styles.css (excerpt), - systemjs.config.js`) + To see the file contents, open the . .l-main-section :marked ## What next? - Our first application doesn't do much. It's basically "Hello, World" for Angular 2. + This first application doesn't do much. It's basically "Hello, World" for Angular 2. - We kept it simple in our first pass: we wrote a little Angular component, - created a simple `index.html`, and launched with a - static file server. That's about all we'd expect to do for a "Hello, World" app. + You wrote a little Angular component, created a simple `index.html`, and launched with a + static file server. - **We have greater ambitions!** +ifDocsFor('ts') :marked - The good news is that the overhead of setup is (mostly) behind us. - We'll probably only touch the `package.json` to update libraries. - We'll likely open `index.html` only if we need to add a library or some css stylesheets. + You also created the basic application setup that you'll re-use for other + sections in this guide. From here, the changes you'll make in the + `package.json` or `index.html` files are only minor updates to add libraries or some css + stylesheets. You also won't need to revisit module loading again. :marked - We're about to take the next step and build a small application that - demonstrates the great things we can build with Angular 2. - - Join us on the [Tour of Heroes Tutorial](./tutorial)! + To take the next step and build a small application that demonstrates real features that you can + build with Angular, carry on to the [Tour of Heroes tutorial](./tutorial)! diff --git a/public/resources/images/devguide/quickstart/my-first-app.png b/public/resources/images/devguide/quickstart/my-first-app.png index 0b40ec2ab0..fb38d08425 100644 Binary files a/public/resources/images/devguide/quickstart/my-first-app.png and b/public/resources/images/devguide/quickstart/my-first-app.png differ