0
# Plugin System
1

2
Nx plugin infrastructure for automatic Jest project detection and configuration inference. The plugin system enables Nx to automatically discover Jest configurations and create appropriate build targets without manual configuration.
3

4
## Capabilities
5

6
### Plugin Node Creation
7

8
Functions for creating Nx plugin nodes that automatically detect and configure Jest projects.
9

10
```typescript { .api }
11
/**
12
 * Create nodes for Jest plugin (v1 API)
13
 * @param configFilePath - Path to Jest configuration file
14
 * @param options - Plugin configuration options
15
 * @param context - Nx plugin creation context
16
 * @returns Plugin node creation result
17
 */
18
function createNodes(
19
  configFilePath: string,
20
  options: JestPluginOptions | undefined,
21
  context: CreateNodesContext
22
): CreateNodesResult;
23

24
/**
25
 * Create nodes for Jest plugin (v2 API with enhanced performance)
26
 * @param configFilePath - Path to Jest configuration file
27
 * @param options - Plugin configuration options
28
 * @param context - Enhanced plugin creation context
29
 * @returns Promise resolving to plugin node creation result
30
 */
31
function createNodesV2(
32
  configFilePath: string,
33
  options: JestPluginOptions | undefined,
34
  context: CreateNodesContextV2
35
): Promise<CreateNodesResult>;
36
```
37

38
### Jest Plugin Options
39

40
Configuration interface for customizing Jest plugin behavior.
41

42
```typescript { .api }
43
interface JestPluginOptions {
44
  /** Name of the primary test target (default: 'test') */
45
  targetName?: string;
46
  /** Name of the CI-optimized test target (default: 'test-ci') */
47
  ciTargetName?: string;
48
  /** Name for grouping atomized tasks on CI */
49
  ciGroupName?: string;
50
  /** 
51
   * Disable jest-config and jest-runtime for faster but potentially less accurate configuration loading
52
   * @default false
53
   */
54
  disableJestRuntime?: boolean;
55
}
56
```
57

58
**Usage Examples:**
59

60
```typescript
61
// nx.json plugin configuration
62
{
63
  "plugins": [
64
    {
65
      "plugin": "@nx/jest/plugin",
66
      "options": {
67
        "targetName": "test",
68
        "ciTargetName": "test-ci",
69
        "ciGroupName": "jest-tests"
70
      }
71
    }
72
  ]
73
}
74
```
75

76
### Plugin Context Interfaces
77

78
Context objects provided to plugin node creation functions.
79

80
```typescript { .api }
81
interface CreateNodesContext {
82
  /** Workspace root directory */
83
  workspaceRoot: string;
84
  /** Configuration file being processed */
85
  configFiles: string[];
86
  /** Nx.json configuration */
87
  nxJsonConfiguration: NxJsonConfiguration;
88
}
89

90
interface CreateNodesContextV2 extends CreateNodesContext {
91
  /** Enhanced context with additional metadata */
92
  readonly configFiles: readonly string[];
93
  /** Plugin-specific cache directory */
94
  cacheDir: string;
95
}
96

97
interface CreateNodesResult {
98
  /** Map of project names to their configurations */
99
  projects?: Record<string, ProjectConfiguration>;
100
  /** External node dependencies */
101
  externalNodes?: Record<string, ProjectConfiguration>;
102
}
103
```
104

105
### Plugin Registration
106

107
The Jest plugin is automatically registered when added to nx.json:
108

109
```json
110
{
111
  "plugins": [
112
    "@nx/jest/plugin"
113
  ]
114
}
115
```
116

117
Or with custom options:
118

119
```json
120
{
121
  "plugins": [
122
    {
123
      "plugin": "@nx/jest/plugin",
124
      "options": {
125
        "targetName": "test",
126
        "ciTargetName": "ci-test",
127
        "disableJestRuntime": false
128
      }
129
    }
130
  ]
131
}
132
```
133

134
### Project Detection
135

136
The plugin automatically detects Jest projects by searching for configuration files:
137

138
- `jest.config.js`
139
- `jest.config.ts`
140
- `jest.config.mjs`
141
- `jest.config.cjs`
142
- `jest.config.json`
143

144
**Configuration File Processing:**
145

146
```typescript
147
// The plugin processes Jest configuration files like:
148
export default {
149
  displayName: 'my-lib',
150
  preset: '../../jest.preset.js',
151
  testEnvironment: 'node',
152
  coverageDirectory: '../../coverage/libs/my-lib',
153
  transform: {
154
    '^.+\\.[tj]s$': ['ts-jest', { tsconfig: '<rootDir>/tsconfig.spec.json' }],
155
  },
156
};
157
```
158

159
### Target Generation
160

161
The plugin automatically generates test targets for detected Jest projects:
162

163
```json
164
{
165
  "name": "my-lib",
166
  "targets": {
167
    "test": {
168
      "executor": "@nx/jest:jest",
169
      "outputs": ["{workspaceRoot}/coverage/{projectRoot}"],
170
      "options": {
171
        "jestConfig": "libs/my-lib/jest.config.ts",
172
        "passWithNoTests": true
173
      }
174
    },
175
    "test-ci": {
176
      "executor": "@nx/jest:jest",
177
      "outputs": ["{workspaceRoot}/coverage/{projectRoot}"],
178
      "options": {
179
        "jestConfig": "libs/my-lib/jest.config.ts",
180
        "ci": true,
181
        "codeCoverage": true
182
      }
183
    }
184
  }
185
}
186
```
187

188
### Configuration Inference
189

190
The plugin infers configuration from Jest config files:
191

192
- **Test Environment**: Detects `testEnvironment` setting
193
- **Coverage Settings**: Infers coverage options and output directories
194
- **File Patterns**: Reads `testMatch` and `testPathIgnorePatterns`
195
- **Module Resolution**: Processes `moduleNameMapper` and resolver settings
196
- **Transformation Rules**: Analyzes `transform` configuration
197

198
**Example Inference:**
199

200
```typescript
201
// From jest.config.ts:
202
export default {
203
  testEnvironment: 'jsdom',
204
  coverageDirectory: '../../coverage/apps/my-app',
205
  testMatch: ['<rootDir>/src/**/*.spec.ts'],
206
};
207

208
// Plugin generates:
209
{
210
  "test": {
211
    "executor": "@nx/jest:jest",
212
    "options": {
213
      "jestConfig": "apps/my-app/jest.config.ts"
214
    },
215
    "outputs": ["{workspaceRoot}/coverage/apps/my-app"]
216
  }
217
}
218
```
219

220
### Performance Optimization
221

222
The plugin includes several performance optimizations:
223

224
- **Caching**: Configuration parsing results are cached
225
- **Lazy Loading**: Jest runtime is loaded only when needed
226
- **Batch Processing**: Multiple configuration files processed together
227
- **Hash-based Invalidation**: Cache invalidation based on file content hashes
228

229
**Runtime Optimization:**
230

231
```typescript
232
// When disableJestRuntime is true, the plugin uses faster but simpler config parsing
233
{
234
  "plugin": "@nx/jest/plugin",
235
  "options": {
236
    "disableJestRuntime": true // Faster but potentially less accurate
237
  }
238
}
239
```
240

241
### Multi-Project Configuration
242

243
The plugin handles monorepo setups with multiple Jest projects:
244

245
```typescript
246
// Root jest.config.ts for multi-project setup
247
export default {
248
  projects: [
249
    '<rootDir>/apps/*/jest.config.ts',
250
    '<rootDir>/libs/*/jest.config.ts'
251
  ]
252
};
253
```
254

255
The plugin creates individual targets for each discovered project while maintaining the multi-project relationship.
256

257
### Error Handling
258

259
The plugin includes comprehensive error handling:
260

261
- **Invalid Configuration**: Logs warnings for unparseable Jest configs
262
- **Missing Files**: Handles missing Jest configuration files gracefully
263
- **Circular Dependencies**: Detects and prevents circular project references
264
- **Version Compatibility**: Warns about Jest version compatibility issues
265

266
### Integration with Nx Features
267

268
The plugin integrates with core Nx features:
269

270
- **Affected**: Automatically includes test targets in affected calculations
271
- **Caching**: Enables intelligent caching of test results
272
- **Parallelization**: Supports parallel test execution across projects
273
- **Watch Mode**: Integrates with Nx watch mode for file change detection