Skip to content

Commit

Permalink
docs: Edited to remove jargon. (#41978)
Browse files Browse the repository at this point in the history
PR Close #41978
  • Loading branch information
TeriGlover authored and umairhm committed May 28, 2021
1 parent e3ccd2b commit 0ed0bd0
Show file tree
Hide file tree
Showing 7 changed files with 108 additions and 52 deletions.
8 changes: 4 additions & 4 deletions aio/content/guide/angular-compiler-options.md
Expand Up @@ -103,15 +103,15 @@ 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`

When `true`, replaces the `templateUrl` and `styleUrls` property in all `@Component` decorators with inlined contents in `template` and `styles` properties.

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}
Expand Down Expand Up @@ -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`

Expand All @@ -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`

Expand Down
10 changes: 5 additions & 5 deletions aio/content/guide/aot-compiler.md
Expand Up @@ -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*
Expand All @@ -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.

Expand Down
64 changes: 60 additions & 4 deletions aio/content/guide/build.md
Expand Up @@ -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:

Expand All @@ -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.
Expand Down Expand Up @@ -291,12 +291,68 @@ To disable these warnings, you can add the CommonJS module name to `allowedCommo
},
</code-example>

{@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.
Expand Down Expand Up @@ -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).
Expand Down
2 changes: 1 addition & 1 deletion aio/content/guide/language-service.md
Expand Up @@ -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.

<div class="lightbox">
Expand Down
14 changes: 7 additions & 7 deletions 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&mdash;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&mdash;a design pattern that loads NgModules as needed. Lazy loading helps keep initial
bundle sizes smaller, which in turn helps decrease load times.

<div class="alert is-helpful">

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
<live-example></live-example>.

</div>
Expand Down Expand Up @@ -66,7 +66,7 @@ where `customer-app` is the name of your app:
ng new customer-app --routing
</code-example>

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`.
Expand Down Expand Up @@ -135,7 +135,7 @@ so you can easily navigate to your modules in the browser:

<code-example path="lazy-loading-ngmodules/src/app/app.component.html" header="app.component.html" region="app-component-template" header="src/app/app.component.html"></code-example>

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:

<code-example language="bash">
ng serve
Expand Down Expand Up @@ -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.

<div class="lightbox">
<img src="generated/images/guide/lazy-loading-ngmodules/network-tab.png" width="600" alt="lazy loaded modules diagram">
Expand Down Expand Up @@ -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`.

Expand Down
6 changes: 3 additions & 3 deletions aio/content/guide/template-typecheck.md
Expand Up @@ -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 `<ng-template>` 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.

Expand Down Expand Up @@ -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).
<table>
Expand Down Expand Up @@ -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

Expand Down

0 comments on commit 0ed0bd0

Please sign in to comment.