npm-dl-stats

📦 A simple CLI tool to check npm package download statistics.

Features

• 🚀 View download statistics for any npm package
• 📊 Display daily, weekly, and monthly downloads in a single view
• 🎨 Sort packages by download count with color-coded ranking
• 🎯 Interactive package selection with --pick option
• 💾 Save and manage package lists for quick access
• ⚡ Zero configuration required for basic usage
• 🌈 Beautiful colored output with chalk

Installation

Global Installation (Recommended)

npm install -g npm-dl-stats

Local Development

git clone https://github.com/a-lost-social-misfit/npm-dl-stats.git
cd npm-dl-stats
npm install
npm run build
npm link

Quick Start

# View downloads for a single package
npm-dl-stats react

# View downloads for multiple packages
npm-dl-stats react,vue,svelte

# Create a list from your npm username
npm-dl-stats init me

# View your saved list
npm-dl-stats me

# Interactive package selection
npm-dl-stats me --pick

Commands

init <list-name>

Initialize a new package list by searching for packages associated with an npm username.

npm-dl-stats init my-packages

What it does:

1. Checks if the list already exists (prompts for overwrite confirmation)
2. Prompts for your npm username
3. Searches for all packages you maintain
4. Saves the list to ~/.config/npm-dl-stats/config.json

Refreshing your list:

If you've published new packages and want to update your list:

npm-dl-stats init me

When prompted with "Overwrite?", press Y to refresh with the latest packages.

config

Show your configuration file location and saved lists.

npm-dl-stats config

Output example:

⚙️  Configuration

Location: /Users/username/.config/npm-dl-stats/config.json

Lists:
  me (4 packages)
    - package-one
    - package-two
    - package-three
    - package-four

<list-name|packages>

Show download statistics for packages.

# Use a saved list
npm-dl-stats me

# Single package
npm-dl-stats react

# Multiple packages (comma-separated)
npm-dl-stats react,vue,svelte

Options

--pick

Interactively select packages from a list before fetching statistics.

npm-dl-stats me --pick

Example interaction:

📋 Select packages:

  1. package-one
  2. package-two
  3. package-three
  4. ALL

Select (1-4 or comma-separated): 1,3

--help / -h

Show help message.

npm-dl-stats --help

--version / -v

Show version number.

npm-dl-stats --version

Output Features

Three-Period Display

By default, the tool shows download statistics for three time periods:

• DAILY - Last 24 hours
• WEEKLY - Last 7 days
• MONTHLY - Last 30 days

This gives you a complete view of your package's download trends at a glance.

Example output:

📦 npm downloads

PACKAGE               DAILY  WEEKLY  MONTHLY
create-neomutt-gmail    265     265      265
md-blog-core             22     192      192
config-fs-utils          83      83       83
-----------------------------------------
Total                   370     540      540

Color-Coded Ranking

• 🥇 1st place - Bold green (highest downloads)
• 🥈 2nd place - Green
• 🥉 3rd place - Yellow
• Others - Gray

Automatic Sorting

Packages are automatically sorted by monthly download count in descending order.

Total Count

The total download count for each period is displayed at the bottom.

Configuration

Configuration File Location

• macOS/Linux: ~/.config/npm-dl-stats/config.json
• Windows: %USERPROFILE%\.config\npm-dl-stats\config.json

Configuration Format

{
  "lists": {
    "me": [
      "package-one",
      "package-two"
    ],
    "favorites": [
      "react",
      "vue",
      "svelte"
    ]
  }
}

Manual Editing

You can manually edit the configuration file to:

• Add or remove packages from lists
• Create new lists
• Delete lists

Examples

Check Your Own Packages

# First time: create a list
npm-dl-stats init me

# Anytime: check downloads
npm-dl-stats me

# Refresh your list (after publishing new packages)
npm-dl-stats init me
# → Press Y to overwrite with latest packages

Compare Frameworks

npm-dl-stats react,vue,svelte,angular

Track Specific Packages

# Create a custom list
npm-dl-stats init frameworks

# Or manually edit config.json:
# {
#   "lists": {
#     "frameworks": ["react", "vue", "svelte"]
#   }
# }

# View downloads
npm-dl-stats frameworks

Troubleshooting

Command not found

If npm-dl-stats is not recognized after installation:

1. Check npm global bin path: npm bin -g
2. Ensure it's in your PATH
3. Try: npx npm-dl-stats instead

No packages found

If you see "No packages found" for your username:

1. Verify your npm username is correct
2. Check that you have published packages
3. Try searching manually: npm search --maintainer=your-username

API Errors

If you encounter API errors:

1. Check your internet connection
2. npm API may be temporarily down
3. Try again after a few minutes

Configuration Issues

To reset your configuration:

rm ~/.config/npm-dl-stats/config.json

Then run npm-dl-stats init again.

API Usage

This tool uses the official npm APIs:

• Downloads API: https://api.npmjs.org/downloads/point/{period}/{packages}
• Search API: https://registry.npmjs.org/-/v1/search

No authentication is required. These are public APIs provided by npm.

Development

Prerequisites

• Node.js 18 or higher
• npm or yarn

Setup

# Clone the repository
git clone https://github.com/a-lost-social-misfit/npm-dl-stats.git
cd npm-dl-stats

# Install dependencies
npm install

# Build
npm run build

# Link for local testing
npm link

# Test
npm-dl-stats --help

Project Structure

npm-dl-stats/
├── src/
│   ├── types.ts              # Type definitions
│   ├── config.ts             # Pure functions (config operations)
│   ├── io/
│   │   ├── fs.ts             # File I/O (side effects)
│   │   └── fetch.ts          # HTTP requests (side effects)
│   ├── commands/
│   │   ├── init.ts           # Init command
│   │   ├── config.ts         # Config command
│   │   └── show.ts           # Show command
│   └── index.ts              # Entry point
├── package.json
├── tsconfig.json
└── README.md

Design Principles

• Separation of concerns: Pure functions vs. side effects
• Minimal dependencies: Only minimist and chalk
• Type safety: Full TypeScript coverage
• Testability: Functions are easy to test

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Author

a-lost-social-misfit

Links

• npm: https://www.npmjs.com/package/npm-dl-stats
• GitHub: https://github.com/a-lost-social-misfit/npm-dl-stats
• Issues: https://github.com/a-lost-social-misfit/npm-dl-stats/issues