🔎 Introspect is a tool to traverse the NPM ecosystem and identify quality modules. Use the CLI to upload and examine your project's dependencies.
Clone or download
Latest commit a77740c Jun 18, 2018
Type Name Latest commit message Commit time
Failed to load latest commit information.


introspect logo


🔎 Traverse the NPM ecosystem and investigate the quality of your modules.


gif of introspect


npm i npm-introspect -g


introspect [packages to analyze] [port]

Run introspect in the root directory of any project you are interested in analyzing. It will parse the package.json and return a visualization of your project's dependencies. If it doesn't find a package.json it will launch with a default package, d3, and output a message in the terminal that it was unable to find a packge.json. If you want to analyze a specific package or packages instead of parsing the package.json you can type those package names like introspect react react-native and it will visualize those packages and skip the package.json.

introspect [noDev] [port]

Development dependencies like testing frameworks and module bundlers are common across many packages and not necessarily what you are looking for when exploring NPM. To launch npm-introspect without showing the development dependencies use the -d flag or -noDev option.

introspect [less] [port]

If you want to run introspect with less overhead use the -less option, or -l flag. With the -l flag introspect will output scores to the terminal and not startup a server.


introspect d3 d3-zoom d3-selection eslint through -p 5000

graph screenshot

Here is an example with the less option

introspect -l

screenshot of less option

The Problem

NPM is the largest and fastest growing repository of code. It has grown into an wild ecosystem of competeing projects, rich recombinations, and useful one-line repositories that cover edge-cases. NPM, however, suffers from a search problem, an ever-sprawling arena of code exacerbated by a userbase with lots of young developers. Young developers who will spend many hours dealing with the same problem that many other devlopers have dealt with because they simply don't know that an answer already exists. A healthy NPM ecosystem can provide users suggestions for projects to look at, answers to problems they might encounter, metrics for maintainable code, and best practices for succesful open source projects. A healthy NPM has the ability to save an incredible number of developer work-hours while cultivating more creative projects and less abandonware.

Unfortunately, NPM provides no standard API.

Original Intention

The original intention of this project was to build a tool that helped new developers find projects that they could contribute to- both to develop them as team members and to build a sense of collective responsibility and open-source ethics. There is a notion for how we can design our interaction with chaotic networks so that every positive action blazes a trail for others to follow. At NPM and in technology in general we are experienceing a mass influx of people who may have little experience with code and its culture. This is an amazing opportunity but may cost an 'eternal September'. There is a need to create adaptive user experiences that do a better job of communicating best practices. How are libraries used, what are smart patterns to construct our projects, how can we use open-source to hedge edge cases and solve problems that beginners may not even be aware they have to think about. How do we communicate how to use something in the way we use design to communicate usage in physical goods- when the good in quesiton is code? Unfortunately, I failed to properly define this project but I'm leaving this in the README to give a sense for how we should think about the tooling around NPM and our digital commons.

The Solution

  1. Statistics on repository quality and maintanence
  2. Recommendor systems that group projects and suggest helpful plugins
  3. Tools for collective decision making that help the community converge on projects to support
  4. An api to assist community efforts to build more meaningful diagnostics and research about open source projects
  5. An understanding that NPM is a commons with several inherent weaknesses that are best solved through strong community interaction.

NPM-introspect is a tool that uses NPMS scores to create rich visualizations to explore the packages and the NPM ecosystem. Run introspect in your project root and it will parse the packages in your package.json and launch the visualization locally. There is also a command to skip the visualization and output the most important data to the command line.

Unfortunately, NPM-introspect is not a solution to many of these problems and there would need to be cooperation from NPM for anything to be implemented. This was simply a project for me to explore NPM and build a tool to change how we interact with our package manager.