From cb566add3cfcd0e8a7b5dc339b3678c9636705a7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20Shevitz=20=F0=9F=94=B5?= Date: Mon, 8 Jun 2020 16:59:30 +0000 Subject: [PATCH] docs: Add content for new `strict` mode for Angular CLI (#37486) In v10, the Angular CLI supports a strict mode, which turns on additional flags for the TypeScript and Angular compilers. PR Close #37486 --- aio/content/guide/file-structure.md | 8 ++- aio/content/guide/setup-local.md | 57 ++++++++++--------- aio/content/guide/strict-mode.md | 46 +++++++++++++++ aio/content/guide/typescript-configuration.md | 4 ++ aio/content/guide/workspace-config.md | 5 ++ aio/content/navigation.json | 5 ++ 6 files changed, 98 insertions(+), 27 deletions(-) create mode 100644 aio/content/guide/strict-mode.md diff --git a/aio/content/guide/file-structure.md b/aio/content/guide/file-structure.md index 0371550b5d..7ab41fb351 100644 --- a/aio/content/guide/file-structure.md +++ b/aio/content/guide/file-structure.md @@ -78,6 +78,12 @@ Files at the top level of `src/` support testing and running your application. S | `styles.sass` | Lists CSS files that supply styles for a project. The extension reflects the style preprocessor you have configured for the project. | | `test.ts` | The main entry point for your unit tests, with some Angular-specific configuration. You don't typically need to edit this file. | +
+ +If you create an application using Angular's strict mode, you will also have an additional `package.json` file in the `src/app` directory. For more information, see [Strict mode](/guide/strict-mode). + +
+ {@a app-src} Inside the `src/` folder, the `app/` folder contains your project's logic and data. @@ -90,7 +96,7 @@ 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](https://webpack.js.org/guides/tree-shaking/#mark-the-file-as-side-effect-free). | +| `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 diff --git a/aio/content/guide/setup-local.md b/aio/content/guide/setup-local.md index daaaf9c256..da0131b392 100644 --- a/aio/content/guide/setup-local.md +++ b/aio/content/guide/setup-local.md @@ -25,49 +25,48 @@ To use the Angular framework, you should be familiar with the following: Knowledge of [TypeScript](https://www.typescriptlang.org/) is helpful, but not required. +To install Angular on your local system, you need the following: + {@a nodejs} -### Node.js -Make sure your development environment includes `Node.js®` and an npm package manager. +* **Node.js** + + Angular requires a [current, active LTS, or maintenance LTS](https://nodejs.org/about/releases) version of Node.js. -Angular requires a [current, active LTS, or maintenance LTS](https://nodejs.org/about/releases/) version of `Node.js`. See the `engines` key for the specific version requirements in our [package.json](https://unpkg.com/@angular/cli/package.json). +
-* To check your version, run `node -v` in a terminal/console window. + For information about specific version requirements, see the `engines` key in the [package.json](https://unpkg.com/@angular/cli/package.json) file. -* To get `Node.js`, go to [nodejs.org](https://nodejs.org "Nodejs.org"). +
+ + For more information on installing Node.js, see [nodejs.org](http://nodejs.org "Nodejs.org"). + If you are unsure what version of Node.js runs on your system, run `node -v` in a terminal window. {@a npm} -### npm package manager -Angular, the Angular CLI, and Angular apps depend on features and functionality provided by libraries that are available as [npm packages](https://docs.npmjs.com/getting-started/what-is-npm). To download and install npm packages, you must have an npm package manager. +* **npm package manager** -This setup guide uses the [npm client](https://docs.npmjs.com/cli/install) command line interface, which is installed with `Node.js` by default. - -To check that you have the npm client installed, run `npm -v` in a terminal/console window. + Angular, the Angular CLI, and Angular applications depend on [npm packages](https://docs.npmjs.com/getting-started/what-is-npm) for many features and functions. + To download and install npm packages, you need an npm package manager. + This guide uses the [npm client](https://docs.npmjs.com/cli/install) command line interface, which is installed with `Node.js` by default. + To check that you have the npm client installed, run `npm -v` in a terminal window. {@a install-cli} -## Step 1: Install the Angular CLI +## Install the Angular CLI -You use the Angular CLI -to create projects, generate application and library code, and perform a variety of ongoing development tasks such as testing, bundling, and deployment. - -Install the Angular CLI globally. - -To install the CLI using `npm`, open a terminal/console window and enter the following command: +You use the Angular CLI to create projects, generate application and library code, and perform a variety of ongoing development tasks such as testing, bundling, and deployment. +To install the Angular CLI, open a terminal window and run the following command: npm install -g @angular/cli - - - {@a create-proj} -## Step 2: Create a workspace and initial application +## Create a workspace and initial application You develop apps in the context of an Angular [**workspace**](guide/glossary#workspace). @@ -86,16 +85,22 @@ The Angular CLI installs the necessary Angular npm packages and other dependenci The CLI creates a new workspace and a simple Welcome app, ready to run. +
+ +You also have the option to use Angular's strict mode, which can help you write better, more maintainable code. +For more information, see [Strict mode](/guide/strict-mode). + +
{@a serve} -## Step 3: Run the application +## Run the application -The Angular CLI includes a server, so that you can easily build and serve your app locally. +The Angular CLI includes a server, so that you can build and serve your app locally. -1. Go to the workspace folder (`my-app`). +1. Navigate to the workspace folder, such as `my-app`. -1. Launch the server by using the CLI command `ng serve`, with the `--open` option. +1. Run the following command: cd my-app @@ -108,7 +113,7 @@ and rebuilds the app as you make changes to those files. The `--open` (or just `-o`) option automatically opens your browser to `http://localhost:4200/`. -You will see: +If your installation and setup was successful, you should see a page similar to the following.
diff --git a/aio/content/guide/strict-mode.md b/aio/content/guide/strict-mode.md new file mode 100644 index 0000000000..3cfe153cb9 --- /dev/null +++ b/aio/content/guide/strict-mode.md @@ -0,0 +1,46 @@ +# 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. + +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. +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 + +You can apply these settings at the workspace and project level. + +To create a new workspace and application using the strict mode, run the following command: + + + +ng new [project-name] --strict + + + +To create a new application in the strict mode within an existing non-strict workspace, run the following command: + + + +ng generate application [project-name] --strict + + + +{@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/) \ No newline at end of file diff --git a/aio/content/guide/typescript-configuration.md b/aio/content/guide/typescript-configuration.md index b278741a95..3561008b20 100644 --- a/aio/content/guide/typescript-configuration.md +++ b/aio/content/guide/typescript-configuration.md @@ -79,6 +79,10 @@ The initial `tsconfig.base.json` for an Angular workspace typically looks like t } +### Strict mode + +When you create new workspaces and projects, you have the option to use Angular's strict mode, which can help you write better, more maintainable code. +For more information, see [Strict mode](/guide/strict-mode). {@a noImplicitAny} diff --git a/aio/content/guide/workspace-config.md b/aio/content/guide/workspace-config.md index 9d355e8130..360c3b3219 100644 --- a/aio/content/guide/workspace-config.md +++ b/aio/content/guide/workspace-config.md @@ -41,6 +41,11 @@ When you create a library project with `ng generate library`, the library projec
+## Strict mode + +When you create new workspaces and projects, you have the option to use Angular's strict mode, which can help you write better, more maintainable code. +For more information, see [Strict mode](/guide/strict-mode). + ## Project configuration options The following top-level configuration properties are available for each project, under `projects:`. diff --git a/aio/content/navigation.json b/aio/content/navigation.json index feb111528e..11e93c4da8 100644 --- a/aio/content/navigation.json +++ b/aio/content/navigation.json @@ -675,6 +675,11 @@ "url": "guide/browser-support", "title": "Browser Support", "tooltip": "Browser support and polyfills guide." + }, + { + "url": "guide/strict-mode", + "title": "Strict mode", + "tooltip": "Reference documentation for Angular's strict mode." } ] },