From 57c4788bc73f4ec4654b14670d82265220d2f273 Mon Sep 17 00:00:00 2001 From: Brandon Date: Mon, 17 Jun 2019 09:19:10 -0500 Subject: [PATCH] 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 --- .../examples/getting-started/tsconfig.0.json | 29 +++++++++ aio/content/guide/typescript-configuration.md | 61 +++---------------- 2 files changed, 39 insertions(+), 51 deletions(-) create mode 100644 aio/content/examples/getting-started/tsconfig.0.json diff --git a/aio/content/examples/getting-started/tsconfig.0.json b/aio/content/examples/getting-started/tsconfig.0.json new file mode 100644 index 0000000000..58d3db1566 --- /dev/null +++ b/aio/content/examples/getting-started/tsconfig.0.json @@ -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 + } +} diff --git a/aio/content/guide/typescript-configuration.md b/aio/content/guide/typescript-configuration.md index 172ab7248c..3e3eb6e8e6 100644 --- a/aio/content/guide/typescript-configuration.md +++ b/aio/content/guide/typescript-configuration.md @@ -23,31 +23,14 @@ guide the compiler as it generates JavaScript files.
- - For details about `tsconfig.json`, see the official [TypeScript wiki](http://www.typescriptlang.org/docs/handbook/tsconfig-json.html).
+The [Setup](guide/setup-local) guide uses the following `tsconfig.json`: - -The [Setup](guide/setup) guide uses the following `tsconfig.json`: - - - { - "compilerOptions": { - "target": "es5", - "module": "commonjs", - "moduleResolution": "node", - "sourceMap": true, - "emitDecoratorMetadata": true, - "experimentalDecorators": true, - "lib": [ "es2015", "dom" ], - "noImplicitAny": true, - "suppressImplicitAnyIndexErrors": true - } - } + 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 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 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 @@ -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: - "suppressImplicitAnyIndexErrors":true + + "suppressImplicitAnyIndexErrors": true - - -The documentation setup sets this flag to `true` as well. - - {@a typings} - - ## TypeScript Typings + Many JavaScript libraries, such as jQuery, the Jasmine testing library, and Angular, extend the JavaScript environment with features and syntax 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 like `Promise` if the target is `es6`. -Since the QuickStart is targeting `es5`, you can override the -list of declaration files to be included: - - - - "lib": ["es2015", "dom"] +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: + - - -Thanks to that, you have all the `es6` typings even when targeting `es5`. - ### Installable typings files + Many libraries—jQuery, Jasmine, and Lodash among them—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 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) 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`. - - -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. +For instance, to install typings for `jasmine` you run `npm install @types/jasmine --save-dev`. {@a target} @@ -156,5 +116,4 @@ QuickStart doesn't require these typings but many of the samples do. ### *target* -By default, the target is `es5`, you can configure the target to `es6` if you only want to deploy the application to -es6 compatible browser. But if you configure the target to `es6` in some old browser such as `IE`, `Syntax Error` will be thrown. +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.