0
# Dependency Management
1

2
The `dependency-checks` rule validates package.json dependencies against actual code usage, ensuring dependency declarations stay synchronized with implementation requirements across the workspace.
3

4
## Capabilities  
5

6
### Dependency Checks Rule
7

8
Analyzes project files to detect missing dependencies, obsolete packages, and version mismatches in package.json files.
9

10
```typescript { .api }
11
/**
12
 * ESLint rule that validates package.json dependencies against actual usage
13
 * Rule name: "@nx/dependency-checks"
14
 */
15
interface DependencyChecksRule {
16
  name: "dependency-checks";
17
  meta: {
18
    type: "suggestion";
19
    docs: {
20
      description: "Checks dependencies in project's package.json for version mismatches";
21
    };
22
    fixable: "code";
23
    schema: [DependencyChecksOptions];
24
    messages: Record<MessageIds, string>;
25
  };
26
  defaultOptions: [DependencyChecksOptions];
27
  create: (context: RuleContext) => RuleListener;
28
}
29
```
30

31
### Configuration Options
32

33
Complete configuration interface for dependency validation behavior.
34

35
```typescript { .api }
36
interface DependencyChecksOptions {
37
  /** Build target names used to determine production vs development dependencies */
38
  buildTargets?: string[];
39
  
40
  /** Check for dependencies used in code but missing from package.json */
41
  checkMissingDependencies?: boolean;
42
  
43
  /** Check for dependencies in package.json that are not used in code */
44
  checkObsoleteDependencies?: boolean;
45
  
46
  /** Check for version mismatches between declared and installed versions */
47
  checkVersionMismatches?: boolean;
48
  
49
  /** Package names to ignore during dependency checks */
50
  ignoredDependencies?: string[];
51
  
52
  /** File patterns to exclude from dependency analysis */
53
  ignoredFiles?: string[];
54
  
55
  /** Include transitive dependencies in the analysis */
56
  includeTransitiveDependencies?: boolean;
57
  
58
  /** Use local workspace paths instead of npm versions for workspace dependencies */
59
  useLocalPathsForWorkspaceDependencies?: boolean;
60
  
61
  /** Runtime helper packages that should be treated specially */
62
  runtimeHelpers?: string[];
63
}
64
```
65

66
### Default Configuration
67

68
The rule comes with sensible defaults for most Nx workspaces.
69

70
```typescript { .api }
71
const DEFAULT_OPTIONS: DependencyChecksOptions = {
72
  buildTargets: ['build'],
73
  checkMissingDependencies: true,
74
  checkObsoleteDependencies: true, 
75
  checkVersionMismatches: true,
76
  ignoredDependencies: [],
77
  ignoredFiles: [],
78
  includeTransitiveDependencies: false,
79
  useLocalPathsForWorkspaceDependencies: false,
80
  runtimeHelpers: []
81
};
82
```
83

84
### Error Messages
85

86
All possible validation messages returned by the rule.
87

88
```typescript { .api }
89
type MessageIds =
90
  | "missingDependency"
91
  | "obsoleteDependency" 
92
  | "versionMismatch"
93
  | "missingDependencySection";
94

95
interface ErrorMessages {
96
  missingDependency: string; // 'The "{{projectName}}" project uses the following packages, but they are missing from "{{section}}":{{packageNames}}'
97
  obsoleteDependency: string; // 'The "{{packageName}}" package is not used by "{{projectName}}" project.'
98
  versionMismatch: string; // 'The version specifier does not contain the installed version of "{{packageName}}" package: {{version}}.'
99
  missingDependencySection: string; // 'Dependency sections are missing from the "package.json" but following dependencies were detected:{{dependencies}}'
100
}
101
```
102

103
**Usage Examples:**
104

105
```typescript
106
// Basic dependency checking
107
{
108
  rules: {
109
    "@nx/dependency-checks": [
110
      "error",
111
      {
112
        checkMissingDependencies: true,
113
        checkObsoleteDependencies: true,
114
        checkVersionMismatches: true
115
      }
116
    ]
117
  }
118
}
119

120
// Ignore specific packages and files
121
{
122
  rules: {
123
    "@nx/dependency-checks": [
124
      "error",
125
      {
126
        ignoredDependencies: [
127
          "@types/node", // Type definitions
128
          "nx", // Workspace tooling
129
          "typescript" // Build tooling
130
        ],
131
        ignoredFiles: [
132
          "**/*.spec.ts", // Test files
133
          "**/*.stories.ts", // Storybook files
134
          "**/jest.config.ts" // Config files
135
        ]
136
      }
137
    ]
138
  }
139
}
140

141
// Custom build targets and workspace handling
142
{
143
  rules: {
144
    "@nx/dependency-checks": [
145
      "error",
146
      {
147
        buildTargets: ["build", "build-prod", "compile"],
148
        useLocalPathsForWorkspaceDependencies: true,
149
        includeTransitiveDependencies: false,
150
        runtimeHelpers: ["tslib", "@babel/runtime"]
151
      }
152
    ]
153
  }
154
}
155

156
// Development vs production dependency checking
157
{
158
  rules: {
159
    "@nx/dependency-checks": [
160
      "error",
161
      {
162
        buildTargets: ["build"],
163
        // Will check that runtime dependencies are in dependencies
164
        // and build-time dependencies are in devDependencies
165
        checkMissingDependencies: true
166
      }
167
    ]
168
  }
169
}
170
```
171

172
### Validation Behaviors
173

174
The rule performs several types of dependency analysis:
175

176
1. **Missing Dependency Detection**: Identifies imports and requires not declared in package.json
177
2. **Obsolete Dependency Detection**: Finds declared dependencies that aren't used in the codebase
178
3. **Version Mismatch Detection**: Compares declared versions with installed versions
179
4. **Dependency Section Validation**: Ensures dependencies are in the correct section (dependencies vs devDependencies)
180
5. **Transitive Dependency Analysis**: Optionally includes transitive dependencies in checks
181
6. **Workspace Integration**: Handles workspace dependencies with local paths
182

183
### Build Target Integration
184

185
The rule uses build targets to determine dependency placement:
186

187
- **Runtime Dependencies**: Required during build execution (goes in `dependencies`)
188
- **Build Dependencies**: Only needed during build process (goes in `devDependencies`)
189
- **Test Dependencies**: Only needed for testing (goes in `devDependencies`)
190

191
### File Analysis Patterns
192

193
The rule analyzes various import patterns:
194

195
```typescript
196
// ES6 imports
197
import { something } from 'package-name';
198
import * as pkg from 'package-name';
199
import pkg from 'package-name';
200

201
// CommonJS requires  
202
const pkg = require('package-name');
203
const { something } = require('package-name');
204

205
// Dynamic imports
206
const pkg = await import('package-name');
207

208
// Type-only imports (TypeScript)
209
import type { SomeType } from 'package-name';
210
```
211

212
### Integration with Nx Workspace
213

214
The rule integrates with Nx workspace features:
215

216
- Reads project configurations from workspace.json/angular.json
217
- Understands workspace library dependencies
218
- Handles workspace-relative imports
219
- Supports workspace package linking
220
- Integrates with workspace dependency graph