From b85ac0313642526b827dc4a437c0e2bcc388b67b Mon Sep 17 00:00:00 2001 From: Judy Bogart Date: Mon, 19 Aug 2019 10:23:42 -0700 Subject: [PATCH] docs(upgrade): position old setup guide as legacy until it can be removed (#32193) PR Close #32193 --- aio/content/guide/testing.md | 20 +++++-- aio/content/guide/typescript-configuration.md | 29 +++++++++- aio/content/guide/upgrade-performance.md | 2 +- .../guide/{setup.md => upgrade-setup.md} | 58 +++++-------------- aio/content/guide/upgrade.md | 7 +-- aio/content/navigation.json | 8 ++- aio/firebase.json | 1 + aio/ngsw-config.json | 2 + 8 files changed, 68 insertions(+), 59 deletions(-) rename aio/content/guide/{setup.md => upgrade-setup.md} (82%) diff --git a/aio/content/guide/testing.md b/aio/content/guide/testing.md index dca2378ada..7e15741746 100644 --- a/aio/content/guide/testing.md +++ b/aio/content/guide/testing.md @@ -1212,7 +1212,8 @@ value becomes available. The test must become _asynchronous_. #### Async test with _fakeAsync()_ -To use `fakeAsync()` functionality, you need to import `zone-testing`, for details, please read [setup guide](guide/setup#appendix-test-using-fakeasyncasync). +To use `fakeAsync()` functionality, you must import `zone.js/dist/zone-testing` in your test setup file. +If you created your project with the Angular CLI, `zone-testing` is already imported in `src/test.ts`. The following test confirms the expected behavior when the service returns an `ErrorObservable`. @@ -1231,6 +1232,13 @@ The `fakeAsync()` function enables a linear coding style by running the test bod The test body appears to be synchronous. There is no nested syntax (like a `Promise.then()`) to disrupt the flow of control. +
+ +Limitation: The `fakeAsync()` function won't work if the test body makes an `XMLHttpRequest` (XHR) call. +XHR calls within a test are rare, but if you need to call XHR, see [`async()`](#async), below. + +
+ {@a tick} #### The _tick()_ function @@ -1406,13 +1414,13 @@ Then you can assert that the quote element displays the expected text. #### Async test with _async()_ -To use `async()` functionality, you need to import `zone-testing`, for details, please read [setup guide](guide/setup#appendix-test-using-fakeasyncasync). +To use `async()` functionality, you must import `zone.js/dist/zone-testing` in your test setup file. +If you created your project with the Angular CLI, `zone-testing` is already imported in `src/test.ts`. The `fakeAsync()` utility function has a few limitations. -In particular, it won't work if the test body makes an `XHR` call. - -`XHR` calls within a test are rare so you can generally stick with `fakeAsync()`. -But if you ever do need to call `XHR`, you'll want to know about `async()`. +In particular, it won't work if the test body makes an `XMLHttpRequest` (XHR) call. +XHR calls within a test are rare so you can generally stick with [`fakeAsync()`](#fake-async). +But if you ever do need to call `XMLHttpRequest`, you'll want to know about `async()`.
diff --git a/aio/content/guide/typescript-configuration.md b/aio/content/guide/typescript-configuration.md index d56ed01ca5..b38d6a1cba 100644 --- a/aio/content/guide/typescript-configuration.md +++ b/aio/content/guide/typescript-configuration.md @@ -28,9 +28,34 @@ For details about `tsconfig.json`, see the official
-The [Setup](guide/setup-local) guide uses the following `tsconfig.json`: +The initial `tsconfig.json` for an Angular app typically looks like this example: + + + + { + "compileOnSave": false, + "compilerOptions": { + "compilerOptions": { + "baseUrl": "./", + "outDir": "./dist/out-tsc", + "sourceMap": true, + "declaration": false, + "module": "es2015", + "moduleResolution": "node", + "emitDecoratorMetadata": true, + "experimentalDecorators": true, + "importHelpers": true, + "target": "es5", + "typeRoots": [ + "node_modules/@types" + ], + "lib": [ + "es2018", + "dom" + ] + } + - This file contains options and flags that are essential for Angular applications. diff --git a/aio/content/guide/upgrade-performance.md b/aio/content/guide/upgrade-performance.md index f8089db313..f0f8274651 100644 --- a/aio/content/guide/upgrade-performance.md +++ b/aio/content/guide/upgrade-performance.md @@ -216,7 +216,7 @@ the recipe. In order to start using any `upgrade/static` APIs, you still need to load the Angular framework as you would in a normal Angular app. You can see how this can be done with SystemJS by following the -instructions in the [Setup](guide/setup) guide, selectively copying code from the +instructions in the [Upgrade Setup](guide/upgrade-setup "Setup for Upgrading from AngularJS") guide, selectively copying code from the [QuickStart github repository](https://github.com/angular/quickstart). You also need to install the `@angular/upgrade` package via `npm install @angular/upgrade --save` diff --git a/aio/content/guide/setup.md b/aio/content/guide/upgrade-setup.md similarity index 82% rename from aio/content/guide/setup.md rename to aio/content/guide/upgrade-setup.md index 26c98d7d03..a0b14fd09d 100644 --- a/aio/content/guide/setup.md +++ b/aio/content/guide/upgrade-setup.md @@ -1,15 +1,15 @@ # Setup for Upgrading from AngularJS -
-**Audience:** Use this guide **only** in the context of [Upgrading from AngularJS](guide/upgrade "Upgrading from AngularJS to Angular") or [Upgrading for Performance](guide/upgrade-performance "Upgrading for Performance"). -Those Upgrade guides refer to this Setup guide for information about using the [deprecated QuickStart GitHub repository](https://github.com/angular/quickstart "Deprecated Angular QuickStart GitHub repository"), which was created prior to the current Angular [CLI](cli "CLI Overview"). +**Audience:** Use this guide **only** in the context of [Upgrading from AngularJS](guide/upgrade "Upgrading from AngularJS to Angular") or [Upgrading for Performance](guide/upgrade-performance "Upgrading for Performance"). +Those Upgrade guides refer to this Setup guide for information about using the [deprecated QuickStart GitHub repository](https://github.com/angular/quickstart "Deprecated Angular QuickStart GitHub repository"), which was created prior to the current Angular [CLI](cli "CLI Overview"). -**For all other scenarios,** see the current instructions in [Local Environment Setup](guide/setup-local "Setting up for Local Development"). +**For all other scenarios,** see the current instructions in [Setting up the Local Environment and Workspace](guide/setup-local "Setting up for Local Development").
@@ -139,6 +139,11 @@ Consequently, there are many files in the project folder on your machine, most of which you can [learn about later](guide/file-structure). +
+ +**Reminder:** The "QuickStart seed" example was created prior to the Angular CLI, so there are some differences between what is described here and an Angular CLI application. + +
{@a app-files} @@ -265,8 +270,8 @@ The following are all in `src/` 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. + When initially created, it declares only the `AppComponent`. + Over time, you add more components to declare. @@ -284,8 +289,8 @@ The following are all in `src/` [bootstraps](guide/bootstrapping) the application's main module (`AppModule`) to run in the browser. The JIT compiler is a reasonable choice during the development of most projects and - it's the only viable choice for a sample running in a _live-coding_ environment like Stackblitz. - You'll learn about alternative compiling and [deployment](guide/deployment) options later in the documentation. + it's the only viable choice for a sample running in a _live-coding_ environment such as Stackblitz. + Alternative [compilation](guide/aot-compiler), [build](guide/build), and [deployment](guide/deployment) options are available. @@ -294,43 +299,6 @@ The following are all in `src/` - -
- - - -### Next Step - -If you're new to Angular, we recommend you follow the [tutorial](tutorial "Tour of Heroes tutorial"). - - -
- -



- -{@a install-prerequisites} - - - -## Appendix: Node.js and npm - - -[Node.js](https://nodejs.org/en/) and the [npm](https://www.npmjs.com/) package manager are essential to modern web development with Angular and other platforms. -Node.js powers client development and build tools. -The _npm_ package manager, which is itself a _Node.js_ application, installs JavaScript libraries. - - -Get them now if they're not already installed on your machine. - -**Verify that you are running Node.js `v8.x` or higher and npm `5.x` or higher** -by running the commands `node -v` and `npm -v` in a terminal/console window. -Older versions produce errors. - -We recommend [nvm](https://github.com/creationix/nvm) for managing multiple versions of Node.js and npm. -You may need [nvm](https://github.com/creationix/nvm) if you already have projects running on your machine that use other versions of Node.js and npm. - - - ## Appendix: Develop locally with IE If you develop angular locally with `ng serve`, a `websocket` connection is set up automatically between browser and local dev server, so when your code changes, the browser can automatically refresh. diff --git a/aio/content/guide/upgrade.md b/aio/content/guide/upgrade.md index 98fad30902..cb015eb1a9 100644 --- a/aio/content/guide/upgrade.md +++ b/aio/content/guide/upgrade.md @@ -422,8 +422,7 @@ will result in the same thing: To begin converting your AngularJS application to a hybrid, you need to load the Angular framework. -You can see how this can be done with SystemJS by following the instructions in [Setup](guide/setup), -selectively copying code from the [QuickStart github repository](https://github.com/angular/quickstart). +You can see how this can be done with SystemJS by following the instructions in [Setup for Upgrading to AngularJS](guide/upgrade-setup) for selectively copying code from the [QuickStart github repository](https://github.com/angular/quickstart). You also need to install the `@angular/upgrade` package via `npm install @angular/upgrade --save` and add a mapping for the `@angular/upgrade/static` package: @@ -1311,7 +1310,7 @@ Turn to the [Angular animations](guide/animations) guide to learn about that. Install Angular into the project, along with the SystemJS module loader. -Take a look at the results of the [Setup](guide/setup) instructions +Take a look at the results of the [upgrade setup instructions](guide/upgrade-setup) and get the following configurations from there: * Add Angular and the other new dependencies to `package.json` @@ -1352,7 +1351,7 @@ to load the actual application: You also need to make a couple of adjustments -to the `systemjs.config.js` file installed during [setup](guide/setup). +to the `systemjs.config.js` file installed during [upgrade setup](guide/upgrade-setup). Point the browser to the project root when loading things through SystemJS, instead of using the `` URL. diff --git a/aio/content/navigation.json b/aio/content/navigation.json index 18236c6685..0197a1295f 100644 --- a/aio/content/navigation.json +++ b/aio/content/navigation.json @@ -506,6 +506,12 @@ "title": "Upgrading from AngularJS", "tooltip": "Incrementally upgrade an AngularJS application to Angular.", "children": [ + { + "url": "guide/upgrade-setup", + "title": "Setup for Upgrading from AngularJS", + "tooltip": "Use code from the Angular QuickStart seed as part of upgrading from AngularJS.", + "hidden": true + }, { "url": "guide/upgrade", "title": "Upgrading Instructions", @@ -587,7 +593,7 @@ "tooltip": "Build, testing, and deployment information.", "children": [ { - "url": "guide/setup", + "url": "guide/upgrade-setup", "title": "Upgrade setup", "tooltip": "How to set up the Angular QuickStart seed in the context of upgrading from AngularJS.", "hidden": true diff --git a/aio/firebase.json b/aio/firebase.json index 5f3b52588d..0bf5acd64f 100644 --- a/aio/firebase.json +++ b/aio/firebase.json @@ -26,6 +26,7 @@ {"type": 301, "source": "/guide/service-worker-comm", "destination": "/guide/service-worker-communications"}, {"type": 301, "source": "/guide/service-worker-configref", "destination": "/guide/service-worker-config"}, {"type": 301, "source": "/guide/webpack", "destination": "https://v5.angular.io/guide/webpack"}, + {"type": 301, "source": "/guide/setup", "destination": "/guide/setup-local"}, {"type": 301, "source": "/guide/setup-systemjs-anatomy", "destination": "/guide/file-structure"}, {"type": 301, "source": "/guide/change-log", "destination": "https://github.com/angular/angular/blob/master/CHANGELOG.md"}, {"type": 301, "source": "/guide/quickstart", "destination": "/start"}, diff --git a/aio/ngsw-config.json b/aio/ngsw-config.json index eefdd3d1a9..9192206bf6 100644 --- a/aio/ngsw-config.json +++ b/aio/ngsw-config.json @@ -122,6 +122,8 @@ "!/guide/webpack", "!/guide/webpack.html", "!/guide/webpack/", + "!/guide/setup", + "!/guide/setup.html", "!/guide/setup-systemjs-anatomy", "!/guide/setup-systemjs-anatomy.html", "!/guide/quickstart",