This post has originally been published on https://juristr.com/blog/2020/09/use-nx-dep-graph-in-custom-scripts. Go to juristr.com/blog for more content
One of the powerful pillars of the open-source Nx monorepo toolkit is its dependency graph. In this article, we're going to look into how we can leverage it in our own scripts.
Nx is an open source dev toolkit to help you scale development with monorepos. What makes Nx particularly stand out is
- dependency graph - Nx understands your workspace
- "affected" commands - that allow you to only build what really changed
- computational caching - Victor Savkin also wrote a blog post on "How to never build or test twice"
- it is tech agnostic - while Nx currently focuses mostly on the JavaScript ecosystem, there's nothing in Nx that is particularly bound to it. As such even Java or .Net projects can be built with it
In this article I'd like to focus on the dependency graph in particular. Behind the scenes, whenever you reference a library within your workspace, Nx keeps track of that. By knowing the structure of the monorepo, Nx is able to provide significant improvements to the developer experience. One such improvement are the so-called “affected” commands. For instance to run your tests:
$ nx affected:test
or
$ nx affected:build
to run the build of your apps and libs. Affected commands only execute the test/build/... on the changed apps and libs. As you can imagine, such commands can help you speed up your CI pipeline time quite a bit. Read more about it on the Nx docs.
The interesting part is that the graph can also be visualized by running
$ nx dep-graph
or by running affected:dep-graph
to only visualize the affected nodes.
Isaac Mann has a short video that walks you through the visualization of the dep-graph
Access the project-graph from code
Nx comes with a set of built-in automation. But after all, each workspace is unique and you should customize it to your needs. For those custom automation scripts, it might be helpful to be able to leverage the dependency graph as well. There are several ways this can be done.
Approach 1: From TypeScript
Inside your TypeScript files, you can get the nodes of the dep-graph as follows:
import { createProjectGraph } from '@nrwl/workspace/src/core/project-graph';
const graph = createProjectGraph();
Note, the import is a deep import grabbing the function from the core/project-graph
file. Since that is not part of the public API, it might be subject to changes. Just be aware of that.
Approach 2: Output to JSON
You can also output the graph into a JSON file like
nx dep-graph --file=testgraph.json
This is especially useful if you need to pipe it into another program again.
Approach 3: Print Affected
If you look at the distributed CI setup on the Nx docs, there’s an example for the Azure setup, which uses the dependency graph to calculate the affected nodes for then distributing the build accordingly.
This is an excerpt from that Node.js script:
const execSync = require('child_process').execSync;
const array = JSON.parse(
execSync(`npx nx print-affected --base=${baseSha}`)
.toString()
.trim()
).tasks.map((t) => t.target.project);
Approach 4: Print Affected Apps & Libs
The above mentioned approach 3 gives you already a lot of flexibility because it allows you to filter and manipulate the resulting JSON output.
As an alternative you can also use affected:apps
and affected:libs
. Especially if you pass the —-plain
flag, it gives you a plain space-separated list of apps/libs you can again parse from a custom script.
$ nx affected:apps —-base=master —-plain
More can be found on the Nx docs.
Where to use it
There are two primary use cases for this inside an Nx monorepo.
- Workspace schematics - Schematics is a fancy word for “generators”, scripts that can be written in TypeScript and which are able to create, update or delete code from your workspace. Nx itself comes with a set of built-in schematics. Workspace schematics allow you to create ad-hoc schematics inside your monorepo
-
Custom scripts - These are usually placed in the
tools
folder of your Nx repo and can be shell scripts, Node.js scripts or whatever you really like. - Optimize your CI setup - by implementing distributed builds that parallelize across multiple nodes.
Conclusion
We’ve briefly looked into the Nx dependency graph, how it works, and especially how you can leverage it from your own code.
Learn more
🧠 Nx Docs
👩💻 Nx GitHub
💬 Nrwl Community Slack
📹 Nrwl Youtube Channel
🥚 Free Egghead course
🧐 Need help with Angular, React, Monorepos, Lerna or Nx? Talk to us 😃
Also, if you liked this, click the ❤️ and make sure to follow Juri and Nx on Twitter for more!
Top comments (0)