docs: update CLI strict mode documentation (#39054)

With this change we update the strict mode documentation to reflect the
changes done in the CLI. (https://github.com/angular/angular-cli/pull/18931)

Changes effect
- Removing `no-any` tslint rule
- The special sideEffects  package.json
- Added `strictTemplates` NGC option

PR Close #39054
This commit is contained in:
Alan Agius 2020-09-30 10:03:16 +02:00 committed by Joey Perrott
parent 79620f5139
commit bd5e425c14
2 changed files with 4 additions and 21 deletions

View File

@ -95,7 +95,6 @@ Angular components, templates, and styles go here.
| `app/app.component.css` | Defines the base CSS stylesheet for the root `AppComponent`. |
| `app/app.component.spec.ts` | Defines a unit test for the root `AppComponent`. |
| `app/app.module.ts` | Defines the root module, named `AppModule`, that tells Angular how to assemble the application. Initially declares only the `AppComponent`. As you add more components to the app, they must be declared here. |
| `app/package.json` | This file is generated only in applications created using `--strict` mode. This file is not used by package managers. It is used to tell the tools and bundlers whether the code under this directory is free of non-local [side-effects](guide/strict-mode#side-effect). |
### Application configuration files

View File

@ -1,17 +1,15 @@
# Strict mode
When you create a new workspace or a project you have an option to create them in a strict mode using the `--strict` flag.
When you create a new workspace or an application you have an option to create them in a strict mode using the `--strict` flag.
Enabling this flag initializes your new workspace or project with a few new settings that improve maintainability, help you catch bugs ahead of time, and allow the CLI to perform advanced optimizations on your application.
Enabling this flag initializes your new workspace or application with a few new settings that improve maintainability, help you catch bugs ahead of time.
Additionally, applications that use these stricter settings are easier to statically analyze, which can help the `ng update` command refactor code more safely and precisely when you are updating to future versions of Angular.
Specifically, the `strict` flag does the following:
* Enables [`strict` mode in TypeScript](https://www.staging-typescript.org/tsconfig#strict), as well as other strictness flags recommended by the TypeScript team. Specifically, `forceConsistentCasingInFileNames`, `noImplicitReturns`, `noFallthroughCasesInSwitch`.
* Turns on strict Angular compiler flags [`strictTemplates`](guide/angular-compiler-options#stricttemplates) and [`strictInjectionParameters`](guide/angular-compiler-options#strictinjectionparameters)
* [Bundle size budgets](guide/build#configuring-size-budgets) have been reduced by ~75%
* Turns on [`no-any` tslint rule](https://palantir.github.io/tslint/rules/no-any/) to prevent declarations of type `any`
* [Marks your application as side-effect free](https://webpack.js.org/guides/tree-shaking/#mark-the-file-as-side-effect-free) to enable more advanced tree-shaking
* Turns on strict Angular compiler flags [`strictTemplates`](guide/angular-compiler-options#stricttemplates), [`strictInjectionParameters`](guide/angular-compiler-options#strictinjectionparameters) and [`strictTemplates`](guide/angular-compiler-options#stricttemplates).
* [Bundle size budgets](guide/build#configuring-size-budgets) have been reduced by ~75%.
You can apply these settings at the workspace and project level.
@ -30,17 +28,3 @@ To create a new application in the strict mode within an existing non-strict wor
ng generate application [project-name] --strict
</code-example>
{@a side-effect}
### Non-local side effects in applications
When you create projects and workspaces using the `strict` mode, you'll notice an additional `package.json` file, located in `src/app/` directory.
This file informs tools and bundlers that the code under this directory is free of non-local side effects. Non-local side effects in the application code are not common and using them is not considered a good coding pattern.
More importantly, code with these types of side effects cannot be optimized, resulting in increased bundle sizes and applications that load more slowly.
If you need more information, the following links may be helpful.
* [Tree-shaking](https://webpack.js.org/guides/tree-shaking/)
* [Dealing with side effects and pure functions in JavaScript](https://dev.to/vonheikemen/dealing-with-side-effects-and-pure-functions-in-javascript-16mg)
* [How to deal with dirty side effects in your pure function JavaScript](https://jrsinclair.com/articles/2018/how-to-deal-with-dirty-side-effects-in-your-pure-functional-javascript/)