docs: refresh TypeScript configuration guide with updated info and files (#31097)

This removes the hard-coded tsconfig.json to use a separate file.
The tsconfig.0.json is added to the getting-started example folder
because have to check it with every major release
Also updates the text regarding defaults for TypeScript compilation targets
and typings

PR Close #31097
This commit is contained in:
Brandon 2019-06-17 09:19:10 -05:00 committed by Andrew Kushnir
parent 7e49beb8cd
commit 57c4788bc7
2 changed files with 39 additions and 51 deletions

View File

@ -0,0 +1,29 @@
// This tsconfig is used in the TypeScript
// configuration guide (../guide/typescript-configuration.md)
// to display the latest default configuration
// Note: Update with every major release to the latest default
// #docregion
{
"compileOnSave": false,
"compilerOptions": {
"baseUrl": "./",
"outDir": "./dist/out-tsc",
"sourceMap": true,
"declaration": false,
"module": "esnext",
"moduleResolution": "node",
"emitDecoratorMetadata": true,
"experimentalDecorators": true,
"importHelpers": true,
"target": "es2015",
"typeRoots": [
"node_modules/@types"
],
// #docregion lib
"lib": [
"es2018",
"dom"
]
// #enddocregion lib
}
}

View File

@ -23,31 +23,14 @@ guide the compiler as it generates JavaScript files.
<div class="alert is-helpful"> <div class="alert is-helpful">
For details about `tsconfig.json`, see the official For details about `tsconfig.json`, see the official
[TypeScript wiki](http://www.typescriptlang.org/docs/handbook/tsconfig-json.html). [TypeScript wiki](http://www.typescriptlang.org/docs/handbook/tsconfig-json.html).
</div> </div>
The [Setup](guide/setup-local) guide uses the following `tsconfig.json`:
<code-example path="getting-started/tsconfig.0.json" header="tsconfig.json" linenums="false">
The [Setup](guide/setup) guide uses the following `tsconfig.json`:
<code-example lang="json" header="tsconfig.json" linenums="false">
{
"compilerOptions": {
"target": "es5",
"module": "commonjs",
"moduleResolution": "node",
"sourceMap": true,
"emitDecoratorMetadata": true,
"experimentalDecorators": true,
"lib": [ "es2015", "dom" ],
"noImplicitAny": true,
"suppressImplicitAnyIndexErrors": true
}
}
</code-example> </code-example>
This file contains options and flags that are essential for Angular applications. This file contains options and flags that are essential for Angular applications.
@ -66,7 +49,6 @@ When the `noImplicitAny` flag is `false` (the default), and if
the compiler cannot infer the variable type based on how it's used, the compiler cannot infer the variable type based on how it's used,
the compiler silently defaults the type to `any`. That's what is meant by *implicit `any`*. the compiler silently defaults the type to `any`. That's what is meant by *implicit `any`*.
The documentation setup sets the `noImplicitAny` flag to `true`.
When the `noImplicitAny` flag is `true` and the TypeScript compiler cannot infer When the `noImplicitAny` flag is `true` and the TypeScript compiler cannot infer
the type, it still generates the JavaScript files, but it also **reports an error**. the type, it still generates the JavaScript files, but it also **reports an error**.
Many seasoned developers prefer this stricter setting because type checking catches more Many seasoned developers prefer this stricter setting because type checking catches more
@ -79,20 +61,15 @@ Most developers feel that *this particular error* is more annoying than helpful.
You can suppress them with the following additional flag: You can suppress them with the following additional flag:
<code-example format="."> <code-example format=".">
"suppressImplicitAnyIndexErrors":true
"suppressImplicitAnyIndexErrors": true
</code-example> </code-example>
The documentation setup sets this flag to `true` as well.
{@a typings} {@a typings}
## TypeScript Typings ## TypeScript Typings
Many JavaScript libraries, such as jQuery, the Jasmine testing library, and Angular, Many JavaScript libraries, such as jQuery, the Jasmine testing library, and Angular,
extend the JavaScript environment with features and syntax extend the JavaScript environment with features and syntax
that the TypeScript compiler doesn't recognize natively. that the TypeScript compiler doesn't recognize natively.
@ -116,20 +93,13 @@ TypeScript includes a special declaration file called `lib.d.ts`. This file cont
Based on the `--target`, TypeScript adds _additional_ ambient declarations Based on the `--target`, TypeScript adds _additional_ ambient declarations
like `Promise` if the target is `es6`. like `Promise` if the target is `es6`.
Since the QuickStart is targeting `es5`, you can override the By default, the target is `es2015`. If you are targeting `es5`, you still have newer type declarations due to the list of declaration files included:
list of declaration files to be included:
<code-example format=".">
"lib": ["es2015", "dom"]
<code-example path="getting-started/tsconfig.0.json" header="tsconfig.json (lib excerpt)" linenums="false" region="lib">
</code-example> </code-example>
Thanks to that, you have all the `es6` typings even when targeting `es5`.
### Installable typings files ### Installable typings files
Many libraries&mdash;jQuery, Jasmine, and Lodash among them&mdash;do *not* include `d.ts` files in their npm packages. Many libraries&mdash;jQuery, Jasmine, and Lodash among them&mdash;do *not* include `d.ts` files in their npm packages.
Fortunately, either their authors or community contributors have created separate `d.ts` files for these libraries and Fortunately, either their authors or community contributors have created separate `d.ts` files for these libraries and
published them in well-known locations. published them in well-known locations.
@ -138,17 +108,7 @@ You can install these typings via `npm` using the
[`@types/*` scoped package](http://www.typescriptlang.org/docs/handbook/declaration-files/consumption.html) [`@types/*` scoped package](http://www.typescriptlang.org/docs/handbook/declaration-files/consumption.html)
and Typescript, starting at 2.0, automatically recognizes them. and Typescript, starting at 2.0, automatically recognizes them.
For instance, to install typings for `jasmine` you could do `npm install @types/jasmine --save-dev`. For instance, to install typings for `jasmine` you run `npm install @types/jasmine --save-dev`.
QuickStart identifies two *typings*, or `d.ts`, files:
* [jasmine](http://jasmine.github.io/) typings for the Jasmine test framework.
* [node](https://www.npmjs.com/package/@types/node) for code that references objects in the *Node.js®* environment;
QuickStart doesn't require these typings but many of the samples do.
{@a target} {@a target}
@ -156,5 +116,4 @@ QuickStart doesn't require these typings but many of the samples do.
### *target* ### *target*
By default, the target is `es5`, you can configure the target to `es6` if you only want to deploy the application to By default, the target is `es2015`, which is supported only in modern browsers. You can configure the target to `es5` to specifically support legacy browsers. [Differential loading](guide/deployment#differential-loading) is also provided by the Angular CLI to support modern, and legacy browsers with separate bundles.
es6 compatible browser. But if you configure the target to `es6` in some old browser such as `IE`, `Syntax Error` will be thrown.