docs(misc): add more content to Nx and ... guides

docs/map.json

@@ -1560,6 +1560,16 @@
             "name": "Using Apollo GraphQL",
             "id": "apollo-react",
             "file": "shared/examples/apollo-react"
+          },
+          {
+            "name": "Large Repo and Caching",
+            "id": "caching",
+            "file": "shared/examples/caching"
+          },
+          {
+            "name": "Large Repo and DTE",
+            "id": "dte",
+            "file": "shared/examples/dte"
           }
         ]
       }

docs/shared/configuration/angularjson.md

@@ -281,7 +281,7 @@ The following is an expanded version showing all options. Your `nx.json` will li
   },
   "tasksRunnerOptions": {
     "default": {
-      "runner": "@nrwl/workspace/tasks-runners/default",
+      "runner": "@nrwl/workspace/tasks-runners",
       "options": {
         "cacheableOperations": ["build", "lint", "test", "e2e"]
       }
@@ -412,7 +412,7 @@ named "default" is used by default. Specify a different one like
 this `nx run-many --target=build --all --runner=another`.
 
 Tasks runners can accept different options. The following are the options supported
-by `"@nrwl/workspace/tasks-runners/default"` and `"@nrwl/nx-cloud"`.
+by `"@nrwl/workspace/tasks-runners"` and `"@nrwl/nx-cloud"`.
 
 - `cacheableOperations` defines the list of targets/operations that are cached by Nx.
 - `parallel` defines the max number of targets ran in parallel (in older versions of Nx you had to
@@ -434,7 +434,7 @@ by `"@nrwl/workspace/tasks-runners/default"` and `"@nrwl/nx-cloud"`.
 {
   "tasksRunnerOptions": {
     "default": {
-      "runner": "@nrwl/workspace/tasks-runners/default",
+      "runner": "@nrwl/workspace/tasks-runners",
       "options": {
         "cacheableOperations": ["build", "lint", "test", "e2e"],
         "runtimeCacheInputs": ["node -v"]

docs/shared/configuration/packagejson.md

@@ -186,7 +186,7 @@ The following is an expanded version showing all options. Your `nx.json` will li
   },
   "tasksRunnerOptions": {
     "default": {
-      "runner": "@nrwl/workspace/tasks-runners/default",
+      "runner": "@nrwl/workspace/tasks-runners",
       "options": {
         "cacheableOperations": ["build", "lint", "test", "e2e"]
       }
@@ -316,7 +316,7 @@ Tasks runners are invoked when you run `nx test`, `nx build`, `nx run-many`, `nx
 named "default" is used by default. Specify a different one like this `nx run-many --target=build --all --runner=another`.
 
 Tasks runners can accept different options. The following are the options supported
-by `"@nrwl/workspace/tasks-runners/default"` and `"@nrwl/nx-cloud"`.
+by `"@nrwl/workspace/tasks-runners"` and `"@nrwl/nx-cloud"`.
 
 - `cacheableOperations` defines the list of targets/operations that are cached by Nx.
 - `parallel` defines the max number of targets ran in parallel (in older versions of Nx you had to
@@ -338,7 +338,7 @@ by `"@nrwl/workspace/tasks-runners/default"` and `"@nrwl/nx-cloud"`.
 {
   "tasksRunnerOptions": {
     "default": {
-      "runner": "@nrwl/workspace/tasks-runners/default",
+      "runner": "@nrwl/workspace/tasks-runners",
       "options": {
         "cacheableOperations": ["build", "lint", "test", "e2e"],
         "runtimeCacheInputs": ["node -v"]

docs/shared/configuration/projectjson.md

@@ -267,7 +267,7 @@ The following is an expanded version showing all options. Your `nx.json` will li
   },
   "tasksRunnerOptions": {
     "default": {
-      "runner": "@nrwl/workspace/tasks-runners/default",
+      "runner": "@nrwl/workspace/tasks-runners",
       "options": {
         "cacheableOperations": ["build", "lint", "test", "e2e"]
       }
@@ -397,7 +397,7 @@ Tasks runners are invoked when you run `nx test`, `nx build`, `nx run-many`, `nx
 named "default" is used by default. Specify a different one like this `nx run-many --target=build --all --runner=another`.
 
 Tasks runners can accept different options. The following are the options supported
-by `"@nrwl/workspace/tasks-runners/default"` and `"@nrwl/nx-cloud"`.
+by `"@nrwl/workspace/tasks-runners"` and `"@nrwl/nx-cloud"`.
 
 - `cacheableOperations` defines the list of targets/operations that are cached by Nx.
 - `parallel` defines the max number of targets ran in parallel (in older versions of Nx you had to
@@ -419,7 +419,7 @@ by `"@nrwl/workspace/tasks-runners/default"` and `"@nrwl/nx-cloud"`.
 {
   "tasksRunnerOptions": {
     "default": {
-      "runner": "@nrwl/workspace/tasks-runners/default",
+      "runner": "@nrwl/workspace/tasks-runners",
       "options": {
         "cacheableOperations": ["build", "lint", "test", "e2e"],
         "runtimeCacheInputs": ["node -v"]

docs/shared/examples/caching.md

@@ -0,0 +1,10 @@
+# File Large Next.js Apps Made Faster by Using Nx
+
+Repo contains:
+
+- 5 shared buildable packages/libraries with 250 components each
+- 5 Next.js applications built out of 20 app-specific libraries. Each app-specific lib has 250 components each. Each library uses the shared components.
+
+The repo shows how Nx works in a large workspace. It also benchmarks Nx and explains the optimisations Nx uses to be fast.
+
+**Repository:** [vsavkin/large-monorepo](https://github.com/vsavkin/large-monorepo)

docs/shared/examples/dte.md

@@ -0,0 +1,10 @@
+# Distributed Task Execution at Scale
+
+Repo contains:
+
+- 5 shared buildable packages/libraries with 250 components each
+- 5 Next.js applications built out of 20 app-specific libraries. Each app-specific lib has 250 components each. Each library uses the shared components.
+
+The repo shows how Nx distributed task execution can make the CI 16 times faster with a small configuration change.
+
+**Repository:** [vsavkin/interstellar](https://github.com/vsavkin/interstellar)

docs/shared/getting-started/intro.md

@@ -22,8 +22,9 @@ These guides will help you get started:
 - [Adding Nx to an existing monorepo](/migration/adding-to-monorepo)
 - [Using Nx without plugins](/getting-started/nx-core)
 - [Nx and TypeScript](/getting-started/nx-and-typescript)
-- [Nx and React](/default/getting-started/nx-and-react)
-- [Nx and Angular](/default/getting-started/nx-and-angular)
+- [Nx and React](/getting-started/nx-and-react)
+- [Nx and Angular](/getting-started/nx-and-angular)
+- [CI Overview](/using-nx/ci-overview)
 
 ## Features
 
@@ -50,6 +51,6 @@ These guides will help you get started:
 
 - [Using Nx without plugins](/getting-started/nx-core)
 - [Nx and TypeScript](/getting-started/nx-and-typescript)
-- [React: Interactive Nx Tutorial (with videos)](/default/react-tutorial/01-create-application)
-- [Node: Interactive Nx Tutorial (with videos)](/default/node-tutorial/01-create-application)
-- [Angular: Interactive Nx Tutorial (with videos)](/default/angular-tutorial/01-create-application)
+- [React: Interactive Nx Tutorial (with videos)](/react-tutorial/01-create-application)
+- [Node: Interactive Nx Tutorial (with videos)](/node-tutorial/01-create-application)
+- [Angular: Interactive Nx Tutorial (with videos)](/angular-tutorial/01-create-application)

docs/shared/getting-started/nx-and-angular.md

@@ -1,9 +1,90 @@
-# Intro to Nx
+# Nx and Angular
 
-## 10-Minute Nx Overview
+Nx is a smart, fast and extensible build system with first class monorepo support and powerful integrations. It has a powerful core and a rich plugin ecosystem.
 
-<iframe width="560" height="315" src="https://www.youtube.com/embed/cXOkmOy-8dk" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; fullscreen"></iframe>
+## Making Things Fast
 
-## Learn Nx Fundamentals
+If you're only interested in improving the performance of your monorepo by using Nx's [affected:\* commands](/using-nx/affected), [computation cache](/using-nx/cache), and [distributed task execution](/using-nx/dte), then you don't need to use any plugins. Everything will work the same way whether your monorepo has React, Vue, Svelte, or even Go, Rust, or Java apps. Nx is technology-agnostic.
 
+Check out the following guides to get started:
+
+- [Installing Nx CLI & creating a new Nx Workspace](/{{framework}}/getting-started/nx-setup)
+- [Adding Nx to an existing monorepo](/{{framework}}/migration/adding-to-monorepo)
+- [Adding Nx to an Angular CLI project](/{{framework}}/migration/migration-angular)
+- [Migrating from AngularJS](/{{framework}}/migration/migration-angularjs)
+- [Using Nx without plugins](/{{framework}}/getting-started/nx-core)
+- [CI Overview](/using-nx/ci-overview)
+
+It is also a good idea to read the [mental model guide](/using-nx/mental-model) to understand how Nx works.
+
+## Nx and Angular Plugins
+
+Nx plugins helps you develop [Angular](/{{framework}}/angular/overview) applications with fully integrated support for
+modern tools and libraries like [Jest](/{{framework}}/jest/overview), [Cypress](/{{framework}}/cypress/overview),
+[ESLint](/{{framework}}/linter/eslint), Storybook, [NgRx](/angular/guides/misc-ngrx) and more.
+
+### 10-min Video Overview
+
+<iframe width="560" height="315" src="https://www.youtube.com/embed/sNz-4PUM0k8" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; fullscreen"></iframe>
+
+Check out the following to get started:
+
+- [Angular: Interactive Nx Tutorial (with videos)](/angular-tutorial/01-create-application)
 - [Free Nx Course on YouTube](https://www.youtube.com/watch?time_continue=49&v=2mYLe9Kp9VM&feature=emb_logo)
+
+## Nx and Angular CLI
+
+**If you add Nx to an Angular CLI project, `ng` and `nx` are interchangeable (they invoke the same command). So anywhere you see `"nx build"` or `"nx affected"`, you can also use `"ng build"` or `"ng affected"`.**
+
+Nx integrates well with the Angular CLI:
+
+- It decorates the Angular CLI. After adding Nx to your workspace, running `ng` will run the wrapped Angular CLI that goes through Nx. Everything will work the same way but a lot faster.
+- It supports all Angular Devkit builders and schematics.
+- It supports using `angular.json` to configure projects and their targets.
+- Nx Console works with Angular CLI projects.
+
+This works so well that often folks don't even know they use Nx.
+
+## Angular CLI, however, has some limitations, and Nx addresses them.
+
+### angular.json is too long
+
+Nx allows you to split `angular.json` into multiple configuration files (one for each project). This is a big deal for large workspaces where `angular.json` can be thousands of lines long.
+
+This is how you do it:
+
+- Change the version number in `angular.json` to `2`
+- Run `nx format`
+- Run `nx generate @nrwl/workspace:convert-to-nx-project --all=true`
+
+Note that even though the configuration is split, everything works the same way. All migrations and schematics that expect a single `angular.json` file, will receive a single file. Nx is smart, so it merges all the files in memory to make those migrations and schematics work.
+
+### 'ng update' and 'nx migrate'
+
+If you haven't used Nx before and used the Angular CLI, you probably ran `ng update`. What is the difference?
+
+`nx migrate` is a much improved version of `ng update`. It runs the same migrations, but allows you to:
+
+- Rerun the same migration multiple times.
+- Reorder migrations.
+- Skip migrations.
+- Fix migrations that "almost work".
+- Commit a partially migrated state.
+- Change versions of packages to match org requirements.
+
+And, in general, it is lot more reliable for non-trivial workspaces. Why?
+
+`ng update` tries to perform migration in a single go, automatically. This doesn't work for most non-trivial workspaces.
+
+- `ng update` doesn't separate updating `package.json` from updating the source code of the repo. It all happens in a single go. This often fails for non-trivial workspaces or for organizations that have a custom npm registry, where you might want to use a different version of a package.
+- `ng update` relies on `peerDependencies` to figure out what needs to be updated. Many third-party plugin don't have `peerDependencies` set correctly.
+- When using `ng update` it is difficult to execute one migration at a time. Sometimes you want to patch things up after executing a migration.
+- When using `ng update` it's not possible to fix almost-working migrations. We do our best but sometimes we don't account for the specifics of a particular workspace.
+- When using `ng update` it's not possible to commit a partially-migrated repo. Migration can take days for a large repo.
+- When using `ng update` it's not possible to rerun some of the migrations multiple times. This is required because you can rebase the branch multiple times while migrating.
+
+The Nx core team have gained a lot of experience migrating large workspaces over the last 5 years, and `nx migrate` has been consistently a lot more reliable and easier to use. It has also been a lot easier to implement migrations that work with `nx migrate` comparing to `ng update`. As a result, folks building React and Node applications with Nx have had better experience migrating because Angular folks use `ng update` out of habit, instead of using the command that works better.
+
+**Starting with Nx 11, you can migrate workspaces only using `nx migrate`**. To reiterate: `nx migrate` runs the migrations written by the Angular CLI team the same way `ng update` runs them. So everything should still work. You just get more control over how it works.
+
+If you still want to run `ng update`, you can do it as follows: `FORCE_NG_UPDATE=true nx update mypackage`.

docs/shared/getting-started/nx-and-react.md

@@ -1,10 +1,33 @@
 # Nx and React
 
-## 10-Minute Nx Overview
+Nx is a smart, fast and extensible build system with first class monorepo support and powerful integrations. It has a powerful core and a rich plugin ecosystem.
+
+## Making Things Fast
+
+If you're only interested in improving the performance of your monorepo by using Nx's [affected:\* commands](/using-nx/affected), [computation cache](/using-nx/cache), and [distributed task execution](/using-nx/dte), then you don't need to use any plugins. Everything will work the same way whether your monorepo has React, Vue, Svelte, or even Go, Rust, or Java apps. Nx is technology-agnostic.
+
+Check out the following guides to get started:
+
+- [Installing Nx CLI & creating a new Nx Workspace](/{{framework}}/getting-started/nx-setup)
+- [Adding Nx to an existing monorepo](/{{framework}}/migration/adding-to-monorepo)
+- [Migrating from CRA](/{{framework}}/migration/migration-cra)
+- [Using Nx without plugins](/{{framework}}/getting-started/nx-core)
+- [CI Overview](/using-nx/ci-overview)
+
+It is also a good idea to read the [mental model guide](/using-nx/mental-model) to understand how Nx works.
+
+## Nx and React Plugins
+
+Nx plugins help you develop [React](/{{framework}}/react/overview) applications with fully integrated support for modern tools
+and libraries like [Jest](/{{framework}}/jest/overview), [Cypress](/{{framework}}/cypress/overview),
+Storybook, [ESLint](/{{framework}}/linter/eslint), and more. Nx also supports React
+frameworks like [Gatsby](/{{version}}/react/gatsby/overview), [Next.js](/{{version}}/react/guides/nextjs), Remix, and has great support for React Native.
+
+### 10-min Video Overview
 
 <iframe width="560" height="315" src="https://www.youtube.com/embed/sNz-4PUM0k8" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; fullscreen"></iframe>
 
-## Learn
+Check out the following to get started:
 
+- [React: Interactive Nx Tutorial (with videos)](/react-tutorial/01-create-application)
 - [Free Nx Course on Egghead: Scale React Development with Nx](https://egghead.io/playlists/scale-react-development-with-nx-4038)
-- [45-Minute Walkthrough](https://www.youtube.com/watch?v=jCf92IyR-GE)

docs/shared/getting-started/nx-setup.md

@@ -44,7 +44,7 @@ If you have an existing Create React App project, you can gain the benefits of N
 npx cra-to-nx
 ```
 
-For more information on adding Nx to an existing repository see the [migration guide](/default/migration/migration-cra)
+For more information on adding Nx to an existing repository see the [migration guide](/migration/migration-cra)
 
 ## Install Nx CLI
 

docs/shared/guides/nextjs.md

@@ -240,7 +240,7 @@ You can share React components between multiple Next.js applications. You can al
 
 Once you are ready to deploy your Next.js application, you have absolute freedom to choose any hosting provider that fits your needs.
 
-You may know that the company behind Next.js, Vercel, has a great hosting platform offering that is developed in tandem with Next.js itself to offer a great overall developer and user experience. We have detailed [how to deploy your Next.js application to Vercel in a separate guide](/default/guides/deploy-nextjs-to-vercel).
+You may know that the company behind Next.js, Vercel, has a great hosting platform offering that is developed in tandem with Next.js itself to offer a great overall developer and user experience. We have detailed [how to deploy your Next.js application to Vercel in a separate guide](/guides/deploy-nextjs-to-vercel).
 
 ## Resources
 

docs/shared/guides/storybook/plugin-angular.md

@@ -193,5 +193,5 @@ For more on using Storybook, see the [official Storybook documentation](https://
 
 Here's more information on common migration scenarios for Storybook with Nx. For Storybook specific migrations that are not automatically handled by Nx please refer to the [official Storybook page](https://storybook.js.org/)
 
-- [Upgrading to Storybook 6](/default/storybook/upgrade-storybook-v6-angular)
-- [Migrate to the new Storybook `webpackFinal` config](/default/storybook/migrate-webpack-final-angular)
+- [Upgrading to Storybook 6](/storybook/upgrade-storybook-v6-angular)
+- [Migrate to the new Storybook `webpackFinal` config](/storybook/migrate-webpack-final-angular)

docs/shared/guides/storybook/plugin-react.md

@@ -199,5 +199,5 @@ For more on using Storybook, see the [official Storybook documentation](https://
 
 Here's more information on common migration scenarios for Storybook with Nx. For Storybook specific migrations that are not automatically handled by Nx please refer to the [official Storybook page](https://storybook.js.org/)
 
-- [Upgrading to Storybook 6](/default/storybook/upgrade-storybook-v6-react)
-- [Migrate to the Nrwl React Storybook Preset](/default/storybook/migrate-webpack-final-react)
+- [Upgrading to Storybook 6](/storybook/upgrade-storybook-v6-react)
+- [Migrate to the Nrwl React Storybook Preset](/storybook/migrate-webpack-final-react)

docs/shared/nx-core.md

@@ -49,7 +49,7 @@ package.json
   "npmScope": "myorg",
   "tasksRunnerOptions": {
     "default": {
-      "runner": "@nrwl/workspace/tasks-runners/default",
+      "runner": "@nrwl/workspace/tasks-runners",
       "options": {
         "cacheableOperations": ["build", "lint", "test", "e2e"]
       }

docs/shared/react-plugin.md

@@ -71,7 +71,7 @@ myorg/
 
 - [Using Cypress](/cypress/overview)
 - [Using Jest](/jest/overview)
-- [Using Storybook](/default/storybook/overview-react)
+- [Using Storybook](/storybook/overview-react)
 
 ## Executors / Builders
 

nx-dev/nx-dev/public/documentation/latest/angular/api-angular/generators/library.md

@@ -155,6 +155,14 @@ Type: `boolean`
 
 Skip formatting files.
 
+### skipModule
+
+Default: `false`
+
+Type: `boolean`
+
+Whether to skip the creation of a default module when generating the library.
+
 ### skipPackageJson
 
 Default: `false`

nx-dev/nx-dev/public/documentation/latest/angular/api-js/executors/swc.md

@@ -43,6 +43,12 @@ Type: `boolean`
 
 Whether to skip TypeScript type checking.
 
+### swcExclude
+
+Type: `array`
+
+List of SWC Glob/Regex to be excluded from compilation (https://swc.rs/docs/configuration/compilation#exclude)
+
 ### watch
 
 Default: `false`

nx-dev/nx-dev/public/documentation/latest/default/api-angular/generators/library.md

@@ -155,6 +155,14 @@ Type: `boolean`
 
 Skip formatting files.
 
+### skipModule
+
+Default: `false`
+
+Type: `boolean`
+
+Whether to skip the creation of a default module when generating the library.
+
 ### skipPackageJson
 
 Default: `false`

nx-dev/nx-dev/public/documentation/latest/default/api-js/executors/swc.md

@@ -43,6 +43,12 @@ Type: `boolean`
 
 Whether to skip TypeScript type checking.
 
+### swcExclude
+
+Type: `array`
+
+List of SWC Glob/Regex to be excluded from compilation (https://swc.rs/docs/configuration/compilation#exclude)
+
 ### watch
 
 Default: `false`

nx-dev/nx-dev/public/documentation/latest/map.json

@@ -1560,6 +1560,16 @@
             "name": "Using Apollo GraphQL",
             "id": "apollo-react",
             "file": "shared/examples/apollo-react"
+          },
+          {
+            "name": "Large Repo and Caching",
+            "id": "caching",
+            "file": "shared/examples/caching"
+          },
+          {
+            "name": "Large Repo and DTE",
+            "id": "dte",
+            "file": "shared/examples/dte"
           }
         ]
       }