Project graph

Learn how Nx builds and uses the project graph to analyze dependencies, power affected detection, and determine task execution order.

The project graph is Nx’s internal model of your workspace. It is a directed acyclic graph where each node is a project (application or library) and each edge represents a dependency between projects. Nx builds this graph by analyzing your source code, and uses it to power affected detection, task ordering, and caching.

How Nx builds the project graph

Nx constructs the project graph automatically every time it runs. The process works as follows:

1. Detect projects

   Nx scans the workspace for package.json and project.json files. Each file found marks a project boundary. Plugins can extend this detection logic to identify projects in non-standard locations.

2. Analyze dependencies

   For each project, Nx analyzes the source files to find dependencies on other projects. It uses TypeScript and JavaScript static import analysis as the primary mechanism, supplemented by plugin-provided analyzers for other file types.

3. Apply plugin and manual overrides

   Plugins can contribute additional edges to the graph (e.g., based on config files). Developers can also declare implicitDependencies in project.json to add edges that static analysis cannot detect.

4. Cache the result

   The completed graph is cached on disk. On subsequent runs, Nx only re-analyzes files that have changed since the last computation, keeping graph construction fast even in large repositories.

Dependency types

Edges in the project graph have a type that describes how the dependency was detected:

Type	Description
static	Detected from an ES/CommonJS import statement in source code
dynamic	Detected from a dynamic import() call
implicit	Declared manually via implicitDependencies, or inferred by a plugin based on non-import signals

TypeScript and JavaScript analysis

Nx’s built-in dependency analysis understands TypeScript path mappings configured in tsconfig.base.json. When a file imports from a path alias like @myorg/shared-ui, Nx resolves that alias back to the owning project and adds the appropriate edge:

// apps/myapp/src/app/app.tsx
import { Button } from '@myorg/shared-ui'; // → edge: myapp → shared-ui
import { formatCurrency } from '@myorg/utils'; // → edge: myapp → utils

tsconfig.base.json

{
  "compilerOptions": {
    "paths": {
      "@myorg/shared-ui": ["libs/shared-ui/src/index.ts"],
      "@myorg/utils": ["libs/utils/src/index.ts"]
    }
  }
}

Implicit dependencies

Some dependencies cannot be detected from imports alone. Declare them explicitly:

apps/e2e/project.json

{
  "name": "myapp-e2e",
  "implicitDependencies": ["myapp"]
}

You can also use implicitDependencies to declare that a project depends on all other projects (useful for meta tools like linters or formatters):

{
  "name": "workspace-lint",
  "implicitDependencies": ["*"]
}

Visualizing the project graph

Nx provides an interactive graph viewer. Launch it with:

nx graph

This opens a browser window with the full project graph. You can also open it focused on a specific project:

nx graph --focus myapp

Navigating the graph UI

• Click a node to see a tooltip with links to project details
• Click a dependency edge to see which file(s) created that dependency
• Use the search bar to filter projects by name
• Use proximity controls to expand the graph outward from a focused project
• Trace the dependency path between any two projects using Start/End point selection
• In Nx 20+, composite nodes group projects in the same folder — expand them in place to see individual projects

Export options

# Export the graph data as JSON for scripting
nx graph --file=output.json

# Export as a static HTML file (shareable)
nx graph --file=output.html

The interactive UI also has a floating action button to save the current view as a .png image.

How the graph powers affected detection

When you run nx affected -t build, Nx uses the project graph to determine which projects are affected by your changes:

1. Identifies which files changed (e.g., from a git diff against the base branch)
2. Maps those files to their owning projects
3. Traverses the project graph to find all downstream dependents of those projects
4. Runs the task only for the affected set

# Run tests only for projects affected by changes in this branch
nx affected -t test

# Run builds only for affected projects
nx affected -t build

How the graph powers task ordering

Nx creates a task graph from the project graph every time you run a command. The task graph respects both the project graph structure and the dependsOn rules in your target configuration. See Task Pipeline for details on how to configure those rules.

Exploring the task graph

In addition to the project graph, you can visualize the task graph for any command using the --graph flag:

nx build myreactapp --graph
nx run-many --targets build --graph
nx affected --targets build --graph

The task graph view shows:

• Which tasks will run and in what order
• Which executor handles each task
• Which inputs Nx uses to compute the cache hash for each task

Inspecting individual projects

To see all resolved configuration for a specific project — including targets inferred by plugins — run:

nx show project myapp --web

This opens a detailed view of the project’s targets, inputs, outputs, and dependency configuration in your browser.