๐ Visualize the dependencies & sub-dependencies in your Javascript application.
Report Bug
ยท
Request Feature
Table of Contents
indeps is a tool for visualizing the dependencies that make up your JavaScript application. Combing through your lockfile is tedious, and isn't a very efficient way to understand the "bigger picture" of the packages within your project. Discovering the source of clashing dependencies or the dependency path for a specific module can be time consuming, and wears down your CMD + F
keys. indeps attempts to solve this issue by providing a human-friendly UI for displaying & analyzing your projects resolved dependencies.
- Easily search through the dependencies & sub-dependencies within your JavaScript project.
- View the dependency tree for any given package.
- Filter dependencies by various criteria, such as showing only the
@types
packages. Or, only show the packages that you've defined as a development dependency for the project. - Coming soon: Visualize your dependencies in a treemap and/or graph.
On the surface, indeps simply parses both your lockfile (either yarn.lock
or package-lock.json
) and your package.json
file, runs additional analysis on these files, and injects this normalized data into a UI that is served by a local HTTP server. Currently, indeps requires:
- A valid lockfile
- Supports Yarn V1, Yarn V2(berry), and NPM(5+) lock files.
- A valid
package.json
file- As of
v0.1.0
, we require a valid package.json file to run the indeps process. We require information about thedevDependencies
&dependencies
that are defined in yourpackage.json
file, and certain lockfile formats do not provide sufficient indication as to which package/package resolution points to a package that the application defined as a dependency or development dependency. In the future, we may allow lockfile-only analysis, with a limited feature set compared to a full lockfile +package.json
analysis.
- As of
indeps can be ran as either a CLI, or one may also utilize our various function exports to run the indeps processes programatically.
- Node v12+
indeps can be installed locally or globally.
To install indeps on a per-project basis:
npm i -D [email protected]
# or
yarn add -D [email protected]
Alternatively, installing indeps globally allows you to run it easily on any of your local projects. To install globally, run:
npm i -g [email protected]
# or
yarn global add [email protected]
indeps can be used a CLI utility to visualize the dependencies defined within any yarn.lock
file - even if it is not inside a specific project.
If the package was installed globally, you can simply run indeps within any project directory with a valid lockfile & package.json
file. Alternatively, you can specify the files you want to be used for the visualization through the --lock
(-l
) and --pkg
flags:
# Can use either a path relative to your current directory
indeps --lock my-project/yarn.lock --pkg my-project/package.json
# Or specify an absolute path
indeps --lock /users/steve/my-project/yarn.lock --pkg /users/steve/my-project/package.json
# leaving it empty will check for a package.json/lockfile in the current directory
indeps
Path to the lockfile to use for visualization.
Path to the package.json
file to use for the visualization.
The port used to serve the local indeps client. Defaults to 8088
.
Automatically open the client in a browser if one is available on the host machine on server start. Defaults to true
.
You may also use --no-open
as an alias for --open false
Disables the default informational log messages; only display warning & error logs. Defaults to false
.
Although indeps was made primarily with CLI usage in mind, we also export some high-level methods that allow you to run the various steps of the indeps process programatically. This provides a way for users to extend the functionality of indeps, or create plugins & extensions for bundlers or task runners.
import fs from "fs";
import {
/** Parses a string-representation of `package.json` to an indeps-compatible parsed object */
parsePkg,
/** Parses a string-representation of a `yarn.lock` or `package-lock.json` file to an indeps-compatible parsed object */
parseLock,
/** Generates a dependency graph based on the object returned from `parseLock` */
createDependencyGraph,
/** Normalizes all data into a single object. */
createDependencyData,
/** A function that creates an instance of the "Viewer", responsible for managing the local server that handles serving the indeps UI. */
createViewer
} from "indeps";
(async () => {
// Get the raw data of the "package.json" file
const pkgData = fs.readFileSync("/path/to/package.json", "utf8");
// Parse raw data using `parsePkg`
const pkg = parsePkg({
data: pkgData
});
// Get the raw data of the lockfile
const lockData = fs.readFileSync(
"/path/to/package-lock.json", // or `yarn.lock`
"utf8"
);
// Parse using `parseLock`
const lock = parseLock({
type: "yarn",
data: lockData
});
// create a DAG from the packages specified in the lockfile. This is used to determine the require path - or dependency tree - of each module.
const graph = createDependencyGraph(lock);
// Normalize & hydrate all of the necessary data into a complete dependency list.
const data = createDependencyData({
lock,
pkg,
graph
});
// create the viewer instance. The viewer is responsible for running a local HTTP server and serving the indeps UI.
const viewer = createViewer({
data,
port: 8008,
packageName: parsedPkg.name,
open: true
});
// start the server. Returns a node HTTP server instance (`node.httpServer`).
const server = await viewer.startServer();
})();
Current focus is CLI usage - the exported methods will be expanded to be more usable & extendable as we reach closer to v1.0.0
.
Status | Milestone |
---|---|
๐ | Implement NPM & Yarn V2 (berry) support |
๐ง | Improve dependency list UI |
๐ง | Create dependency graph/treemap visualization capabilities |
๐ง | Static site generation |
๐ง | Rewrite of method exports, plugin & theme support |
See the open issues for a full list of proposed features (and known issues).
Distributed under the MIT License. See LICENSE.txt
.