diff --git a/aio/content/guide/angular-compiler-options.md b/aio/content/guide/angular-compiler-options.md index caab12c89a..79b39fd8e9 100644 --- a/aio/content/guide/angular-compiler-options.md +++ b/aio/content/guide/angular-compiler-options.md @@ -1,6 +1,6 @@ # Angular compiler options -When you use [AOT compilation](guide/aot-compiler), you can control how your application is compiled by specifying *template* compiler options in the `tsconfig.json` [TypeScript configuration file](guide/typescript-configuration). +When you use [AOT compilation](guide/aot-compiler), you can control how your application is compiled by specifying *template* compiler options in the [TypeScript configuration file](guide/typescript-configuration). The template options object, `angularCompilerOptions`, is a sibling to the `compilerOptions` object that supplies standard options to the TypeScript compiler. @@ -21,11 +21,11 @@ The template options object, `angularCompilerOptions`, is a sibling to the `comp {@a tsconfig-extends} ## Configuration inheritance with extends -Like the TypeScript compiler, The Angular AOT compiler also supports `extends` in the `angularCompilerOptions` section of the TypeScript configuration file, `tsconfig.json`. +Like the TypeScript compiler, The Angular AOT compiler also supports `extends` in the `angularCompilerOptions` section of the TypeScript configuration file. The `extends` property is at the top level, parallel to `compilerOptions` and `angularCompilerOptions`. A TypeScript configuration can inherit settings from another file using the `extends` property. -The configuration options from the base file are loaded first, then overridden by those in the inheriting `tsconfig` file. +The configuration options from the base file are loaded first, then overridden by those in the inheriting configuration file. For example: diff --git a/aio/content/guide/aot-compiler.md b/aio/content/guide/aot-compiler.md index ee55630756..0367adf8dd 100644 --- a/aio/content/guide/aot-compiler.md +++ b/aio/content/guide/aot-compiler.md @@ -105,7 +105,7 @@ For help in understanding and resolving these problems, see [AOT Metadata Errors ### Configuring AOT compilation -You can provide options in the `tsconfig.json` [TypeScript configuration file](guide/typescript-configuration) that control the compilation process. See [Angular compiler options](guide/angular-compiler-options) for a complete list of available options. +You can provide options in the [TypeScript configuration file](guide/typescript-configuration) that controls the compilation process. See [Angular compiler options](guide/angular-compiler-options) for a complete list of available options. ## Phase 1: Code analysis @@ -211,7 +211,7 @@ The compiler later reports the error if it needs that piece of metadata to gener
- If you want `ngc` to report syntax errors immediately rather than produce a `.metadata.json` file with errors, set the `strictMetadataEmit` option in the TypeScript configuration file, `tsconfig.json`. + If you want `ngc` to report syntax errors immediately rather than produce a `.metadata.json` file with errors, set the `strictMetadataEmit` option in the TypeScript configuration file. ``` "angularCompilerOptions": { @@ -548,7 +548,7 @@ It does not, however, rewrite the `.d.ts` file, so TypeScript doesn't recognize One of the Angular compiler's most helpful features is the ability to type-check expressions within templates, and catch any errors before they cause crashes at runtime. In the template type-checking phase, the Angular template compiler uses the TypeScript compiler to validate the binding expressions in templates. -Enable this phase explicitly by adding the compiler option `"fullTemplateTypeCheck"` in the `"angularCompilerOptions"` of the project's `tsconfig.json` +Enable this phase explicitly by adding the compiler option `"fullTemplateTypeCheck"` in the `"angularCompilerOptions"` of the project's TypeScript configuration file (see [Angular Compiler Options](guide/angular-compiler-options)).
diff --git a/aio/content/guide/deployment.md b/aio/content/guide/deployment.md index 4532515c2b..a611a5427b 100644 --- a/aio/content/guide/deployment.md +++ b/aio/content/guide/deployment.md @@ -469,7 +469,7 @@ The following configurations determine your requirements. * TypeScript configuration - In the TypeScript configuration file, `tsconfig.json`, the "target" option in the `compilerOptions` section determines the ECMAScript target version that the code is compiled to. + In the TypeScript configuration file, the "target" option in the `compilerOptions` section determines the ECMAScript target version that the code is compiled to. Modern browsers support ES2015 natively, while ES5 is more commonly used to support legacy browsers.
diff --git a/aio/content/guide/elements.md b/aio/content/guide/elements.md index f5875823c4..5456de99f9 100644 --- a/aio/content/guide/elements.md +++ b/aio/content/guide/elements.md @@ -117,7 +117,7 @@ The recently-developed [custom elements](https://developer.mozilla.org/en-US/doc -In browsers that support Custom Elements natively, the specification requires developers use ES2015 classes to define Custom Elements - developers can opt-in to this by setting the `target: "es2015"` property in their project's `tsconfig.json`. As Custom Element and ES2015 support may not be available in all browsers, developers can instead choose to use a polyfill to support older browsers and ES5 code. +In browsers that support Custom Elements natively, the specification requires developers use ES2015 classes to define Custom Elements - developers can opt-in to this by setting the `target: "es2015"` property in their project's [TypeScript configuration file](/guide/typescript-configuration). As Custom Element and ES2015 support may not be available in all browsers, developers can instead choose to use a polyfill to support older browsers and ES5 code. Use the [Angular CLI](cli) to automatically set up your project with the correct polyfill: `ng add @angular/elements --name=*your_project_name*`. - For more information about polyfills, see [polyfill documentation](https://www.webcomponents.org/polyfills). diff --git a/aio/content/guide/file-structure.md b/aio/content/guide/file-structure.md index 5671ba7f19..e93618826c 100644 --- a/aio/content/guide/file-structure.md +++ b/aio/content/guide/file-structure.md @@ -40,7 +40,8 @@ The top level of the workspace contains workspace-wide configuration files, conf | `package-lock.json` | Provides version information for all packages installed into `node_modules` by the npm client. See [npm documentation](https://docs.npmjs.com/files/package-lock.json) for details. If you use the yarn client, this file will be [yarn.lock](https://yarnpkg.com/lang/en/docs/yarn-lock/) instead. | | `src/` | Source files for the root-level application project. | | `node_modules/` | Provides [npm packages](guide/npm-packages) to the entire workspace. Workspace-wide `node_modules` dependencies are visible to all projects. | -| `tsconfig.json` | Default [TypeScript](https://www.typescriptlang.org/) configuration for projects in the workspace. | +| `tsconfig.json` | The `tsconfig.json` file is a ["Solution Style"](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-9.html#support-for-solution-style-tsconfigjson-files) TypeScript configuration file. Code editors and TypeScript’s language server use this file to improve development experience. Compilers do not use this file. | +| `tsconfig.base.json` | The base [TypeScript](https://www.typescriptlang.org/) configuration for projects in the workspace. All other configuration files inherit from this base file. For more information, see the [Configuration inheritance with extends](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html#configuration-inheritance-with-extends) section of the TypeScript documentation.| | `tslint.json` | Default [TSLint](https://palantir.github.io/tslint/) configuration for projects in the workspace. | @@ -95,7 +96,7 @@ Angular components, templates, and styles go here. The application-specific configuration files for the root application reside at the workspace root level. For a multi-project workspace, project-specific configuration files are in the project root, under `projects/project-name/`. -Project-specific [TypeScript](https://www.typescriptlang.org/) configuration files inherit from the workspace-wide `tsconfig.json`, and project-specific [TSLint](https://palantir.github.io/tslint/) configuration files inherit from the workspace-wide `tslint.json`. +Project-specific [TypeScript](https://www.typescriptlang.org/) configuration files inherit from the workspace-wide `tsconfig.base.json`, and project-specific [TSLint](https://palantir.github.io/tslint/) configuration files inherit from the workspace-wide `tslint.json`. | APPLICATION-SPECIFIC CONFIG FILES | PURPOSE | | :--------------------- | :------------------------------------------| diff --git a/aio/content/guide/glossary.md b/aio/content/guide/glossary.md index bef5582213..5d3c027a13 100644 --- a/aio/content/guide/glossary.md +++ b/aio/content/guide/glossary.md @@ -950,6 +950,10 @@ Many code editors and IDEs support TypeScript either natively or with plug-ins. TypeScript is the preferred language for Angular development. Read more about TypeScript at [typescriptlang.org](http://www.typescriptlang.org/). +## TypeScript configuration file + +A file specifies the root files and the compiler options required to compile a TypeScript project. For more information, see [TypeScript configuration](/guide/typescript-configuration). + {@a U} diff --git a/aio/content/guide/ivy-compatibility.md b/aio/content/guide/ivy-compatibility.md index b86aa858b5..1cf01b49ff 100644 --- a/aio/content/guide/ivy-compatibility.md +++ b/aio/content/guide/ivy-compatibility.md @@ -11,11 +11,11 @@ That said, some applications will likely need to apply some manual updates. In version 9, [a few deprecated APIs have been removed](guide/updating-to-version-9#removals) and there are a [few breaking changes](guide/updating-to-version-9#breaking-changes) unrelated to Ivy. If you're seeing errors after updating to version 9, you'll first want to rule those changes out. -To do so, temporarily [turn off Ivy](guide/ivy#opting-out-of-angular-ivy) in your `tsconfig.json` and re-start your app. +To do so, temporarily [turn off Ivy](guide/ivy#opting-out-of-angular-ivy) in your `tsconfig.base.json` and re-start your app. If you're still seeing the errors, they are not specific to Ivy. In this case, you may want to consult the [general version 9 guide](guide/updating-to-version-9). If you've opted into any of the stricter type-checking settings that are new with v9, you may also want to check out the [template type-checking guide](guide/template-typecheck). -If the errors are gone, switch back to Ivy by removing the changes to the `tsconfig.json` and review the list of expected changes below. +If the errors are gone, switch back to Ivy by removing the changes to the `tsconfig.base.json` and review the list of expected changes below. {@a payload-size-debugging} ### Payload size debugging diff --git a/aio/content/guide/template-typecheck.md b/aio/content/guide/template-typecheck.md index b00834bfe8..efe1b51e57 100644 --- a/aio/content/guide/template-typecheck.md +++ b/aio/content/guide/template-typecheck.md @@ -3,7 +3,7 @@ ## Overview of template type checking Just as TypeScript catches type errors in your code, Angular checks the expressions and bindings within the templates of your application and can report any type errors it finds. -Angular currently has three modes of doing this, depending on the value of the `fullTemplateTypeCheck` and `strictTemplates` flags in the [TypeScript configuration file](guide/typescript-configuration), `tsconfig.json`. +Angular currently has three modes of doing this, depending on the value of the `fullTemplateTypeCheck` and `strictTemplates` flags in the [TypeScript configuration file](guide/typescript-configuration). ### Basic mode @@ -107,7 +107,7 @@ There can also be false positives when the typings of an Angular library are eit In case of a false positive like these, there are a few options: * Use the [`$any()` type-cast function](guide/template-syntax#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 strict checks entirely by setting `strictTemplates: false` in the application's TypeScript configuration file. * 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`. diff --git a/aio/content/guide/typescript-configuration.md b/aio/content/guide/typescript-configuration.md index 08d58b0443..b278741a95 100644 --- a/aio/content/guide/typescript-configuration.md +++ b/aio/content/guide/typescript-configuration.md @@ -15,22 +15,49 @@ that are important to Angular developers, including details about the following {@a tsconfig} -## TypeScript configuration +## Configuration files -A TypeScript configuration file called `tsconfig.json` guides the compiler as it generates JavaScript files for a project. -This file contains options and flags that are essential for Angular applications. -Typically, the file is found at the [root level of the workspace](guide/file-structure). +A given Angular workspace contains several TypeScript configuration files. +At the root level, there are two main TypeScript configuration files: a `tsconfig.json` file and a `tsconfig.base.json` file. + +The `tsconfig.json` file is a ["Solution Style"](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-9.html#support-for-solution-style-tsconfigjson-files) TypeScript configuration file. +Code editors and TypeScript’s language server use this file to improve development experience. +Compilers do not use this file. + +The `tsconfig.json` file contains a list of paths to the other TypeScript configuration files used in the workspace. + + +{ + "files": [], + "references": [ + { + "path": "./tsconfig.app.json" + }, + { + "path": "./tsconfig.spec.json" + }, + { + "path": "./projects/my-lib/tsconfig.lib.json" + } + ] +} + + +The `tsconfig.base.json` file specifies the base TypeScript and Angular compiler options that all projects in the workspace inherit. + +The TypeScript and Angular have a wide range of options which can be used to configure type-checking features and generated output. +For more information, see the [Configuration inheritance with extends](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html#configuration-inheritance-with-extends) section of the TypeScript documentation.
-For details about `tsconfig.json`, see the official -[TypeScript wiki](http://www.typescriptlang.org/docs/handbook/tsconfig-json.html). +For more information TypeScript configuration files, see the official [TypeScript wiki](http://www.typescriptlang.org/docs/handbook/tsconfig-json.html) +For details about configuration inheritance, see the [Configuration inheritance with extends](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html#configuration-inheritance-with-extends) section.
-The initial `tsconfig.json` for an Angular app typically looks like the following example. +The initial `tsconfig.base.json` for an Angular workspace typically looks like the following example. - + { "compileOnSave": false, "compilerOptions": { @@ -40,21 +67,14 @@ The initial `tsconfig.json` for an Angular app typically looks like the followin "declaration": false, "downlevelIteration": true, "experimentalDecorators": true, - "module": "esnext", "moduleResolution": "node", "importHelpers": true, "target": "es2015", - "typeRoots": [ - "node_modules/@types" - ], + "module": "es2020", "lib": [ "es2018", "dom" ] - }, - "angularCompilerOptions": { - "strictTemplates": true, - "strictInjectionParameters": true } } diff --git a/aio/content/guide/universal.md b/aio/content/guide/universal.md index d7b70c5ad9..d9f1bea9df 100644 --- a/aio/content/guide/universal.md +++ b/aio/content/guide/universal.md @@ -48,11 +48,11 @@ src/ app/ ... application code app.server.module.ts * server-side application module server.ts * express web server -tsconfig.json TypeScript client configuration -tsconfig.app.json TypeScript client configuration -tsconfig.server.json * TypeScript server configuration -tsconfig.spec.json TypeScript spec configuration -package.json npm configuration +tsconfig.json TypeScript solution style configuration +tsconfig.base.json TypeScript base configuration +tsconfig.app.json TypeScript browser application configuration +tsconfig.server.json TypeScript server application configuration +tsconfig.spec.json TypeScript tests configuration The files marked with `*` are new and not in the original tutorial sample.