0
# npm-check
1

2
npm-check is a comprehensive Node.js library and command-line tool that analyzes npm projects to identify outdated, incorrect, and unused dependencies. It provides an interactive CLI interface for safely updating packages, supports both local and global dependency checking, and works with public and private npm registries.
3

4
## Package Information
5

6
- **Package Name**: npm-check
7
- **Package Type**: npm
8
- **Language**: JavaScript (Node.js)
9
- **Installation**: `npm install -g npm-check` or `npm install npm-check`
10

11
## Core Imports
12

13
```javascript
14
const npmCheck = require('npm-check');
15
```
16

17
For TypeScript:
18

19
```typescript
20
import npmCheck from 'npm-check';
21
```
22

23
## Basic Usage
24

25
### Programmatic API
26

27
```javascript
28
const npmCheck = require('npm-check');
29

30
// Basic usage - check current directory
31
npmCheck()
32
  .then(currentState => {
33
    const packages = currentState.get('packages');
34
    packages.forEach(pkg => {
35
      console.log(`${pkg.moduleName}: ${pkg.installed} -> ${pkg.latest}`);
36
    });
37
  });
38

39
// With options
40
npmCheck({
41
  global: false,
42
  skipUnused: false,
43
  ignoreDev: false,
44
  cwd: './my-project'
45
})
46
  .then(currentState => {
47
    // Process results
48
    const outdatedPackages = currentState.get('packages')
49
      .filter(pkg => pkg.bump && !pkg.notInstalled);
50
  });
51
```
52

53
### Command Line Interface
54

55
```bash
56
# Check current directory
57
npm-check
58

59
# Interactive update mode
60
npm-check -u
61

62
# Check global packages
63
npm-check -g
64

65
# Update all packages without prompting
66
npm-check -y
67

68
# Check only production dependencies
69
npm-check -p
70

71
# Skip unused dependency check
72
npm-check -s
73
```
74

75
## Architecture
76

77
npm-check is built around several key components:
78

79
- **State Management**: Central state object that tracks all analysis data and configuration
80
- **Input Analysis**: Modules that analyze package.json, installed packages, and registry data
81
- **Output Formatting**: Different output modes (static, interactive, batch update)
82
- **CLI Interface**: Command-line wrapper that provides user-friendly interface
83
- **Dependency Detection**: Integration with depcheck for unused dependency analysis
84

85
## Capabilities
86

87
### Programmatic API
88

89
Core programmatic interface for integrating npm-check functionality into other tools and scripts.
90

91
```javascript { .api }
92
function npmCheck(options?: NpmCheckOptions): Promise<CurrentState>;
93

94
interface NpmCheckOptions {
95
  global?: boolean;
96
  update?: boolean;
97
  updateAll?: boolean;
98
  skipUnused?: boolean;
99
  devOnly?: boolean;
100
  ignoreDev?: boolean;
101
  cwd?: string;
102
  saveExact?: boolean;
103
  currentState?: Object;
104
  ignore?: string | string[];
105
  specials?: string;
106
  debug?: boolean;
107
  emoji?: boolean;
108
  spinner?: boolean;
109
  installer?: 'npm' | 'pnpm' | 'yarn' | 'ied' | 'auto';
110
}
111

112
interface CurrentState {
113
  get(key: string): any;
114
  set(key: string, value: any): void;
115
  all(): Object;
116
  inspectIfDebugMode(): void;
117
}
118
```
119

120
[Programmatic API](./programmatic-api.md)
121

122
### Command Line Interface
123

124
Full-featured CLI for interactive and automated dependency management workflows.
125

126
```bash { .api }
127
npm-check [path] [options]
128

129
Options:
130
  -u, --update          Interactive update
131
  -y, --update-all      Update all without prompting  
132
  -g, --global          Check global modules
133
  -s, --skip-unused     Skip unused package check
134
  -p, --production      Skip devDependencies
135
  -d, --dev-only        Only check devDependencies
136
  -i, --ignore <glob>   Ignore dependencies by glob
137
  -E, --save-exact      Save exact versions
138
  --specials <list>     Depcheck specials to include
139
  --no-color           Disable color output
140
  --no-emoji           Disable emoji output
141
  --debug              Enable debug output
142
```
143

144
[Command Line Interface](./cli.md)
145

146
## Types
147

148
```typescript { .api }
149
interface PackageInfo {
150
  moduleName: string;
151
  homepage: string;
152
  regError: any;
153
  pkgError: any;
154
  latest: string;
155
  installed: string;
156
  isInstalled: boolean;
157
  notInstalled: boolean;
158
  packageWanted: string;
159
  packageJson: string;
160
  devDependency: boolean;
161
  usedInScripts: string[] | undefined;
162
  mismatch: boolean;
163
  semverValid: string;
164
  easyUpgrade: boolean;
165
  bump: 'patch' | 'minor' | 'major' | 'prerelease' | 'build' | 'nonSemver' | null;
166
  unused: boolean;
167
}
168

169
type StateKey = 
170
  | 'packages'               // Array of PackageInfo objects
171
  | 'debug'                 // Debug mode status
172
  | 'global'                // Global mode status
173
  | 'cwd'                   // Current working directory
174
  | 'cwdPackageJson'        // Parsed package.json object
175
  | 'emoji'                 // Emoji mode status
176
  | 'globalPackages'        // Global packages data
177
  | 'unusedDependencies'    // Unused dependencies array
178
  | 'missingFromPackageJson' // Missing packages object
179
  | 'update'                // Update mode status
180
  | 'updateAll'             // Update all mode status
181
  | 'skipUnused'            // Skip unused check status
182
  | 'devOnly'               // Dev only mode status
183
  | 'ignoreDev'             // Ignore dev dependencies status
184
  | 'saveExact'             // Save exact versions status
185
  | 'specials'              // Depcheck specials
186
  | 'spinner'               // Spinner enabled status
187
  | 'installer'             // Package installer to use
188
  | 'ignore';               // Ignore patterns for dependencies
189
```