From ef7f0c0d51b18474be2e117a9af8b3dc63ff3b38 Mon Sep 17 00:00:00 2001 From: Juri Date: Fri, 31 Mar 2023 16:50:13 +0200 Subject: [PATCH] docs(core): what is Nx --- CODEOWNERS | 51 ++++--- docs/README.md | 8 +- docs/generated/manifests/menus.json | 101 +++++++++----- docs/generated/manifests/nx.json | 127 ++++++++++++------ docs/map.json | 31 ++++- .../concepts/integrated-vs-package-based.md | 8 +- docs/shared/core-tutorial/01-create-blog.md | 2 +- docs/shared/getting-started/installation.md | 89 ++++++++++++ docs/shared/getting-started/intro.md | 80 ++++++----- docs/shared/getting-started/why-nx.md | 29 ++++ docs/shared/images/nx-architecture.svg | 115 ++++++++++++++++ docs/shared/migration/adding-to-monorepo.md | 2 +- docs/shared/npm-tutorial/integrated.md | 2 +- nx-dev/data-access-menu/src/lib/menu.utils.ts | 1 + nx-dev/nx-dev/redirect-rules.config.js | 24 +++- nx-dev/nx-dev/redirect-rules.config.spec.js | 2 +- packages/cra-to-nx/README.md | 2 +- .../preset/point-to-tutorial-and-course.ts | 6 +- 18 files changed, 533 insertions(+), 147 deletions(-) create mode 100644 docs/shared/getting-started/installation.md create mode 100644 docs/shared/getting-started/why-nx.md create mode 100644 docs/shared/images/nx-architecture.svg diff --git a/CODEOWNERS b/CODEOWNERS index e37d9cce41071..41780b37de0c8 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -1,13 +1,15 @@ # Any file not covered by a rule below, will default to Jason + Victor and a few select others. -* @FrozenPandaz @vsavkin -/packages/**/* @FrozenPandaz @vsavkin @AgentEnder @jaysoo @JamesHenry -/e2e/**/* @FrozenPandaz @vsavkin @AgentEnder @jaysoo @JamesHenry -/scripts/**/* @FrozenPandaz @vsavkin @AgentEnder @jaysoo @JamesHenry -/tools/**/* @FrozenPandaz @vsavkin @AgentEnder @jaysoo @JamesHenry -package.json @FrozenPandaz @vsavkin @AgentEnder @jaysoo @JamesHenry -yarn.lock @FrozenPandaz @vsavkin @AgentEnder @jaysoo @JamesHenry + +- @FrozenPandaz @vsavkin + /packages/**/\* @FrozenPandaz @vsavkin @AgentEnder @jaysoo @JamesHenry + /e2e/**/_ @FrozenPandaz @vsavkin @AgentEnder @jaysoo @JamesHenry + /scripts/\*\*/_ @FrozenPandaz @vsavkin @AgentEnder @jaysoo @JamesHenry + /tools/\*_/_ @FrozenPandaz @vsavkin @AgentEnder @jaysoo @JamesHenry + package.json @FrozenPandaz @vsavkin @AgentEnder @jaysoo @JamesHenry + yarn.lock @FrozenPandaz @vsavkin @AgentEnder @jaysoo @JamesHenry # Docs Site + Graph + /docs @bcabanes @isaacplmann @juristr /docs/nx-cloud @StalkAltan @rarmatei @isaacplmann @juristr @bcabanes /graph/** @philipjfulcher @FrozenPandaz @bcabanes @@ -18,6 +20,7 @@ yarn.lock @FrozenPandaz @vsavkin @AgentEnder @jaysoo @JamesHenry # Plugin Verticals ## Angular + /docs/generated/packages/angular/** @Coly010 @leosvelperez /docs/shared/packages/angular/** @Coly010 @leosvelperez @isaacplmann @juristr /packages/angular/** @Coly010 @leosvelperez @@ -27,9 +30,10 @@ yarn.lock @FrozenPandaz @vsavkin @AgentEnder @jaysoo @JamesHenry /e2e/make-angular-cli-faster/** @leosvelperez @Coly010 /packages/angular/plugins/component-testing.ts @leosvelperez @Coly010 @barbados-clemens /packages/angular/src/generators/cypress-component-configuration/** @leosvelperez @Coly010 @barbados-clemens -/packages/angular/src/generators/component-test/** @leosvelperez @Coly010 @barbados-clemens +/packages/angular/src/generators/component-test/\*\* @leosvelperez @Coly010 @barbados-clemens ## React + /docs/generated/packages/react/** @jaysoo @ndcunningham @mandarini @xiongemi /docs/generated/packages/next/** @jaysoo @ndcunningham @xiongemi /docs/shared/packages/react/** @jaysoo @ndcunningham @mandarini @xiongemi @@ -42,9 +46,10 @@ yarn.lock @FrozenPandaz @vsavkin @AgentEnder @jaysoo @JamesHenry /e2e/cra-to-nx/** @jaysoo @xiongemi @mandarini @ndcunningham /packages/react/plugins/component-testing/** @jaysoo @ndcunningham @barbados-clemens /packages/react/src/generators/cypress-component-configuration/** @jaysoo @ndcunningham @barbados-clemens -/packages/react/src/generators/component-test/** @jaysoo @ndcunningham @barbados-clemens +/packages/react/src/generators/component-test/\*\* @jaysoo @ndcunningham @barbados-clemens # React Native + /docs/generated/packages/detox/** @xiongemi @jaysoo @ndcunningham /docs/generated/packages/expo/** @xiongemi @jaysoo @ndcunningham /docs/generated/packages/react-native/** @xiongemi @jaysoo @ndcunningham @@ -53,16 +58,18 @@ yarn.lock @FrozenPandaz @vsavkin @AgentEnder @jaysoo @JamesHenry /packages/expo/** @xiongemi @jaysoo @ndcunningham /e2e/expo/** @xiongemi @jaysoo @ndcunningham /packages/react-native/** @xiongemi @jaysoo @ndcunningham -/e2e/react-native/** @xiongemi @jaysoo @ndcunningham +/e2e/react-native/\*\* @xiongemi @jaysoo @ndcunningham ## Node + /docs/generated/packages/node/** @nartc @ndcunningham @jaysoo /packages/node/** @nartc @ndcunningham @jaysoo /packages/express/** @nartc @ndcunningham @jaysoo /packages/nest/** @nartc @ndcunningham @jaysoo -/e2e/node/** @nartc @ndcunningham @jaysoo +/e2e/node/\*\* @nartc @ndcunningham @jaysoo ## JS + /docs/generated/packages/js/** @nartc @jaysoo @ndcunningham /docs/generated/packages/web/** @jaysoo @mandarini @ndcunningham /docs/generated/packages/webpack/** @jaysoo @mandarini @ndcunningham @@ -89,6 +96,7 @@ yarn.lock @FrozenPandaz @vsavkin @AgentEnder @jaysoo @JamesHenry /e2e/vite/** @jaysoo @mandarini @ndcunningham ## Tools + /docs/generated/packages/cypress/** @barbados-clemens @FrozenPandaz /docs/generated/packages/jest/** @barbados-clemens @FrozenPandaz /packages/cypress/** @barbados-clemens @FrozenPandaz @@ -97,33 +105,38 @@ yarn.lock @FrozenPandaz @vsavkin @AgentEnder @jaysoo @JamesHenry /e2e/jest/** @barbados-clemens @FrozenPandaz # Linter + /docs/generated/packages/eslint-plugin-nx/** @meeroslav @FrozenPandaz @JamesHenry /docs/generated/packages/linter/** @meeroslav @FrozenPandaz @JamesHenry /packages/eslint-plugin-nx/** @meeroslav @FrozenPandaz @JamesHenry /packages/linter/** @meeroslav @FrozenPandaz @JamesHenry -/e2e/linter/** @meeroslav @FrozenPandaz -.eslint* @meeroslav @FrozenPandaz @JamesHenry +/e2e/linter/\*_ @meeroslav @FrozenPandaz +.eslint_ @meeroslav @FrozenPandaz @JamesHenry # Storybook + /docs/generated/packages/storybook/** @mandarini @jaysoo @Coly010 /docs/shared/packages/storybook/** @mandarini @jaysoo @Coly010 /packages/storybook/** @mandarini @jaysoo @Coly010 /e2e/storybook/** @mandarini @FrozenPandaz @Coly010 -/e2e/storybook-angular/** @mandarini @Coly010 +/e2e/storybook-angular/\*\* @mandarini @Coly010 ## Devkit + /docs/generated/devkit/** @FrozenPandaz @AgentEnder /docs/generated/packages/devkit/** @FrozenPandaz @AgentEnder -/packages/devkit/** @FrozenPandaz @AgentEnder +/packages/devkit/\*\* @FrozenPandaz @AgentEnder /packages/devkit/index.ts @FrozenPandaz @vsavkin /packages/devkit/src/utils/module-federation @jaysoo @Coly010 # Nx-Plugin + /docs/generated/packages/nx-plugin/** @AgentEnder @FrozenPandaz /packages/nx-plugin/** @AgentEnder @FrozenPandaz -/e2e/nx-plugin/** @AgentEnder @FrozenPandaz +/e2e/nx-plugin/\*\* @AgentEnder @FrozenPandaz ## Core + /docs/generated/packages/nx/** @vsavkin @FrozenPandaz @AgentEnder /docs/generated/packages/workspace/** @vsavkin @FrozenPandaz @AgentEnder /packages/nx/** @vsavkin @FrozenPandaz @AgentEnder @@ -135,7 +148,7 @@ yarn.lock @FrozenPandaz @vsavkin @AgentEnder @jaysoo @JamesHenry /packages/nx/src/nx-init/react/** @jaysoo @xiongemi @mandarini /e2e/nx-init/src/nx-init-react.test.ts @jaysoo @xiongemi @mandarini @ndcunningham /e2e/nx-init/src/files/cra/** @jaysoo @xiongemi @mandarini @ndcunningham -/e2e/nx*/** @FrozenPandaz @AgentEnder @vsavkin +/e2e/nx\*/** @FrozenPandaz @AgentEnder @vsavkin /packages/workspace/** @FrozenPandaz @AgentEnder @vsavkin /e2e/workspace-create/** @FrozenPandaz @AgentEnder @vsavkin /e2e/workspace-create-npm/** @FrozenPandaz @vsavkin @@ -144,6 +157,7 @@ yarn.lock @FrozenPandaz @vsavkin @AgentEnder @jaysoo @JamesHenry /e2e/add-nx-to-monorepo/** @vsavkin @FrozenPandaz @AgentEnder # Misc + /e2e/lerna-smoke-tests/** @vsavkin @JamesHenry /e2e/utils/** @meeroslav @barbados-clemens @vsavkin @mandarini /community @AgentEnder @FrozenPandaz @@ -152,18 +166,21 @@ yarn.lock @FrozenPandaz @vsavkin @AgentEnder @jaysoo @JamesHenry /CODEOWNERS @FrozenPandaz @AgentEnder # Scripts + /scripts/depcheck @FrozenPandaz @vsavkin @jaysoo /scripts/documentation @bcabanes @isaacplmann /scripts/local-registry @FrozenPandaz @vsavkin /scripts/angular-support-upgrades @Coly010 @leosvelperez # CI + /.circleci/** @meeroslav @vsavkin @FrozenPandaz /.github/** @meeroslav @vsavkin @FrozenPandaz @JamesHenry /.husky/** @meeroslav @vsavkin @FrozenPandaz /packages/workspace/src/generators/ci-workflow/** @meeroslav @StalkAltan @vsavkin # Global Files + project.json @FrozenPandaz @vsavkin jest.config.ts @barbados-clemens @FrozenPandaz jest.preset.ts @barbados-clemens @FrozenPandaz diff --git a/docs/README.md b/docs/README.md index 9f851a475ee86..8480770172c3f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -50,10 +50,10 @@ Title cards allow to only show a title in a card with a title and an url. ```markdown {% cards cols="4" %} -{% title-card title="string" href="string" /%} -{% title-card title="string" href="string" /%} -{% title-card title="string" href="string" /%} -{% title-card title="string" href="string" /%} +{% title-card title="string" url="string" /%} +{% title-card title="string" url="string" /%} +{% title-card title="string" url="string" /%} +{% title-card title="string" url="string" /%} {% /cards %} ``` diff --git a/docs/generated/manifests/menus.json b/docs/generated/manifests/menus.json index 62ef44b237064..384ad5c447f3f 100644 --- a/docs/generated/manifests/menus.json +++ b/docs/generated/manifests/menus.json @@ -3,13 +3,13 @@ "id": "nx", "menu": [ { - "name": "Getting Started", + "name": "Start Here", "path": "/getting-started", "id": "getting-started", "isExternal": false, "children": [ { - "name": "Intro to Nx", + "name": "Getting Started", "path": "/getting-started/intro", "id": "intro", "isExternal": false, @@ -17,40 +17,89 @@ "disableCollapsible": false }, { - "name": "Package-Based Repo Tutorial", - "path": "/getting-started/package-based-repo-tutorial", + "name": "Installation", + "path": "/getting-started/installation", + "id": "installation", + "isExternal": false, + "children": [], + "disableCollapsible": false + }, + { + "name": "Why Nx?", + "path": "/getting-started/why-nx", + "id": "why-nx", + "isExternal": false, + "children": [], + "disableCollapsible": false + } + ], + "disableCollapsible": false + }, + { + "name": "Getting Started", + "path": "/getting-started/intro", + "id": "intro", + "isExternal": false, + "children": [], + "disableCollapsible": false + }, + { + "name": "Installation", + "path": "/getting-started/installation", + "id": "installation", + "isExternal": false, + "children": [], + "disableCollapsible": false + }, + { + "name": "Why Nx?", + "path": "/getting-started/why-nx", + "id": "why-nx", + "isExternal": false, + "children": [], + "disableCollapsible": false + }, + { + "name": "5 min Tutorials", + "path": "/tutorials", + "id": "tutorials", + "isExternal": false, + "children": [ + { + "name": "Package-Based Monorepo", + "path": "/tutorials/package-based-repo-tutorial", "id": "package-based-repo-tutorial", "isExternal": false, "children": [], "disableCollapsible": false }, { - "name": "Integrated Repo Tutorial", - "path": "/getting-started/integrated-repo-tutorial", + "name": "Integrated Monorepo", + "path": "/tutorials/integrated-repo-tutorial", "id": "integrated-repo-tutorial", "isExternal": false, "children": [], "disableCollapsible": false }, { - "name": "React Standalone Tutorial", - "path": "/getting-started/react-standalone-tutorial", + "name": "React Standalone", + "path": "/tutorials/react-standalone-tutorial", "id": "react-standalone-tutorial", "isExternal": false, "children": [], "disableCollapsible": false }, { - "name": "Angular Standalone Tutorial", - "path": "/getting-started/angular-standalone-tutorial", + "name": "Angular Standalone", + "path": "/tutorials/angular-standalone-tutorial", "id": "angular-standalone-tutorial", "isExternal": false, "children": [], "disableCollapsible": false }, { - "name": "Node Server Tutorial", - "path": "/getting-started/node-server-tutorial", + "name": "Node Standalone", + "path": "/tutorials/node-server-tutorial", "id": "node-server-tutorial", "isExternal": false, "children": [], @@ -60,48 +109,40 @@ "disableCollapsible": false }, { - "name": "Intro to Nx", - "path": "/getting-started/intro", - "id": "intro", - "isExternal": false, - "children": [], - "disableCollapsible": false - }, - { - "name": "Package-Based Repo Tutorial", - "path": "/getting-started/package-based-repo-tutorial", + "name": "Package-Based Monorepo", + "path": "/tutorials/package-based-repo-tutorial", "id": "package-based-repo-tutorial", "isExternal": false, "children": [], "disableCollapsible": false }, { - "name": "Integrated Repo Tutorial", - "path": "/getting-started/integrated-repo-tutorial", + "name": "Integrated Monorepo", + "path": "/tutorials/integrated-repo-tutorial", "id": "integrated-repo-tutorial", "isExternal": false, "children": [], "disableCollapsible": false }, { - "name": "React Standalone Tutorial", - "path": "/getting-started/react-standalone-tutorial", + "name": "React Standalone", + "path": "/tutorials/react-standalone-tutorial", "id": "react-standalone-tutorial", "isExternal": false, "children": [], "disableCollapsible": false }, { - "name": "Angular Standalone Tutorial", - "path": "/getting-started/angular-standalone-tutorial", + "name": "Angular Standalone", + "path": "/tutorials/angular-standalone-tutorial", "id": "angular-standalone-tutorial", "isExternal": false, "children": [], "disableCollapsible": false }, { - "name": "Node Server Tutorial", - "path": "/getting-started/node-server-tutorial", + "name": "Node Standalone", + "path": "/tutorials/node-server-tutorial", "id": "node-server-tutorial", "isExternal": false, "children": [], diff --git a/docs/generated/manifests/nx.json b/docs/generated/manifests/nx.json index 759d1fe2cdf13..1706b81854457 100644 --- a/docs/generated/manifests/nx.json +++ b/docs/generated/manifests/nx.json @@ -1,13 +1,13 @@ { "/getting-started": { "id": "getting-started", - "name": "Getting Started", + "name": "Start Here", "description": "Get started with basic information, concepts and tutorials.", "file": "", "itemList": [ { "id": "intro", - "name": "Intro to Nx", + "name": "Getting Started", "description": "", "file": "shared/getting-started/intro", "itemList": [], @@ -15,119 +15,170 @@ "path": "/getting-started/intro", "tags": [] }, + { + "id": "installation", + "name": "Installation", + "description": "", + "file": "shared/getting-started/installation", + "itemList": [], + "isExternal": false, + "path": "/getting-started/installation", + "tags": [] + }, + { + "id": "why-nx", + "name": "Why Nx?", + "description": "", + "file": "shared/getting-started/why-nx", + "itemList": [], + "isExternal": false, + "path": "/getting-started/why-nx", + "tags": [] + } + ], + "isExternal": false, + "path": "/getting-started", + "tags": [] + }, + "/getting-started/intro": { + "id": "intro", + "name": "Getting Started", + "description": "", + "file": "shared/getting-started/intro", + "itemList": [], + "isExternal": false, + "path": "/getting-started/intro", + "tags": [] + }, + "/getting-started/installation": { + "id": "installation", + "name": "Installation", + "description": "", + "file": "shared/getting-started/installation", + "itemList": [], + "isExternal": false, + "path": "/getting-started/installation", + "tags": [] + }, + "/getting-started/why-nx": { + "id": "why-nx", + "name": "Why Nx?", + "description": "", + "file": "shared/getting-started/why-nx", + "itemList": [], + "isExternal": false, + "path": "/getting-started/why-nx", + "tags": [] + }, + "/tutorials": { + "id": "tutorials", + "name": "5 min Tutorials", + "description": "Get started with basic information, concepts and tutorials.", + "file": "", + "itemList": [ { "id": "package-based-repo-tutorial", - "name": "Package-Based Repo Tutorial", + "name": "Package-Based Monorepo", "description": "", "file": "shared/npm-tutorial/package-based", "itemList": [], "isExternal": false, - "path": "/getting-started/package-based-repo-tutorial", + "path": "/tutorials/package-based-repo-tutorial", "tags": [] }, { "id": "integrated-repo-tutorial", - "name": "Integrated Repo Tutorial", + "name": "Integrated Monorepo", "description": "", "file": "shared/npm-tutorial/integrated", "itemList": [], "isExternal": false, - "path": "/getting-started/integrated-repo-tutorial", + "path": "/tutorials/integrated-repo-tutorial", "tags": [] }, { "id": "react-standalone-tutorial", - "name": "React Standalone Tutorial", + "name": "React Standalone", "description": "", "file": "shared/react-standalone-tutorial/1-code-generation", "itemList": [], "isExternal": false, - "path": "/getting-started/react-standalone-tutorial", + "path": "/tutorials/react-standalone-tutorial", "tags": [] }, { "id": "angular-standalone-tutorial", - "name": "Angular Standalone Tutorial", + "name": "Angular Standalone", "description": "", "file": "shared/angular-standalone-tutorial/1-code-generation", "itemList": [], "isExternal": false, - "path": "/getting-started/angular-standalone-tutorial", + "path": "/tutorials/angular-standalone-tutorial", "tags": [] }, { "id": "node-server-tutorial", - "name": "Node Server Tutorial", + "name": "Node Standalone", "description": "", "file": "shared/node-server-tutorial/1-code-generation", "itemList": [], "isExternal": false, - "path": "/getting-started/node-server-tutorial", + "path": "/tutorials/node-server-tutorial", "tags": [] } ], "isExternal": false, - "path": "/getting-started", + "path": "/tutorials", "tags": [] }, - "/getting-started/intro": { - "id": "intro", - "name": "Intro to Nx", - "description": "", - "file": "shared/getting-started/intro", - "itemList": [], - "isExternal": false, - "path": "/getting-started/intro", - "tags": [] - }, - "/getting-started/package-based-repo-tutorial": { + "/tutorials/package-based-repo-tutorial": { "id": "package-based-repo-tutorial", - "name": "Package-Based Repo Tutorial", + "name": "Package-Based Monorepo", "description": "", "file": "shared/npm-tutorial/package-based", "itemList": [], "isExternal": false, - "path": "/getting-started/package-based-repo-tutorial", + "path": "/tutorials/package-based-repo-tutorial", "tags": [] }, - "/getting-started/integrated-repo-tutorial": { + "/tutorials/integrated-repo-tutorial": { "id": "integrated-repo-tutorial", - "name": "Integrated Repo Tutorial", + "name": "Integrated Monorepo", "description": "", "file": "shared/npm-tutorial/integrated", "itemList": [], "isExternal": false, - "path": "/getting-started/integrated-repo-tutorial", + "path": "/tutorials/integrated-repo-tutorial", "tags": [] }, - "/getting-started/react-standalone-tutorial": { + "/tutorials/react-standalone-tutorial": { "id": "react-standalone-tutorial", - "name": "React Standalone Tutorial", + "name": "React Standalone", "description": "", "file": "shared/react-standalone-tutorial/1-code-generation", "itemList": [], "isExternal": false, - "path": "/getting-started/react-standalone-tutorial", + "path": "/tutorials/react-standalone-tutorial", "tags": [] }, - "/getting-started/angular-standalone-tutorial": { + "/tutorials/angular-standalone-tutorial": { "id": "angular-standalone-tutorial", - "name": "Angular Standalone Tutorial", + "name": "Angular Standalone", "description": "", "file": "shared/angular-standalone-tutorial/1-code-generation", "itemList": [], "isExternal": false, - "path": "/getting-started/angular-standalone-tutorial", + "path": "/tutorials/angular-standalone-tutorial", "tags": [] }, - "/getting-started/node-server-tutorial": { + "/tutorials/node-server-tutorial": { "id": "node-server-tutorial", - "name": "Node Server Tutorial", + "name": "Node Standalone", "description": "", "file": "shared/node-server-tutorial/1-code-generation", "itemList": [], "isExternal": false, - "path": "/getting-started/node-server-tutorial", + "path": "/tutorials/node-server-tutorial", "tags": [] }, "/core-tutorial": { diff --git a/docs/map.json b/docs/map.json index c17a28fc07ad2..f178f065a7273 100644 --- a/docs/map.json +++ b/docs/map.json @@ -9,37 +9,54 @@ "description": "Nx documentation for you to discover!", "itemList": [ { - "name": "Getting Started", + "name": "Start Here", "id": "getting-started", "description": "Get started with basic information, concepts and tutorials.", "itemList": [ { - "name": "Intro to Nx", + "name": "Getting Started", "id": "intro", "file": "shared/getting-started/intro" }, { - "name": "Package-Based Repo Tutorial", + "name": "Installation", + "id": "installation", + "file": "shared/getting-started/installation" + }, + { + "name": "Why Nx?", + "id": "why-nx", + "file": "shared/getting-started/why-nx" + } + ] + }, + { + "name": "5 min Tutorials", + "id": "tutorials", + "description": "Get started with basic information, concepts and tutorials.", + "itemList": [ + { + "name": "Package-Based Monorepo", "id": "package-based-repo-tutorial", "file": "shared/npm-tutorial/package-based" }, { - "name": "Integrated Repo Tutorial", + "name": "Integrated Monorepo", "id": "integrated-repo-tutorial", "file": "shared/npm-tutorial/integrated" }, { - "name": "React Standalone Tutorial", + "name": "React Standalone", "id": "react-standalone-tutorial", "file": "shared/react-standalone-tutorial/1-code-generation" }, { - "name": "Angular Standalone Tutorial", + "name": "Angular Standalone", "id": "angular-standalone-tutorial", "file": "shared/angular-standalone-tutorial/1-code-generation" }, { - "name": "Node Server Tutorial", + "name": "Node Standalone", "id": "node-server-tutorial", "file": "shared/node-server-tutorial/1-code-generation" } diff --git a/docs/shared/concepts/integrated-vs-package-based.md b/docs/shared/concepts/integrated-vs-package-based.md index 0f19af2482df7..2d37aac3811e5 100644 --- a/docs/shared/concepts/integrated-vs-package-based.md +++ b/docs/shared/concepts/integrated-vs-package-based.md @@ -18,7 +18,7 @@ A package-based repo is a collection of packages that depend on each other via ` Lerna, Yarn, Lage, [Turborepo](/more-concepts/turbo-and-nx) and Nx (without plugins) support this style. {% cards %} -{% card title="Tutorial: Getting Started with Package-Based Repos" description="Walkthrough for creating a package-based monorepo with Nx" type="documentation" url="/getting-started/package-based-repo-tutorial" /%} +{% card title="Tutorial: Getting Started with Package-Based Repos" description="Walkthrough for creating a package-based monorepo with Nx" type="documentation" url="/tutorials/package-based-repo-tutorial" /%} {% /cards %} ## Integrated Repos @@ -28,7 +28,7 @@ An integrated repo contains projects that depend on each other through standard Bazel and Nx (with plugins) support this style. {% cards %} -{% card title="Tutorial: Getting Started with Integrated Repos" description="Walkthrough for creating an integrated monorepo with Nx" type="documentation" url="/getting-started/integrated-repo-tutorial" /%} +{% card title="Tutorial: Getting Started with Integrated Repos" description="Walkthrough for creating an integrated monorepo with Nx" type="documentation" url="/tutorials/integrated-repo-tutorial" /%} {% /cards %} ## Standalone Applications @@ -37,8 +37,8 @@ Nx plugins, especially the [generators](/plugin-features/use-code-generators), [ {% cards %} {% card title="Standalone Applications with Nx" description="Learn what Standlone Apps are and how Nx can be useful" type="video" url="https://youtu.be/qEaVzh-oBBc" /%} -{% card title="Tutorial: React Standalone Tutorial" description="Walkthrough for creating a React standalone application with Nx" type="documentation" url="/getting-started/react-standalone-tutorial" /%} -{% card title="Tutorial: Angular Standalone Tutorial" description="Walkthrough for creating an Angular standalone application with Nx" type="documentation" url="/getting-started/angular-standalone-tutorial" /%} +{% card title="Tutorial: React Standalone Tutorial" description="Walkthrough for creating a React standalone application with Nx" type="documentation" url="/tutorials/react-standalone-tutorial" /%} +{% card title="Tutorial: Angular Standalone Tutorial" description="Walkthrough for creating an Angular standalone application with Nx" type="documentation" url="/tutorials/angular-standalone-tutorial" /%} {% /cards %} ## How to Choose diff --git a/docs/shared/core-tutorial/01-create-blog.md b/docs/shared/core-tutorial/01-create-blog.md index de29893a99544..0c21a55a53975 100644 --- a/docs/shared/core-tutorial/01-create-blog.md +++ b/docs/shared/core-tutorial/01-create-blog.md @@ -3,7 +3,7 @@ In this tutorial you create multiple projects in a monorepo and take advantage of the core Nx features with a minimum of configuration. {% callout type="check" title="Package-Based Repo" %} -This tutorial sets up a [package-based repo](/concepts/integrated-vs-package-based). If you prefer an [integrated repo](/concepts/integrated-vs-package-based), check out the [React](/react-tutorial/1-code-generation), [Angular](/angular-tutorial/1-code-generation) or [Node](/getting-started/node-server-tutorial) tutorials. +This tutorial sets up a [package-based repo](/concepts/integrated-vs-package-based). If you prefer an [integrated repo](/concepts/integrated-vs-package-based), check out the [React](/react-tutorial/1-code-generation), [Angular](/angular-tutorial/1-code-generation) or [Node](/tutorials/node-server-tutorial) tutorials. {% /callout %} ## Contents: diff --git a/docs/shared/getting-started/installation.md b/docs/shared/getting-started/installation.md new file mode 100644 index 0000000000000..ee8eca64479f9 --- /dev/null +++ b/docs/shared/getting-started/installation.md @@ -0,0 +1,89 @@ +# Installation + +Create a new Nx workspace using the following command: + +{% tabs %} +{% tab label="npm" %} + +```shell +npm create nx-workspace +``` + +{% /tab %} +{% tab label="yarn" %} + +```shell +yarn create nx-workspace +``` + +{% /tab %} +{% tab label="pnpm" %} + +```shell +pnpm create nx-workspace +``` + +{% /tab %} +{% /tabs %} + +This will guide you through the setup, asking whether you want a monorepo or a standalone app and whether you want to start with a blank or a preconfigured setup. + +```{% command="npm create nx-workspace" %} +? Choose what to create … +Package-based monorepo: Nx makes it fast but lets you run things your way. +Integrated monorepo: Nx configures your favorite frameworks and lets you focus on shipping features. +Standalone React app: Nx configures Vite (or Webpack), ESLint, and Cypress. +Standalone Angular app: Nx configures Jest, ESLint, and Cypress. +Standalone Node app: Nx configures a framework (ex. Express), esbuild, ESlint and Jest. +``` + +Once you've created your workspace, you can + +- run single tasks with `npx nx ` +- run multiple tasks with `npx nx run-many -t ` + +Run `npx nx run-many -t build` twice to see how Nx's powerful caching speeds up your build. + +Learn more about [running tasks](/core-features/run-tasks). + +## Installing Nx Into an Existing Repository + +If you want to add Nx to an existing repository run: + +```shell +npx nx@latest init +``` + +You can also manually install the nx NPM package and create a [nx.json](https://nx.dev/reference/nx-json) to configure it. Learn more about [adopting Nx in an existing project](/recipes/adopting-nx) + +## Installing Nx Globally + +You can install Nx globally. Depending on your package manager, use one of the following commands: + +{% tabs %} +{% tab label="npm" %} + +```shell +npm install --global nx@latest +``` + +{% /tab %} +{% tab label="yarn" %} + +```shell +yarn global add nx@latest +``` + +{% /tab %} +{% tab label="pnpm" %} + +```shell +pnpm install --global nx@latest +``` + +{% /tab %} +{% /tabs %} + +The advantage of a global installation is that you don't have to prefix your commands with npx, yarn or pnpm. The global Nx installation hands off the process execution to the local Nx installation in your repository, which eliminates any issues with outdated globally installed packages. + +Learn more about [managing and troubleshooting a global Nx installation](/more-concepts/global-nx). diff --git a/docs/shared/getting-started/intro.md b/docs/shared/getting-started/intro.md index fd40339c19cb3..3c9161ca58622 100644 --- a/docs/shared/getting-started/intro.md +++ b/docs/shared/getting-started/intro.md @@ -1,83 +1,93 @@ # Intro to Nx -Nx is a smart, fast and extensible build system with first class monorepo support and powerful integrations. +Nx is a powerful open-source build system that provides tools and techniques for enhancing developer productivity, optimizing CI performance, and maintaining code quality. Learn more about [how Nx works](/getting-started/why-nx). + +You can use Nx to quickly scaffold a new standalone project or even an entire monorepo. It can be incrementally adopted and will grow with your project as it scales. + +{% cards cols="3" %} + +{% title-card title="New Monorepo" url="#start-a-new-monorepo" /%} +{% title-card title="New Standalone Project" url="#start-a-new-standalone-project" /%} +{% title-card title="Add to an Existing Project or Monorepo" url="#adding-nx-to-an-existing-project-or-monorepo" /%} + +{% /cards %} + +## Start a New Monorepo + +Its modular architecture lets you adopt Nx for package-based monorepos in combination with NPM, Yarn or PNPM, or create a fully integrated monorepo using Nx plugins. Learn more with the tutorials below. {% personas %} -{% persona type="javascript" title="New Package-Based Repo" url="/getting-started/package-based-repo-tutorial" %} +{% persona type="javascript" title="New Package-Based Repo" url="/tutorials/package-based-repo-tutorial" %} Create a monorepo with Yarn, NPM or PNPM. Nx makes it fast, but lets you run things your way. -- [Get started with your package-based repo](/getting-started/package-based-repo-tutorial) +- [Get started with your package-based repo](/tutorials/package-based-repo-tutorial) {% /persona %} -{% persona type="integrated" title="New Integrated Repo" url="/getting-started/integrated-repo-tutorial" %} +{% persona type="integrated" title="New Integrated Repo" url="/tutorials/integrated-repo-tutorial" %} Get a pre-configured setup. Nx configures your favorite frameworks and lets you focus on shipping features. -- [Get started with your integrated repo](/getting-started/integrated-repo-tutorial) +- [Get started with your integrated repo](/tutorials/integrated-repo-tutorial) {% /persona %} {% /personas %} +{% /cards %} + +## Start a New Standalone Project + +Nx works well not just for monorepos. Nx plugins help you scaffold new standalone projects with pre-configured tooling and modularize your codebase with local libraries. + {% cards cols="3" %} -{% persona type="react" title="Create a Standalone React app" url="/getting-started/react-standalone-tutorial" %} +{% persona type="react" title="Create a Standalone React app" url="/tutorials/react-standalone-tutorial" %} -A modern React setup with built-in support for Vite, ESLint, Cypress and more. Think CRA but modern, always up-to-date and scalable. +A modern React setup with built-in support for Vite, ESLint, Cypress, and more. Think CRA but modern, always up-to-date and scalable. -- [Create a Standalone React app](/getting-started/react-standalone-tutorial) +- [Create a Standalone React app](/tutorials/react-standalone-tutorial) {% /persona %} -{% persona type="angular" title="Create a Standalone Angular app" url="/getting-started/angular-standalone-tutorial" %} +{% persona type="angular" title="Create a Standalone Angular app" url="/tutorials/angular-standalone-tutorial" %} A modern Angular development experience powered by advanced generators and integrations with modern tooling. -- [Create a Standalone Angular app](/getting-started/angular-standalone-tutorial) +- [Create a Standalone Angular app](/tutorials/angular-standalone-tutorial) {% /persona %} -{% persona type="node" title="Create a Standalone Node server" url="/getting-started/node-server-tutorial" %} +{% persona type="node" title="Create a Standalone Node server" url="/tutorials/node-server-tutorial" %} A modern Node server with scaffolding for Express, Fastify or Koa. There's also Docker support built-in. -- [Create a Standalone Node server](/getting-started/node-server-tutorial) +- [Create a Standalone Node server](/tutorials/node-server-tutorial) {% /persona %} {% /cards %} -## Adopting Nx +## Adding Nx to an Existing Project or Monorepo Coming from an existing project and want to adopt Nx? We have a few recipes to help you get started. {% cards cols="2" %} -{% card title="Add to Existing Monorepo" description="Add Nx to your existing NPM/YARN/PNPM workspace" type="documentation" url="/recipes/adopting-nx/adding-to-monorepo" /%} +{% persona type="extend" title="Add to Existing Monorepo" url="/recipes/adopting-nx/adding-to-monorepo" %} +Add Nx to your existing NPM/YARN/PNPM workspace +{% /persona %} -{% card title="Add to any Project" description="Add Nx to an standalone project" type="documentation" url="/recipes/adopting-nx/adding-to-existing-project" /%} +{% persona title="Add to any Project" type="extend" url="/recipes/adopting-nx/adding-to-existing-project" %} +Add Nx to a standalone project +{% /persona %} -{% card title="Migrate from CRA" description="Migrate from a CRA setup and automatically switch to Vite" type="documentation" url="/recipes/adopting-nx/migration-cra" /%} +{% persona title="Migrate from CRA" type="react" url="/recipes/adopting-nx/migration-cra" %} +Migrate from a CRA setup and automatically switch to Vite +{% /persona %} -{% card title="Migrate from Angular CLI" description="Automatically migrate from the Angular CLI" type="documentation" url="/recipes/adopting-nx/migration-angular" /%} +{% persona title="Migrate from Angular CLI" type="angular" url="/recipes/adopting-nx/migration-angular" %} +Automatically migrate from the Angular CLI +{% /persona %} {% /cards %} - -## Why Nx? - -Nx has two main goals: - -- **Speed up your existing workflow with minimum effort.** -- **Provide a first-rate developer experience no matter the size of the repo.** - -It achieves that speed via [computation caching](/core-features/cache-task-results), by only [run tasks affected by a given change](/core-features/run-tasks#run-tasks-affected-by-a-pr) and by being able to [distribute your task execution](/core-features/distribute-task-execution) across multiple agents in CI. - -High quality DX is implemented via [code generators](/plugin-features/use-code-generators), [IDE extensions](/core-features/integrate-with-editors#integrate-with-editors) and by helping you [keep your codebase evergreen](/core-features/automate-updating-dependencies). - -## How does Nx compare to other tools? - -If you know other tools in the monorepo space, here is how Nx compares: - -- [Monorepo.tools](https://monorepo.tools) -- [Nx and Turborepo](/more-concepts/turbo-and-nx) diff --git a/docs/shared/getting-started/why-nx.md b/docs/shared/getting-started/why-nx.md new file mode 100644 index 0000000000000..a09b8eebe3d7d --- /dev/null +++ b/docs/shared/getting-started/why-nx.md @@ -0,0 +1,29 @@ +# Why Nx? + +We created Nx because developers struggle to configure, maintain and especially integrate various tools and frameworks. Setting up a system that works well for a handful of developers and at the same time, easily scales up to an entire organization is hard. This includes setting up low-level build tooling, configuring fast CI, and keeping your codebase healthy, up-to-date, and maintainable. + +We wanted to provide a solution that is easy to adopt and scales. + +## How Does Nx Help You? + +In a nutshell, Nx helps to: **speed up your computation** (e.g. builds, tests etc), locally and on CI and to **integrate and automate your tooling** via its plugins. All of this can be adopted incrementally. You can use plugins, but you don't have to. Look at the Nx architecture in the next section to learn more. + +You can use Nx to + +- speed up your existing project's builds and tests, locally and on CI (whether that's a monorepo or standalone application) +- quickly scaffold a new project (using Nx plugins) without having to configure any lower-level build tools +- easily integrate new tooling (e.g., Storybook, Tailwind etc), into your project. +- ensure consistency and code quality with custom generators and lint rules +- update your frameworks and tools and keep your workspace evergreen using the automated code migration feature + +## How Does Nx Work? + +Nx is built in a modular fashion to let you only use the features you need. + +![High-level Nx architecture](../images/nx-architecture.svg) + +- The **Nx** package provides fundamental technology-agnostic capabilities such as: [workspace analysis](/core-features/explore-graph), [task running](/core-features/run-tasks), [caching](/core-features/cache-task-results), [distribution](/core-features/distribute-task-execution), [code generation](/plugin-features/use-code-generators) and [automated code migrations](/core-features/automate-updating-dependencies). +- **Plugins** are NPM packages that built on top of the fundamental capabilities provided by the Nx package. Nx plugins contain [code generators](/plugin-features/use-code-generators), [executors](/plugin-features/use-task-executors) (to abstract lower-level build tooling) and automated code migrations for keeping your tools up to date. Contrary to the Nx package, which works the same way with any JS or non-JS project, plugins are usually technology specific. For instance, `@nrwl/react` adds support for building React apps and libs, `@nrwl/cypress` adds e2e testing capabilities with Cypress. Plugins make developers more productive by removing any friction of integrating different tools with each other and by providing utilities to keep them up to date. The Nx team maintains plugins for React, Next, Remix, Angular, Jest, Cypress, Storybook and more. You can use the `@nrwl/nx-plugin` package to easily [scaffold a new plugin](/plugin-features/create-your-own-plugin) or even just [automate your local workspace](/recipes/generators/local-generators). There are also more than 80 [community plugins](/community). +- **Devkit** is a set of utilities for [building Nx plugins](/plugin-features/create-your-own-plugin). +- **Nx Cloud** helps scale your project on CI by [adding remote caching](/concepts/how-caching-works) and [distributed task execution](/more-concepts/illustrated-dte). It also improves developer ergonomics by integrating with GitHub, GitLab and BitBucket and providing searchable structured logs. Learn more at [nx.app](https://nx.app). +- **Nx Console** is an extension for **VSCode, IntelliJ and VIM**. It provides code autocompletion, interactive generators, workspace visualizations, powerful refactorings and more. You can [install it here](/core-features/integrate-with-editors). diff --git a/docs/shared/images/nx-architecture.svg b/docs/shared/images/nx-architecture.svg new file mode 100644 index 0000000000000..49045a86e9805 --- /dev/null +++ b/docs/shared/images/nx-architecture.svg @@ -0,0 +1,115 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/shared/migration/adding-to-monorepo.md b/docs/shared/migration/adding-to-monorepo.md index 267dffe5eb485..38c6c3565653a 100644 --- a/docs/shared/migration/adding-to-monorepo.md +++ b/docs/shared/migration/adding-to-monorepo.md @@ -4,7 +4,7 @@ Interested in migrating from [Lerna](https://github.com/lerna/lerna) in particular? In case you missed it, Lerna v6 is powering Nx underneath. As a result, Lerna gets all the modern features such as caching and task pipelines. Read more on [https://lerna.js.org/upgrade](https://lerna.js.org/upgrade). {% /callout %} -Nx has first class support for [package-based monorepos](/getting-started/package-based-repo-tutorial). As a result, if you have an existing NPM/Yarn or PNPM based monorepo setup, you can easily add Nx to get +Nx has first class support for [package-based monorepos](/tutorials/package-based-repo-tutorial). As a result, if you have an existing NPM/Yarn or PNPM based monorepo setup, you can easily add Nx to get - fast [task scheduling](/core-features/run-tasks) - support for [task pipelines](/concepts/task-pipeline-configuration) diff --git a/docs/shared/npm-tutorial/integrated.md b/docs/shared/npm-tutorial/integrated.md index 6d8b936b9b631..c19f972a3b9fe 100644 --- a/docs/shared/npm-tutorial/integrated.md +++ b/docs/shared/npm-tutorial/integrated.md @@ -233,6 +233,6 @@ npx nx affected --target=build {% card title="React Tutorial" description="A step-by-step tutorial showing how to build an integrated monorepo with React applications sharing code." url="/react-tutorial/1-code-generation" /%} -{% card title="Node.js Tutorial" description="A step-by-step tutorial showing how to build an integrated monorepo with Node.js applications sharing code." url="/getting-started/node-server-tutorial" /%} +{% card title="Node.js Tutorial" description="A step-by-step tutorial showing how to build an integrated monorepo with Node.js applications sharing code." url="/tutorials/node-server-tutorial" /%} {% /cards %} diff --git a/nx-dev/data-access-menu/src/lib/menu.utils.ts b/nx-dev/data-access-menu/src/lib/menu.utils.ts index 8a619b97801b8..acb8670689cb9 100644 --- a/nx-dev/data-access-menu/src/lib/menu.utils.ts +++ b/nx-dev/data-access-menu/src/lib/menu.utils.ts @@ -9,6 +9,7 @@ export function getBasicNxSection(items: MenuItem[]): MenuSection { .filter( (m) => m.id === 'getting-started' || + m.id === 'tutorials' || m.id === 'core-features' || m.id === 'plugin-features' || m.id === 'concepts' || diff --git a/nx-dev/nx-dev/redirect-rules.config.js b/nx-dev/nx-dev/redirect-rules.config.js index 3e53eb1895bb3..fe79ac7b097a8 100644 --- a/nx-dev/nx-dev/redirect-rules.config.js +++ b/nx-dev/nx-dev/redirect-rules.config.js @@ -342,7 +342,7 @@ const tutorialBaseUrls = { '/(l|latest)/(a|angular)/tutorial/1-code-generation': '/angular-tutorial/1-code-generation', '/(l|latest)/(a|node)/tutorial/1-code-generation': - '/getting-started/node-server-tutorial', + '/tutorials/node-server-tutorial', '/(l|latest)/(r|react)/tutorial/1-code-generation': '/react-tutorial/1-code-generation', }; @@ -378,7 +378,7 @@ const oldNodeTutorialPaths = [ ]; const extraNodeRedirects = { - '/getting-started/node-tutorial': '/getting-started/node-server-tutorial', + '/getting-started/node-tutorial': '/tutorials/node-server-tutorial', '/node-tutorial/1-code-generation': '/node-server-tutorial/1-code-generation', '/node-tutorial/2-project-graph': '/node-server-tutorial/2-project-graph', '/node-tutorial/3-task-running': '/node-server-tutorial/3-task-running', @@ -386,11 +386,12 @@ const extraNodeRedirects = { '/node-tutorial/5-docker-target': '/node-server-tutorial/5-docker-target', '/node-tutorial/6-summary': '/node-server-tutorial/6-summary', }; -const nodeRedirectDestination = '/getting-started/node-server-tutorial'; +const nodeRedirectDestination = '/tutorials/node-server-tutorial'; const nodeTutorialRedirects = oldNodeTutorialPaths.reduce((acc, path) => { acc[path] = nodeRedirectDestination; return acc; }, {}); + const tutorialRedirects = Object.assign( tutorialBaseUrls, reactTutorialRedirects, @@ -507,6 +508,22 @@ const packagesDocuments = { '/linter/eslint-plugin-nx': '/packages/linter/documents/eslint-plugin-nx', }; +/** + * Concept documents Updates (updated 2023-03-31) + */ +const conceptUrls = { + '/more-concepts/global-nx': + '/getting-started/installation#installing-nx-globally', + '/getting-started/package-based-repo-tutorial': + '/tutorials/package-based-repo-tutorial', + '/getting-started/integrated-repo-tutorial': + '/tutorials/integrated-repo-tutorial', + '/getting-started/react-standalone-tutorial': + '/tutorials/react-standalone-tutorial', + '/getting-started/angular-standalone-tutorial': + '/tutorials/angular-standalone-tutorial', +}; + /** * Public export API */ @@ -521,4 +538,5 @@ module.exports = { tutorialRedirects, packagesIndexes, packagesDocuments, + conceptUrls, }; diff --git a/nx-dev/nx-dev/redirect-rules.config.spec.js b/nx-dev/nx-dev/redirect-rules.config.spec.js index 51778e5cf6380..540476161add8 100644 --- a/nx-dev/nx-dev/redirect-rules.config.spec.js +++ b/nx-dev/nx-dev/redirect-rules.config.spec.js @@ -79,7 +79,7 @@ describe('Redirect rules configuration', () => { for (const url of oldNodeTutorialPaths) { expect(redirectRules.tutorialRedirects[url]).toEqual( - '/getting-started/node-server-tutorial' + '/tutorials/node-server-tutorial' ); } diff --git a/packages/cra-to-nx/README.md b/packages/cra-to-nx/README.md index 4db6e3cef3ab4..905299bfd8052 100644 --- a/packages/cra-to-nx/README.md +++ b/packages/cra-to-nx/README.md @@ -41,7 +41,7 @@ nx generate lib ui-button ### Courses, guides, docs -- [Follow the Nx React tutorial](https://nx.dev/getting-started/react-standalone-tutorial) +- [Follow the Nx React tutorial](https://nx.dev/tutorials/react-standalone-tutorial) - [Free Nx course on Egghead.io](https://egghead.io/playlists/scale-react-development-with-nx-4038) diff --git a/packages/create-nx-workspace/src/utils/preset/point-to-tutorial-and-course.ts b/packages/create-nx-workspace/src/utils/preset/point-to-tutorial-and-course.ts index 9ffdcafeb340d..04c383f5444dc 100644 --- a/packages/create-nx-workspace/src/utils/preset/point-to-tutorial-and-course.ts +++ b/packages/create-nx-workspace/src/utils/preset/point-to-tutorial-and-course.ts @@ -26,7 +26,7 @@ export function pointToTutorialAndCourse(preset: Preset) { output.addVerticalSeparator(); output.note({ title, - bodyLines: [`https://nx.dev/getting-started/react-standalone-tutorial`], + bodyLines: [`https://nx.dev/tutorials/react-standalone-tutorial`], }); break; case Preset.ReactMonorepo: @@ -41,9 +41,7 @@ export function pointToTutorialAndCourse(preset: Preset) { output.addVerticalSeparator(); output.note({ title, - bodyLines: [ - `https://nx.dev/getting-started/angular-standalone-tutorial`, - ], + bodyLines: [`https://nx.dev/tutorials/angular-standalone-tutorial`], }); break; case Preset.AngularMonorepo: