From 03c48d1c8c41adea281adb3c6dd92c648011e058 Mon Sep 17 00:00:00 2001 From: Isaac Mann Date: Fri, 9 Oct 2020 14:29:06 -0400 Subject: [PATCH] docs(docs): expand dependency graph docs (#3714) * docs(docs): expand dependency graph docs * docs(docs): path typo * docs(docs): pr review fixes * docs(docs): rewording Co-authored-by: Isaac Mann --- docs/map.json | 30 +++++------ docs/shared/monorepo-dependency-diagrams.md | 5 -- .../workspace/structure/dependency-graph.md | 52 +++++++++++++++++++ 3 files changed, 67 insertions(+), 20 deletions(-) delete mode 100644 docs/shared/monorepo-dependency-diagrams.md create mode 100644 docs/shared/workspace/structure/dependency-graph.md diff --git a/docs/map.json b/docs/map.json index ceb0070f38462..6408c561b2211 100644 --- a/docs/map.json +++ b/docs/map.json @@ -932,6 +932,11 @@ "name": "Using Tags", "id": "monorepo-tags", "file": "shared/monorepo-tags" + }, + { + "name": "Dependency Graph", + "id": "dependency-graph", + "file": "shared/workspace/structure/dependency-graph" } ] }, @@ -977,11 +982,6 @@ } ] }, - { - "name": "Visualizing Workspaces", - "id": "monorepo-dependency-diagrams", - "file": "shared/monorepo-dependency-diagrams" - }, { "name": "Using NgRx", "id": "misc-ngrx" @@ -1953,6 +1953,11 @@ "name": "Using Tags", "id": "monorepo-tags", "file": "shared/monorepo-tags" + }, + { + "name": "Dependency Graph", + "id": "dependency-graph", + "file": "shared/workspace/structure/dependency-graph" } ] }, @@ -1998,11 +2003,6 @@ } ] }, - { - "name": "Visualizing Workspaces", - "id": "monorepo-dependency-diagrams", - "file": "shared/monorepo-dependency-diagrams" - }, { "name": "Adding Images, Fonts, and Files", "id": "adding-assets-react", @@ -2952,6 +2952,11 @@ "name": "Using Tags", "id": "monorepo-tags", "file": "shared/monorepo-tags" + }, + { + "name": "Dependency Graph", + "id": "dependency-graph", + "file": "shared/workspace/structure/dependency-graph" } ] }, @@ -2997,11 +3002,6 @@ } ] }, - { - "name": "Visualizing Workspaces", - "id": "monorepo-dependency-diagrams", - "file": "shared/monorepo-dependency-diagrams" - }, { "name": "Using Nx at Enterprises", "id": "monorepo-nx-enterprise", diff --git a/docs/shared/monorepo-dependency-diagrams.md b/docs/shared/monorepo-dependency-diagrams.md deleted file mode 100644 index e4201d66f7043..0000000000000 --- a/docs/shared/monorepo-dependency-diagrams.md +++ /dev/null @@ -1,5 +0,0 @@ -# Analyzing & Visualizing Workspaces - -To be able to support the monorepo-style development, the tools must know how different projects in your workspace depend on each other. Nx uses advanced code analysis to construct this dependency graph. And it gives you a way to explore it: - - diff --git a/docs/shared/workspace/structure/dependency-graph.md b/docs/shared/workspace/structure/dependency-graph.md new file mode 100644 index 0000000000000..9c352090b1045 --- /dev/null +++ b/docs/shared/workspace/structure/dependency-graph.md @@ -0,0 +1,52 @@ +# Analyzing & Visualizing Workspaces + +To be able to support the monorepo-style development, the tools must know how different projects in your workspace depend on each other. Nx uses advanced code analysis to construct this dependency graph. And it gives you a way to explore it: + + + +## How the Dependency Graph is Built + +Nx creates a graph of all the dependencies between projects in your workspace using two sources of information: + +1. Typescript `import` statements referencing a particular project's path alias + + For instance, if a file in `my-app` has this code: + + ```typescript + import { something } from '@myorg/awesome-library'; + ``` + + Then `my-app` depends on `awesome-library` + +2. Manually created `implicitDependencies` in the `nx.json` file. [Full `implicitDependencies` documentation](/{framework}/workspace/configuration#implicit-dependencies) + + If your `nx.json` has this content: + + ```json + { + "projects": { + "my-app": { + "tags": [], + "implicitDependencies": ["my-api"] + } + } + } + ``` + + Then `my-app` depends on `my-api` + +## Circular Dependencies + +A circular dependency is when a project transitively depends on itself. This can cause problems in the design of your software and also makes Nx's affected algorithm less effective. The lint rule, `nx-enforce-module-boundaries`, will produce an error if any circular dependencies are created and ensures that any `import` statements going across projects only `import` from the defined public apis in a project's root `index.ts` file. + +When migrating a new codebase into an nx workspace, you'll likely begin to uncover existing circular dependencies. Let's look at the simplest possible circular dependency, where `projectA` depends on `projectB` and vice versa. + +**To resolve circular dependencies:** + +First, identify the `import` statements causing the dependency. Search in the source folder of `projectA` for references to `@myorg/projectB` and search in the source folder of `projectB` for references to `@myorg/projectA`. + +Then there are three strategies you can use: + +1. Look for small pieces of code that can be moved from one project to the other. +2. Look for code that both libraries depend on and move that code into a new shared library. +3. Combine `projectA` and `projectB` into one library.