0
# Plugin Configuration Validation
1

2
The `nx-plugin-checks` rule validates Nx plugin configuration files to ensure proper structure, valid implementation paths, and correct schema definitions for generators, executors, and migrations.
3

4
## Capabilities
5

6
### Nx Plugin Checks Rule  
7

8
Validates common Nx plugin configuration files including generators.json, executors.json, migrations.json, and their TypeScript implementations.
9

10
```typescript { .api }
11
/**
12
 * ESLint rule that validates Nx plugin configuration files
13
 * Rule name: "@nx/nx-plugin-checks"
14
 */
15
interface NxPluginChecksRule {
16
  name: "nx-plugin-checks";
17
  meta: {
18
    docs: {
19
      description: "Checks common nx-plugin configuration files for validity";
20
    };
21
    schema: [NxPluginChecksOptions];
22
    messages: Record<MessageIds, string>;
23
  };
24
  defaultOptions: [NxPluginChecksOptions];
25
  create: (context: RuleContext) => RuleListener;
26
}
27
```
28

29
### Configuration Options
30

31
Complete configuration interface for plugin validation behavior.
32

33
```typescript { .api }
34
interface NxPluginChecksOptions {
35
  /** Path to the project's generators.json file, relative to project root */
36
  generatorsJson?: string;
37
  
38
  /** Path to the project's executors.json file, relative to project root */
39
  executorsJson?: string;
40
  
41
  /** Path to the project's migrations.json file, relative to project root */
42
  migrationsJson?: string;
43
  
44
  /** Path to the project's package.json file, relative to project root */
45
  packageJson?: string;
46
  
47
  /** List of valid version specifiers for package versions */
48
  allowedVersionStrings: string[];
49
  
50
  /** Path to TypeScript configuration file for implementation validation */
51
  tsConfig?: string;
52
}
53
```
54

55
### Default Configuration
56

57
Standard defaults for most Nx plugin projects.
58

59
```typescript { .api }
60
const DEFAULT_OPTIONS: NxPluginChecksOptions = {
61
  generatorsJson: 'generators.json',
62
  executorsJson: 'executors.json', 
63
  migrationsJson: 'migrations.json',
64
  packageJson: 'package.json',
65
  allowedVersionStrings: ['*', 'latest', 'next'],
66
  tsConfig: 'tsconfig.lib.json'
67
};
68
```
69

70
### Error Messages
71

72
All possible validation messages returned by the rule.
73

74
```typescript { .api }
75
type MessageIds =
76
  | "missingRequiredSchema"
77
  | "invalidSchemaPath"
78
  | "missingImplementation"
79
  | "invalidImplementationPath"
80
  | "invalidImplementationModule"
81
  | "unableToReadImplementationExports"
82
  | "invalidVersion"
83
  | "missingVersion"
84
  | "noGeneratorsOrSchematicsFound"
85
  | "noExecutorsOrBuildersFound"
86
  | "valueShouldBeObject";
87
```
88

89
**Usage Examples:**
90

91
```typescript
92
// Basic plugin validation
93
{
94
  rules: {
95
    "@nx/nx-plugin-checks": "error"
96
  }
97
}
98

99
// Custom configuration paths
100
{
101
  rules: {
102
    "@nx/nx-plugin-checks": [
103
      "error",
104
      {
105
        generatorsJson: "src/generators.json",
106
        executorsJson: "src/executors.json",
107
        migrationsJson: "migrations.json",
108
        packageJson: "package.json",
109
        tsConfig: "tsconfig.json"
110
      }
111
    ]
112
  }
113
}
114

115
// Custom allowed version strings
116
{
117
  rules: {
118
    "@nx/nx-plugin-checks": [
119
      "error",
120
      {
121
        allowedVersionStrings: ["*", "latest", "next", "beta", "alpha"]
122
      }
123
    ]
124
  }
125
}
126
```
127

128
### Validation Behaviors
129

130
The rule performs comprehensive validation across multiple areas:
131

132
1. **File Existence**: Verifies configuration files exist at specified paths
133
2. **JSON Structure**: Validates JSON syntax and basic structure
134
3. **Schema Validation**: Ensures required schema properties are present and valid
135
4. **Implementation Validation**: Checks that implementation files exist and export correct functions
136
5. **Version Validation**: Validates version strings against allowed patterns
137
6. **Cross-Reference Validation**: Ensures consistency between configuration files and package.json
138

139
### Generator Configuration Validation
140

141
For generators.json files, the rule validates:
142

143
```typescript { .api }
144
interface GeneratorConfig {
145
  generators: {
146
    [name: string]: {
147
      factory: string; // Path to implementation function
148
      schema: string; // Path to JSON schema file
149
      description?: string;
150
      aliases?: string[];
151
      hidden?: boolean;
152
    };
153
  };
154
}
155
```
156

157
**Validation Checks:**
158
- Factory implementation file exists and exports the specified function
159
- Schema file exists and contains valid JSON schema
160
- Implementation function has correct signature
161
- All required properties are present
162

163
### Executor Configuration Validation
164

165
For executors.json files, the rule validates:
166

167
```typescript { .api }
168
interface ExecutorConfig {
169
  executors: {
170
    [name: string]: {
171
      implementation: string; // Path to implementation function
172
      schema: string; // Path to JSON schema file
173
      description?: string;
174
      hasher?: string; // Path to custom hasher function
175
    };
176
  };
177
}
178
```
179

180
**Validation Checks:**
181
- Implementation file exists and exports default executor function
182
- Schema file exists and contains valid JSON schema
183
- Custom hasher function exists if specified
184
- Implementation function returns proper executor result
185

186
### Migration Configuration Validation
187

188
For migrations.json files, the rule validates:
189

190
```typescript { .api }
191
interface MigrationConfig {
192
  generators?: {
193
    [version: string]: {
194
      version: string;
195
      description?: string;
196
      factory?: string; // Path to migration function
197
      cli?: "nx"; // CLI compatibility
198
    };
199
  };
200
  packageJsonUpdates?: {
201
    [version: string]: {
202
      version: string;
203
      packages: {
204
        [packageName: string]: {
205
          version: string;
206
          alwaysAddToPackageJson?: boolean;
207
        };
208
      };
209
    };
210
  };
211
}
212
```
213

214
**Validation Checks:**
215
- Version strings match semantic versioning patterns
216
- Migration factory functions exist and are properly implemented
217
- Package version specifications are valid
218
- Migration descriptions are informative
219

220
### Package.json Integration
221

222
The rule also validates package.json integration:
223

224
```typescript { .api }
225
interface PackageJsonPluginConfig {
226
  "nx-migrations"?: {
227
    migrations: string; // Path to migrations.json
228
  };
229
  generators?: string; // Path to generators.json (legacy)
230
  schematics?: string; // Path to generators.json (Angular compatibility)
231
  executors?: string; // Path to executors.json  
232
  builders?: string; // Path to executors.json (Angular compatibility)
233
}
234
```
235

236
**Validation Checks:**
237
- Migration configuration points to valid migrations.json
238
- Generator/schematic paths point to valid files
239
- Executor/builder paths point to valid files
240
- Plugin configuration is consistent across files
241

242
### TypeScript Implementation Validation
243

244
When tsConfig is specified, the rule performs advanced TypeScript analysis:
245

246
- Validates that implementation files compile successfully
247
- Checks function exports match configuration expectations
248
- Validates parameter types for generator/executor functions
249
- Ensures proper return types for all plugin functions
250

251
### Integration with Nx Plugin System
252

253
The rule understands and validates against Nx plugin conventions:
254

255
- Supports both generators.json and schematics.json naming
256
- Supports both executors.json and builders.json naming  
257
- Validates against Nx plugin API requirements
258
- Integrates with Nx workspace configuration standards