ben-kincaid / indeps Goto Github PK

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 the devDependencies & dependencies that are defined in your package.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.

(back to top)

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]

(back to top)

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.

(back to top)

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.

(back to top)

See the open issues for a full list of proposed features (and known issues).

(back to top)

Distributed under the MIT License. See LICENSE.txt.

(back to top)