npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

packdoc

v1.3.0

Published

CLI Tool to control package.json health, it can lint, pin versions via lock files, checking engines and check unused/missing dependencies

Downloads

744

Readme

packdoc

CLI Tool to control package.json health, it can lint, pin versions via lock files, checking engines and check unused/missing dependencies

Why ?

Ive written this tool mainly as an Continous Integration helper, in my company we had several scripts for package health checks and i wanted to have everything in one CLI.
By now i also focus more on daily user tasks simply to make OUR workflow easier.
This project also dogfeeds itself as you can see here: https://gitlab.com/FreaKzero/packdoc/blob/master/.gitlab-ci.yml

Install

npm:
npm install -g packdoc
yarn:
yarn global add packdoc

Linting defaults

I wont "loosen" the linting defaults as are they now. Based on my experience and the usecase i have right now the best way to ensure the stuff "can be built" is that you fix your versions in the package.json regardless of package-lock.json or yarn.lock. I know this is highly opiononated so as i decided to publish the package for the public i ensured that this would be configureable - so please dont make issue requests for the standard linting.

Engines Command

When you want to use it

  • You want to validate Alien Technologies which yarn wont resolve (The engine "XXX" appears to be invalid)
  • Giving fast help to your developers how to update certain engines
  • Using NPM and want to validate your engines

Drawbacks

  • In some cases when using yarn you have to ignore the engines validation

Troubleshooting

  • If you run into a incompatible module error with yarn
    run packdoc engines --strict first and then use yarn with yarn --ignore-engines

  • My Alientechnology spits out more than a version string how can i validate ?
    see Plugin development

Which Engines are supported out of the box ?
See variable enginesDefault in https://gitlab.com/FreaKzero/packdoc/blob/master/src/settings.js

Plugin Development

Put a pluginfile named packdoc-plugin.js in your project root folder to activate plugins.

Engine Plugin

Feel free to make an issue or Merge request with your engine-plugins to see them integrated into this project.
Output problem Example: git --version

git version 2.11.0

Plugin:

module.exports = {
  // plugin for engines
  engines: {
    // the bin which is used in package.json
    git: {
      // the parameter to use for outputting the version string
      param: '--version',
      // String transformer - the value will be sanitized after this step with semver.clean
      transform: (value) => value.split(' ')[2] || null,
      // the URL which will be shown when versioncheck fails
      url: 'https://git-scm.com/downloads'
    }
  }
}

Depcheck Plugin

The packdoc usage command uses depcheck (https://github.com/depcheck/depcheck) internally.
When you need a custom configuration for it you can use a plugin entry to overwrite the current behaviour.
The properties usageIgnore and usageIgnoreDirs in your package json will not work anymore (because overwritten)

Example:

module.exports = {
  // plugin for depcheck
  depcheck: (depcheck, pkg) => ({
    // the depcheck library will be resolved in this callback so you dont have to require it
    // you can access properties of your package json via the pkg variable
    ignoreBinPackage: false,
    skipMissing: false,
    ignoreDirs: [],
    ignoreMatches: [],
    parsers: {
      '*.js': depcheck.parser.es6,
      '*.jsx': depcheck.parser.jsx
    },
    detectors: [
      depcheck.detector.requireCallExpression,
      depcheck.detector.importDeclaration
    ],
    specials: [depcheck.special.webpack, depcheck.special.babel]
  })
};
Usage

  $ packdoc usage
    Check unused and missing dependencies
  Options  
    --strict, -s         Strict, exits with 1 when missing or unused deps are found

  $ packdoc lint
    package.json linting
  Options  
    --strict, -s         Strict, exits with 1 when linting issues are found
    --list, -l           Show list of current applied linting rules

  $ packdoc fix
    Fix issues in package.json - omit all options to fix everything
  Options
    --pin, -p            Pins versions based on lockfile
    --sort, -s           Sorts dependencies alphabetically
    --install, -i        Install missing dependencies 

  $ packdoc audit
    Runs engine validation, usage and <manager> audit command
  Options
    --strict,s           Strict, exits with 1 when audit issues are found

  $ packdoc engines
    Check and give help for engines entry in package.json
    see ${pkg.repository} for plugin development
  Options
    --strict, -s         Strict, exits with 1 when engine issues are found
    --list, -l           Show list of registered engine validators (also plugins)

  $ packdoc publish <semver> --token=<token>
    CI helper to publish packages to a registry (always semver strict)
    semver check -> overwrite package.version -> generating ~/.npmrc -> npm publish
  Options  
    --token, -t          authToken for your registry (required)
    --registry, -r       Registry where to publish (default: //registry.npmjs.org)

  $ packdoc bump <semver>
    Tool for versioning (overwrite) package.json or checking semver without writing
  Options
    --check, -c          Check if given version is SEMVER conform without writing to package.json
    --loose, -l          loose versioning
  
  Setup Example

  {
    "packdoc": {
      // linting rules overwrite, default []
      // rule definition documentation: https://github.com/tclindner/npm-package-json-lint/wiki
      "lint": {'require-homepage': 'off'},
      // ignore false-positives for packdoc usage command, default []
      "usageIgnore": ["@babel/*", "*eslint*"],
      // ignore directories for packdoc usage command, default []
      "usageIgnoreDirs": ['build', 'dist'],
      // npm or yarn, default yarn
      "manager": "yarn"
    }
  }

Changelog

Version 0.0.7

  • REFACTOR install flag now on fix command
  • FEATURE check flag for bump
  • REFACTOR usage and added

Version 0.1.0

  • FEATURE Engine Checker and Helper
  • FEATURE Plugin System (engines only)

Version 1.0.0

  • BREAK Remove --dir Flag for bump
  • ADD engine checker for git
  • FEATURE npm publish helper for ci systems

Version 1.1.0

  • BREAK --rules for lint is now --list
  • FEATURE depcheck config plugin
  • FEATURE --list flag for engines

Version 1.2.0

  • FEATURE package contents inected in depcheck plugin
  • FEATURE directoryignore rule in packagejson for usage command

Version 1.3.0

  • FEATURE audit command