0
# npm-check-updates
1

2
npm-check-updates upgrades your package.json dependencies to the latest versions, ignoring specified versions. It maintains existing semantic versioning policies, only modifies package.json files, and provides both CLI and programmatic interfaces with support for multiple package managers.
3

4
## Package Information
5

6
- **Package Name**: npm-check-updates
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install -g npm-check-updates`
10

11
## Core Imports
12

13
```typescript
14
import ncu, { type RunOptions } from "npm-check-updates";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const ncu = require("npm-check-updates");
21
```
22

23
## Basic Usage
24

25
### CLI Usage
26

27
```bash
28
# Check for updates
29
ncu
30

31
# Upgrade package.json
32
ncu -u
33

34
# Interactive mode
35
ncu --interactive
36

37
# Filter specific packages
38
ncu --filter "@angular/*"
39

40
# Target specific update types
41
ncu --target minor
42
```
43

44
### Programmatic Usage
45

46
```typescript
47
import ncu, { RunOptions } from "npm-check-updates";
48

49
// Basic upgrade
50
const upgrades = await ncu({ upgrade: true });
51

52
// With options
53
const upgrades = await ncu({
54
  packageFile: "./package.json",
55
  upgrade: true,
56
  target: "minor",
57
  filter: /^@myorg\//,
58
  interactive: false
59
});
60
```
61

62
## Architecture
63

64
npm-check-updates is built around several key components:
65

66
- **Main API**: Single `run()` function that handles all upgrade operations
67
- **Configuration System**: Comprehensive options through `RunOptions` interface and CLI flags
68
- **Package Manager Support**: Pluggable architecture supporting npm, yarn, pnpm, deno, bun, and static registries
69
- **Version Resolution**: Sophisticated version targeting with multiple strategies (latest, minor, patch, etc.)
70
- **Interactive Mode**: User-guided upgrade selection with filtering and grouping
71
- **Doctor Mode**: Test-driven upgrade validation to identify breaking changes
72

73
## Capabilities
74

75
### Programmatic API
76

77
Core programmatic interface for integrating npm-check-updates into Node.js applications. Provides the main `run()` function and comprehensive type definitions.
78

79
```typescript { .api }
80
function run(
81
  runOptions?: RunOptions, 
82
  options?: { cli?: boolean }
83
): Promise<PackageFile | Index<VersionSpec> | void>;
84

85
export type { RunOptions };
86
```
87

88
[Programmatic API](./programmatic-api.md)
89

90
### CLI Interface
91

92
Command-line interface providing access to all functionality through terminal commands. Supports over 50 configuration options for fine-grained control.
93

94
```bash { .api }
95
npm-check-updates [options] [filter...]
96
ncu [options] [filter...]
97

98
# Key options:
99
--upgrade, -u          # Overwrite package file with upgraded versions
100
--interactive, -i      # Enable interactive prompts
101
--target <target>      # Version targeting strategy
102
--filter <pattern>     # Package name filtering
103
--global, -g           # Check global packages
104
--doctor               # Test-driven upgrade validation
105
```
106

107
[CLI Interface](./cli-interface.md)
108

109
### Configuration Options
110

111
Comprehensive configuration system supporting both programmatic and CLI usage. Controls all aspects of dependency checking and upgrading behavior.
112

113
```typescript { .api }
114
interface RunOptions {
115
  upgrade?: boolean;
116
  target?: 'latest' | 'newest' | 'greatest' | 'minor' | 'patch' | 'semver' | `@${string}` | TargetFunction;
117
  filter?: string | RegExp | (string | RegExp)[] | FilterFunction;
118
  packageManager?: 'npm' | 'yarn' | 'pnpm' | 'deno' | 'bun' | 'staticRegistry';
119
  interactive?: boolean;
120
  global?: boolean;
121
  doctor?: boolean;
122
  // ... and 40+ additional options
123
}
124
```
125

126
[Configuration Options](./configuration.md)
127

128
### Package Manager Support
129

130
Multi-package manager support with pluggable architecture. Each package manager provides standardized version resolution methods.
131

132
```typescript { .api }
133
interface PackageManager {
134
  latest: (packageName: string, currentVersion: VersionSpec, options: Options) => Promise<VersionSpec | null>;
135
  newest: (packageName: string, currentVersion: VersionSpec, options: Options) => Promise<VersionSpec | null>;
136
  greatest: (packageName: string, currentVersion: VersionSpec, options: Options) => Promise<VersionSpec | null>;
137
  // ... additional resolution methods
138
}
139
```
140

141
[Package Manager Support](./package-managers.md)
142

143
### Type Definitions
144

145
Complete TypeScript type definitions for all configuration options, data structures, and function signatures. Enables full type safety in programmatic usage.
146

147
```typescript { .api }
148
type VersionSpec = string;
149
type Index<T> = Record<string, T>;
150

151
interface PackageFile {
152
  dependencies?: Index<VersionSpec>;
153
  devDependencies?: Index<VersionSpec>;
154
  optionalDependencies?: Index<VersionSpec>;
155
  peerDependencies?: Index<VersionSpec>;
156
  // ... additional package.json properties
157
}
158
```
159

160
[Type Definitions](./types.md)