From 0ed0bd0fb336fee435f5a91dff4943355d83d101 Mon Sep 17 00:00:00 2001 From: Teri Glover Date: Fri, 7 May 2021 04:28:01 +0000 Subject: [PATCH] docs: Edited to remove jargon. (#41978) PR Close #41978 --- aio/content/guide/angular-compiler-options.md | 8 +-- aio/content/guide/aot-compiler.md | 10 +-- aio/content/guide/build.md | 64 +++++++++++++++++-- aio/content/guide/language-service.md | 2 +- aio/content/guide/lazy-loading-ngmodules.md | 14 ++-- aio/content/guide/template-typecheck.md | 6 +- aio/content/guide/universal.md | 56 ++++++++-------- 7 files changed, 108 insertions(+), 52 deletions(-) diff --git a/aio/content/guide/angular-compiler-options.md b/aio/content/guide/angular-compiler-options.md index ecdeacc0c843d..0dad034e59156 100644 --- a/aio/content/guide/angular-compiler-options.md +++ b/aio/content/guide/angular-compiler-options.md @@ -103,7 +103,7 @@ This allows `$localize` messages in application code to use the same id as ident Enables the [Ivy](guide/ivy) compilation and rendering pipeline. Default is `true`, as of version 9. In version 9, you can [opt out of Ivy](guide/ivy#opting-out-of-angular-ivy) to continue using the previous compiler, View Engine. -For library projects generated with the CLI, the `prod` configuration default is `false` in version 9. +For library projects generated with the CLI, the production configuration default is `false` in version 9. ### `enableResourceInlining` @@ -111,7 +111,7 @@ When `true`, replaces the `templateUrl` and `styleUrls` property in all `@Compon When enabled, the `.js` output of `ngc` does not include any lazy-loaded template or style URLs. -For library projects generated with the CLI, the dev configuration default is `true`. +For library projects generated with the CLI, the development configuration default is `true`. {@a enablelegacytemplate} @@ -184,7 +184,7 @@ When `true`, does not emit `.ngfactory.js` and `.ngstyle.js` files. This turns o Can be used to instruct the template compiler to produce `.metadata.json` files for distribution with an `npm` package while avoiding the production of `.ngfactory.js` and `.ngstyle.js` files that cannot be distributed to `npm`. -For library projects generated with the CLI, the dev configuration default is `true`. +For library projects generated with the CLI, the development configuration default is `true`. ### `strictMetadataEmit` @@ -202,7 +202,7 @@ If the client of a library intends to use a symbol in an annotation, the templat This option allows detection of these errors during the build phase of the library and is used, for example, in producing Angular libraries themselves. -For library projects generated with the CLI, the dev configuration default is `true`. +For library projects generated with the CLI, the development configuration default is `true`. ### `strictInjectionParameters` diff --git a/aio/content/guide/aot-compiler.md b/aio/content/guide/aot-compiler.md index 9e8a7f67c8217..fce4ec07354e1 100644 --- a/aio/content/guide/aot-compiler.md +++ b/aio/content/guide/aot-compiler.md @@ -18,14 +18,14 @@ Here are some reasons you might want to use AOT. * *Faster rendering* With AOT, the browser downloads a pre-compiled version of the application. - The browser loads executable code so it can render the application immediately, without waiting to compile the app first. + The browser loads executable code so it can render the application immediately, without waiting to compile the application first. * *Fewer asynchronous requests* The compiler _inlines_ external HTML templates and CSS style sheets within the application JavaScript, eliminating separate ajax requests for those source files. * *Smaller Angular framework download size* - There's no need to download the Angular compiler if the app is already compiled. + There's no need to download the Angular compiler if the application is already compiled. The compiler is roughly half of Angular itself, so omitting it dramatically reduces the application payload. * *Detect template errors earlier* @@ -43,10 +43,10 @@ Here are some reasons you might want to use AOT. Angular offers two ways to compile your application: -* **_Just-in-Time_ (JIT)**, which compiles your app in the browser at runtime. This was the default until Angular 8. -* **_Ahead-of-Time_ (AOT)**, which compiles your app and libraries at build time. This is the default since Angular 9. +* **_Just-in-Time_ (JIT)**, which compiles your application in the browser at runtime. This was the default until Angular 8. +* **_Ahead-of-Time_ (AOT)**, which compiles your application and libraries at build time. This is the default since Angular 9. -When you run the [`ng build`](cli/build) (build only) or [`ng serve`](cli/serve) (build and serve locally) CLI commands, the type of compilation (JIT or AOT) depends on the value of the `aot` property in your build configuration specified in `angular.json`. By default, `aot` is set to `true` for new CLI apps. +When you run the [`ng build`](cli/build) (build only) or [`ng serve`](cli/serve) (build and serve locally) CLI commands, the type of compilation (JIT or AOT) depends on the value of the `aot` property in your build configuration specified in `angular.json`. By default, `aot` is set to `true` for new CLI applications. See the [CLI command reference](cli) and [Building and serving Angular apps](guide/build) for more information. diff --git a/aio/content/guide/build.md b/aio/content/guide/build.md index 86809fbefa578..5b6cae399c1d4 100644 --- a/aio/content/guide/build.md +++ b/aio/content/guide/build.md @@ -198,7 +198,7 @@ Specify size values in the following formats: * 12%: Percentage of size relative to baseline. (Not valid for baseline values.) -When you configure a budget, the build system warns or reports an error when a given part of the app reaches or exceeds a boundary size that you set. +When you configure a budget, the build system warns or reports an error when a given part of the application reaches or exceeds a boundary size that you set. Each budget entry is a JSON object with the following properties: @@ -217,7 +217,7 @@ Each budget entry is a JSON object with the following properties: * `bundle` - The size of a specific bundle. * `initial` - The size of JavaScript needed for bootstrapping the application. Defaults to warning @ 500kb and erroring at 1mb. * `allScript` - The size of all scripts. -* `all` - The size of the entire app. +* `all` - The size of the entire application. * `anyComponentStyle` - This size of any one component stylesheet. Defaults to warning at 2kb and erroring at 4kb. * `anyScript` - The size of any one script. * `any` - The size of any file. @@ -291,12 +291,68 @@ To disable these warnings, you can add the CommonJS module name to `allowedCommo }, +{@a browser-compat} + +## Configuring browser compatibility + +The CLI uses [Autoprefixer](https://github.com/postcss/autoprefixer) to ensure compatibility with different browser and browser versions. +You may find it necessary to target specific browsers or exclude certain browser versions from your build. + +Internally, Autoprefixer relies on a library called [Browserslist](https://github.com/browserslist/browserslist) to figure out which browsers to support with prefixing. +Browserlist looks for configuration options in a `browserslist` property of the package configuration file, or in a configuration file named `.browserslistrc`. +Autoprefixer looks for the `browserslist` configuration when it prefixes your CSS. + +* You can tell Autoprefixer what browsers to target by adding a browserslist property to the package configuration file, `package.json`: +``` + "browserslist": [ + "> 1%", + "last 2 versions" + ] +``` + +* Alternatively, you can add a new file, `.browserslistrc`, to the project directory, that specifies browsers you want to support: +``` + ### Supported Browsers + > 1% + last 2 versions +``` + +See the [browserslist repo](https://github.com/browserslist/browserslist) for more examples of how to target specific browsers and versions. + +### Backward compatibility with Lighthouse + +If you want to produce a progressive web application and are using [Lighthouse](https://developers.google.com/web/tools/lighthouse/) to grade the project, add the following `browserslist` entry to your `package.json` file, in order to eliminate the [old flexbox](https://developers.google.com/web/tools/lighthouse/audits/old-flexbox) prefixes: + +``` +"browserslist": [ + "last 2 versions", + "not ie <= 10", + "not ie_mob <= 10" +] +``` + +### Backward compatibility with CSS grid + +CSS grid layout support in Autoprefixer, which was previously on by default, is off by default in Angular 8 and higher. + +To use CSS grid with Internet Explorer 10/11, you must explicitly enable it using the `autoplace` option. +To do this, add the following to the top of the global styles file (or within a specific css selector scope): + +``` +/* autoprefixer grid: autoplace */ +``` +or +``` +/* autoprefixer grid: no-autoplace */ +``` + +For more information, see [Autoprefixer documentation](https://autoprefixer.github.io/). {@a proxy} ## Proxying to a backend server -You can use the [proxying support](https://webpack.js.org/configuration/dev-server/#devserverproxy) in the `webpack` dev server to divert certain URLs to a backend server, by passing a file to the `--proxy-config` build option. +You can use the [proxying support](https://webpack.js.org/configuration/dev-server/#devserverproxy) in the `webpack` development server to divert certain URLs to a backend server, by passing a file to the `--proxy-config` build option. For example, to divert all calls for `http://localhost:4200/api` to a server running on `http://localhost:3000/api`, take the following steps. 1. Create a file `proxy.conf.json` in your project's `src/` folder. @@ -324,7 +380,7 @@ For example, to divert all calls for `http://localhost:4200/api` to a server run ... ``` -1. To run the dev server with this proxy configuration, call `ng serve`. +1. To run the development server with this proxy configuration, call `ng serve`. You can edit the proxy configuration file to add configuration options; some examples are given below. For a description of all options, see [webpack DevServer documentation](https://webpack.js.org/configuration/dev-server/#devserverproxy). diff --git a/aio/content/guide/language-service.md b/aio/content/guide/language-service.md index ba0ec323eee09..769c139be9447 100644 --- a/aio/content/guide/language-service.md +++ b/aio/content/guide/language-service.md @@ -57,7 +57,7 @@ In this example, Angular doesn't know what `orders` is or where it comes from. ### Quick info and navigation -The quick-info feature allows you to hover to see where components, directives, modules, and so on come from. +The quick-info feature allows you to hover to see where components, directives, and modules come from. You can then click "Go to definition" or press F12 to go directly to the definition.
diff --git a/aio/content/guide/lazy-loading-ngmodules.md b/aio/content/guide/lazy-loading-ngmodules.md index 0a926ef6c6ff6..5a88bd513edd5 100644 --- a/aio/content/guide/lazy-loading-ngmodules.md +++ b/aio/content/guide/lazy-loading-ngmodules.md @@ -1,11 +1,11 @@ # Lazy-loading feature modules -By default, NgModules are eagerly loaded, which means that as soon as the app loads, so do all the NgModules, whether or not they are immediately necessary. For large apps with lots of routes, consider lazy loading—a design pattern that loads NgModules as needed. Lazy loading helps keep initial +By default, NgModules are eagerly loaded, which means that as soon as the application loads, so do all the NgModules, whether or not they are immediately necessary. For large applications with lots of routes, consider lazy loading—a design pattern that loads NgModules as needed. Lazy loading helps keep initial bundle sizes smaller, which in turn helps decrease load times.
-For the final sample app with two lazy-loaded modules that this page describes, see the +For the final sample application with two lazy-loaded modules that this page describes, see the .
@@ -66,7 +66,7 @@ where `customer-app` is the name of your app: ng new customer-app --routing -This creates an app called `customer-app` and the `--routing` flag +This creates an application called `customer-app` and the `--routing` flag generates a file called `app-routing.module.ts`, which is one of the files you need for setting up lazy loading for your feature module. Navigate into the project by issuing the command `cd customer-app`. @@ -135,7 +135,7 @@ so you can easily navigate to your modules in the browser: -To see your app in the browser so far, enter the following command in the terminal window: +To see your application in the browser so far, enter the following command in the terminal window: ng serve @@ -185,7 +185,7 @@ The other feature module's routing module is configured similarly. ### Verify lazy loading -You can check to see that a module is indeed being lazy loaded with the Chrome developer tools. In Chrome, open the dev tools by pressing `Cmd+Option+i` on a Mac or `Ctrl+Shift+j` on a PC and go to the Network Tab. +You can check to see that a module is indeed being lazy loaded with the Chrome developer tools. In Chrome, open the developer tools by pressing `Cmd+Option+i` on a Mac or `Ctrl+Shift+j` on a PC and go to the Network Tab.
lazy loaded modules diagram @@ -228,12 +228,12 @@ For more information, see the [`forRoot()` pattern](guide/singleton-services#for ## Preloading -Preloading improves UX by loading parts of your app in the background. +Preloading improves UX by loading parts of your application in the background. You can preload modules or component data. ### Preloading modules -Preloading modules improves UX by loading parts of your app in the background so users don't have to wait for the elements to download when they activate a route. +Preloading modules improves UX by loading parts of your application in the background so users don't have to wait for the elements to download when they activate a route. To enable preloading of all lazy loaded modules, import the `PreloadAllModules` token from the Angular `router`. diff --git a/aio/content/guide/template-typecheck.md b/aio/content/guide/template-typecheck.md index 57dead83ede63..7a26778896935 100644 --- a/aio/content/guide/template-typecheck.md +++ b/aio/content/guide/template-typecheck.md @@ -20,7 +20,7 @@ The compiler does not verify that the value of `user.address.city` is assignable The compiler also has some major limitations in this mode: * Importantly, it doesn't check embedded views, such as `*ngIf`, `*ngFor`, other `` embedded view. -* It doesn't figure out the types of `#refs`, the results of pipes, the type of `$event` in event bindings, and so on. +* It doesn't figure out the types of `#refs`, the results of pipes, or the type of `$event` in event bindings. In many cases, these things end up as type `any`, which can cause subsequent parts of the expression to go unchecked. @@ -110,7 +110,7 @@ In case of a false positive like these, there are a few options: * Use the [`$any()` type-cast function](guide/template-expression-operators#any-type-cast-function) in certain contexts to opt out of type-checking for a part of the expression. * You can disable strict checks entirely by setting `strictTemplates: false` in the application's TypeScript configuration file, `tsconfig.json`. * You can disable certain type-checking operations individually, while maintaining strictness in other aspects, by setting a _strictness flag_ to `false`. -* If you want to use `strictTemplates` and `strictNullChecks` together, you can opt out of strict null type checking specifically for input bindings via `strictNullInputTypes`. +* If you want to use `strictTemplates` and `strictNullChecks` together, you can opt out of strict null type checking specifically for input bindings using `strictNullInputTypes`. Unless otherwise noted, each option below is set to the value for `strictTemplates` (`true` when `strictTemplates` is `true` and vice versa). @@ -170,7 +170,7 @@ If that doesn't work, an option of last resort is to turn off full mode entirely A type-checking error that you cannot resolve with any of the recommended methods can be the result of a bug in the template type-checker itself. If you get errors that require falling back to basic mode, it is likely to be such a bug. -If this happens, please [file an issue](https://github.com/angular/angular/issues) so the team can address it. +If this happens, [file an issue](https://github.com/angular/angular/issues) so the team can address it. ## Inputs and type-checking diff --git a/aio/content/guide/universal.md b/aio/content/guide/universal.md index acd5e1b320a32..0531e55f06736 100644 --- a/aio/content/guide/universal.md +++ b/aio/content/guide/universal.md @@ -7,7 +7,7 @@ Angular Universal executes on the _server_, generating _static_ application page the client. This means that the application generally renders more quickly, giving users a chance to view the application layout before it becomes fully interactive. -For a more detailed look at different techniques and concepts surrounding SSR, please check out this +For a more detailed look at different techniques and concepts surrounding SSR, check out this [article](https://developers.google.com/web/updates/2019/02/rendering-on-the-web). You can easily prepare an application for server-side rendering using the [Angular CLI](guide/glossary#cli). @@ -25,7 +25,7 @@ The CLI schematic `@nguniversal/express-engine` performs the required steps, as The [Tour of Heroes tutorial](tutorial) is the foundation for this walkthrough. -In this example, the Angular CLI compiles and bundles the Universal version of the app with the +In this example, the Angular CLI compiles and bundles the Universal version of the application with the [Ahead-of-Time (AOT) compiler](guide/aot-compiler). A Node.js Express web server compiles HTML pages with Universal based on client requests. @@ -58,7 +58,7 @@ The files marked with `*` are new and not in the original tutorial sample. ### Universal in action -To start rendering your app with Universal on your local system, use the following command. +To start rendering your application with Universal on your local system, use the following command. npm run dev:ssr @@ -67,7 +67,7 @@ npm run dev:ssr Open a browser and navigate to http://localhost:4200/. You should see the familiar Tour of Heroes dashboard page. -Navigation via `routerLinks` works correctly because they use the native anchor (``) tags. +Navigation using `routerLinks` works correctly because they use the native anchor (``) tags. You can go from the Dashboard to the Heroes page and back. You can click a hero on the Dashboard page to display its Details page. @@ -78,11 +78,11 @@ you'll notice: * The *Back* and *Save* buttons on the Details page don't work. User events other than `routerLink` clicks aren't supported. -You must wait for the full client app to bootstrap and run, or buffer the events using libraries like +You must wait for the full client application to bootstrap and run, or buffer the events using libraries like [preboot](https://github.com/angular/preboot), which allow you to replay these events once the client-side scripts load. -The transition from the server-rendered app to the client app happens quickly on a development machine, but you should -always test your apps in real-world scenarios. +The transition from the server-rendered application to the client application happens quickly on a development machine, but you should +always test your applications in real-world scenarios. You can simulate a slower network to see the transition more clearly as follows: @@ -91,12 +91,12 @@ You can simulate a slower network to see the transition more clearly as follows: dropdown on the far right of the menu bar. 1. Try one of the "3G" speeds. -The server-rendered application still launches quickly but the full client app may take seconds to load. +The server-rendered application still launches quickly but the full client application may take seconds to load. {@a why-do-it} ## Why use server-side rendering? -There are three main reasons to create a Universal version of your app. +There are three main reasons to create a Universal version of your application. 1. Facilitate web crawlers through [search engine optimization (SEO)](https://static.googleusercontent.com/media/www.google.com/en//webmasters/docs/search-engine-optimization-starter-guide.pdf) 1. Improve performance on mobile and low-powered devices @@ -110,32 +110,32 @@ Google, Bing, Facebook, Twitter, and other social media sites rely on web crawle make that content searchable on the web. These web crawlers may be unable to navigate and index your highly interactive Angular application as a human user could do. -Angular Universal can generate a static version of your app that is easily searchable, linkable, and navigable without JavaScript. +Angular Universal can generate a static version of your application that is easily searchable, linkable, and navigable without JavaScript. Universal also makes a site preview available since each URL returns a fully rendered page. {@a no-javascript} ### Improve performance on mobile and low-powered devices Some devices don't support JavaScript or execute JavaScript so poorly that the user experience is unacceptable. -For these cases, you may require a server-rendered, no-JavaScript version of the app. +For these cases, you may require a server-rendered, no-JavaScript version of the application. This version, however limited, may be the only practical alternative for -people who otherwise couldn't use the app at all. +people who otherwise couldn't use the application at all. {@a startup-performance} ### Show the first page quickly Displaying the first page quickly can be critical for user engagement. Pages that load faster perform better, [even with changes as small as 100ms](https://web.dev/shopping-for-speed-on-ebay/). -Your app may have to launch faster to engage these users before they decide to do something else. +Your application may have to launch faster to engage these users before they decide to do something else. -With Angular Universal, you can generate landing pages for the app that look like the complete app. +With Angular Universal, you can generate landing pages for the application that look like the complete application. The pages are pure HTML, and can display even if JavaScript is disabled. The pages don't handle browser events, but they _do_ support navigation through the site using [`routerLink`](guide/router-reference#router-link). In practice, you'll serve a static version of the landing page to hold the user's attention. -At the same time, you'll load the full Angular app behind it. +At the same time, you'll load the full Angular application behind it. The user perceives near-instant performance from the landing page -and gets the full interactive experience after the full app loads. +and gets the full interactive experience after the full application loads. {@a how-does-it-work} ## Universal web servers @@ -148,7 +148,7 @@ The sample web server for this guide is based on the popular [Express](https://e
- **Note:** _Any_ web server technology can serve a Universal app as long as it can call Universal's `renderModule()` function. + **Note:** _Any_ web server technology can serve a Universal application as long as it can call Universal's `renderModule()` function. The principles and decision points discussed here apply to any web server technology.
@@ -172,7 +172,7 @@ Finally, the server returns the rendered page to the client. ### Working around the browser APIs -Because a Universal app doesn't execute in the browser, some of the browser APIs and capabilities may be missing on the server. +Because a Universal application doesn't execute in the browser, some of the browser APIs and capabilities may be missing on the server. For example, server-side applications can't reference browser-only global objects such as `window`, `document`, `navigator`, or `location`. @@ -181,9 +181,9 @@ or [`DOCUMENT`](api/common/DOCUMENT); it may substitute adequately for these API If Angular doesn't provide it, it's possible to write new abstractions that delegate to the browser APIs while in the browser and to an alternative implementation while on the server (aka shimming). -Similarly, without mouse or keyboard events, a server-side app can't rely on a user clicking a button to show a component. -The app must determine what to render based solely on the incoming client request. -This is a good argument for making the app [routable](guide/router). +Similarly, without mouse or keyboard events, a server-side application can't rely on a user clicking a button to show a component. +The application must determine what to render based solely on the incoming client request. +This is a good argument for making the application [routable](guide/router). {@a universal-engine} ### Universal template engine @@ -196,8 +196,8 @@ The important bit in the `server.ts` file is the `ngExpressEngine()` function. The `ngExpressEngine()` function is a wrapper around Universal's `renderModule()` function which turns a client's requests into server-rendered HTML pages. It accepts an object with the following properties: -* `bootstrap`: The root `NgModule` or `NgModule` factory to use for bootstraping the app when rendering on the server. For the example app, it is `AppServerModule`. It's the bridge between the Universal server-side renderer and the Angular application. -* `extraProviders`: This is optional and lets you specify dependency providers that apply only when rendering the app on the server. You can do this when your app needs information that can only be determined by the currently running server instance. +* `bootstrap`: The root `NgModule` or `NgModule` factory to use for bootstraping the application when rendering on the server. For the example app, it is `AppServerModule`. It's the bridge between the Universal server-side renderer and the Angular application. +* `extraProviders`: This is optional and lets you specify dependency providers that apply only when rendering the application on the server. You can do this when your application needs information that can only be determined by the currently running server instance. The `ngExpressEngine()` function returns a `Promise` callback that resolves to the rendered page. It's up to the engine to decide what to do with that page. @@ -220,7 +220,7 @@ The web server must distinguish _app page requests_ from other kinds of requests It's not as simple as intercepting a request to the root address `/`. The browser could ask for one of the application routes such as `/dashboard`, `/heroes`, or `/detail:12`. -In fact, if the app were only rendered by the server, _every_ app link clicked would arrive at the server +In fact, if the application were only rendered by the server, _every_ application link clicked would arrive at the server as a navigation URL intended for the router. Fortunately, application routes have something in common: their URLs lack file extensions. @@ -278,8 +278,8 @@ You don't need to do anything to make relative URLs work on the server. If, for some reason, you are not using an `@nguniversal/*-engine` package, you may need to handle it yourself. The recommended solution is to pass the full request URL to the `options` argument of [renderModule()](api/platform-server/renderModule) or [renderModuleFactory()](api/platform-server/renderModuleFactory) (depending on what you use to render `AppServerModule` on the server). -This option is the least intrusive as it does not require any changes to the app. -Here, "request URL" refers to the URL of the request as a response to which the app is being rendered on the server. -For example, if the client requested `https://my-server.com/dashboard` and you are rendering the app on the server to respond to that request, `options.url` should be set to `https://my-server.com/dashboard`. +This option is the least intrusive as it does not require any changes to the application. +Here, "request URL" refers to the URL of the request as a response to which the application is being rendered on the server. +For example, if the client requested `https://my-server.com/dashboard` and you are rendering the application on the server to respond to that request, `options.url` should be set to `https://my-server.com/dashboard`. -Now, on every HTTP request made as part of rendering the app on the server, Angular can correctly resolve the request URL to an absolute URL, using the provided `options.url`. +Now, on every HTTP request made as part of rendering the application on the server, Angular can correctly resolve the request URL to an absolute URL, using the provided `options.url`.