Explore your Workspace

Nx understands your workspace as a collection of projects. Each project can be explored to view the different tasks which can be run.

The projects in the workspace have dependencies between them and form a graph known as the Project Graph. Nx uses this project graph in many ways to make informed decisions such as which tasks to run, when the results of a task can be restored from cache, and more.

In addition to the project graph, Nx also runs your tasks as a Task Graph. This is a separate graph of tasks and their dependencies which is based on the project graph and determines the way in which the tasks are executed.

Nx allows you to interactively explore your workspace through a UI which shows the information above. Using this tool is vital to understanding both your workspace as well as how Nx behaves.

This guide will teach you to use this tool to explore projects, the project graph, and the task graphs for your workspace.

Explore Projects in your Workspace

Projects in Nx are the different parts of the monorepo which can have tasks run for them.

The best way to see what projects are in your workspace is to view the project graph which will be covered in the next section. Another way is to look at the Projects pane in Nx Console or run nx show projects to show a list of projects in your terminal.

You can see more details about a specific project in Nx Console or by running nx show project <project-name> --web. Both methods will show something like the example below:

The view shows a list of targets which can be run by Nx. Each target has different options which determine how Nx runs the task.

Explore the Project Graph

Nx understands the projects in your workspace as a graph and uses this understanding to behave intelligently. Exploring this graph visually is vital to understanding how your code is structured and how Nx behaves. It always stays up to date without having to actively maintain a document as it is calculated by analyzing your source code.

Launching the Project Graph

To launch the project graph visualization for your workspace, use Nx Console or run:

This will open a browser window with an interactive view of the project graph of your workspace.

Focusing on Valuable Projects

Viewing the entire graph can be unmanageable even for smaller repositories, so there are several ways to narrow the focus of the visualization down to the most useful part of the graph at the moment.

1. Focus on a specific project and then use the proximity and group by folder controls in the sidebar to modify the graph around that project. You can also start the graph with a project focused by running nx graph --focus <project-name>.
2. Use the search bar to find all projects with names that contain a certain string.
3. Manually hide or show projects in the sidebar.

Once the graph is displayed, you can explore deeper by clicking on nodes and edges in the graph. Click on a node to show a tooltip which also has a link to view more details about the project. You can trace the dependency chain between two projects by choosing a Start and End point in the project tooltips. Click on any dependency line to find which file(s) created the dependency.

Composite nodes represent a set of projects in the same folder and can be expanded in place to show all the individual projects and their dependencies. You can also "focus" a composite node to render a graph of just the projects inside that node. Composite nodes are essential to navigate a graph of even a moderate size.

Try playing around with a fully interactive graph on a sample repo or look at the more limited example below:

Export Project Graph to JSON

If you prefer to analyze the underlying data of the project graph with a script or some other tool, you can run:

This will give you all the information that is used to create the project graph visualization.

Export the Project Graph as an Image

There is a floating action button in the bottom right of the project graph view which will save the graph as a .png file. Sharing this image with other developers is a great way to express how a project fits into the workspace. Some moments which you may want to share these images are:

• When providing a high-level overview of the workspace
• When introducing new project(s) into the workspace
• When changing how project(s) are related
• To share which other projects are directly affected by changes you are making

Explore the Task Graph

Nx uses the project graph of your workspace to determine the order in which to run tasks. Pass the --graph flag to view the task graph which is executed by Nx when running a command.

Click on the nodes of this graph to see more information about the task such as:

• Which executor was used to run the command
• Which inputs are used to calculate the computation hash.
• A link to see more details about the project which the task belongs to

Dependencies in this graph mean that Nx will need to wait for all task dependencies to complete successfully before running the task.