ns-package-graph - visualize packages used in an N|Solid runtime
ns-package-graph is a command-line tool to generate a graphical
representation of the packages being used in an N|Solid runtime.
ns-package-graph [options] [app or instance id]
When run with no arguments, displays some help and a list of running N|Solid application names, and their instance ids.
When you pass an appplication name or instance id as parameter, a matching
instance will be sent the
nsolid-cli package_info command, to capture
information on the process's packages and modules. That information is used to
generate a GraphViz dot formatted graph diagram of package dependencies
in the running program. That output is then passed to the awesome Viz.js
library to convert into SVG, which is then written to stdout.
$ ns-package-graph <nsolid app name or instance id> <?xml version="1.0" encoding="UTF-8" standalone="no"?> <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> <!-- Generated by graphviz version 2.38.0 (20140413.2041) --> ... $ ns-package-graph <nsolid app name or instance id> > packages-graph.svg
The package nodes in the graph output are annotated with color depending on duplicate package status. For duplicate copies of the exact same package name and version, those nodes are colored red - they should have been de-duped. For duplicate copies of the exact same package name but different versions, those nodes are colored yellow.
For example, here's the output from a run of npm version 3, in a few different forms:
Clicking on the link to the SVG file above should open the graph in your browser, allowing you to zoom in to see the node names / versions. The HTML file provides a nicer experience in a browser.
When displaying the SVG file in a browser, either directly, or indirectly via the generated HTML file, the following goodies are available:
- tooltips over nodes and edges
- each package node is a link to it's page at
npmjs.org- just click the node to view
To generate the image in a format other than SVG, use the
option, and then use a Graphviz tool to convert to the format of your
$ ns-package-graph --format dot MyApp > MyApp-packages.dot $ dot -T png -O MyApp-packages.dot # generates MyApp-packages.dot.png
-v --version print the current version -h --help print the help text -g --group group by: "package", "version", "path" -f --format output format: "svg", "dot", "html", "data-url" -c --child child nodes: "dep", "parent" -s --server PORT run server on specified port
--group package --format svg --child dep --server (no default port, must be passed as argument)
--group option changes the grouping of the nodes to show:
package- one node for each unique package, any version, any path loaded
version- one node for each unique package / version, any path loaded
path- node for each unique package / version / path loaded
The number of nodes drawn increases with each group option, respectively.
--format option determines the output:
dot- generate the Graphviz dot file
svg- generate an SVG file from the Graphviz dot file data
html- generate an HTML file with the embedded SVG and zoom controls
data-url- generate a data URL for the SVG image
--child option determines what children nodes are:
dep- children are the dependencies of the package
parent- children are packages that depend on the package
--server option runs the program as an HTTP server. You must pass a port
number to bind the HTTP server to. The server responds to URIs of N|Solid
instance ids or application names, by generating a graph diagram of the packages
in the process. The other options apply, so you'll probably want to use
--format html option for a nicer experience.
A bookmarklet is available to create and view the graph diagram, when invoked
from the N|Solid Console pages. To create the bookmarklet, create a new bookmark
for this page, and then edit it to set the name to
whatever you want), and set the URL to the text below. Customize the URL inside
the bookmarket URL (ie,
http://example.com:4000) to be the root URL of your
ns-package-graph server. Then when you're on an N|Solid Console page which shows
a single app or process, you can click the bookmark and see the package diagram.
To install the
ns-package-graph utility globally, run:
npm install -g https://github.com/pmuellr/ns-package-graph.git
Note that you will to have N|Solid installed and running. Specifically, this
utility will make calls into
nsolid-cli to get information from the same
hub as your N|Solid runtime processes.
For more information on installing N|Solid, see:
Two simple sample applications are included in the package:
Here are the outputs of running
ns-package-graph on the running samples:
.png files were created using the GraphViz
npm version 2 to
npm install it's dependencies,
because that results in duplicated packages. When using
npm version 3,
there aren't any duplicated packages.
The following sort of message will be displayed if the
nsolid-cli command is
not installed. Refer to the N|Solid installation instructions above.
$ ns-package-graph error running `nsolid-cli info`: Command failed: nsolid-cli info /bin/sh: nsolid-cli: command not found
nsolid-cli related errors, see the help information for that
command, by running:
$ nsolid-cli --help
Eg, if you aren't running the N|Solid hub on the default ports, you can override
the defaults by creating a