0
# Project Configuration
1

2
Generators for initializing Jest in Nx workspaces and adding Jest configuration to individual projects. These generators handle dependency installation, configuration file creation, and workspace integration.
3

4
## Capabilities
5

6
### Configuration Generator
7

8
Adds Jest configuration to an existing project with comprehensive setup options.
9

10
```typescript { .api }
11
/**
12
 * Add Jest configuration to a project
13
 * @param tree - Nx virtual file system tree
14
 * @param options - Jest project configuration options
15
 * @returns Promise resolving to generator callback for post-execution tasks
16
 */
17
function configurationGenerator(
18
  tree: Tree, 
19
  options: JestProjectSchema
20
): Promise<GeneratorCallback>;
21

22
/**
23
 * @deprecated Use configurationGenerator instead. Will be removed in Nx v22.
24
 */
25
const jestProjectGenerator = configurationGenerator;
26
```
27

28
### Jest Project Schema
29

30
Configuration options for setting up Jest in a project.
31

32
```typescript { .api }
33
interface JestProjectSchema {
34
  /** Target project name */
35
  project: string;
36
  /** Name of the test target (default: 'test') */
37
  targetName?: string;
38
  /** Enable TSX support for React projects */
39
  supportTsx?: boolean;
40
  /** Setup file configuration for specific frameworks */
41
  setupFile?: 'angular' | 'web-components' | 'none';
42
  /** Skip adding Jest serializers */
43
  skipSerializers?: boolean;
44
  /** Test environment configuration */
45
  testEnvironment?: 'node' | 'jsdom' | 'none';
46
  /** Skip formatting generated files */
47
  skipFormat?: boolean;
48
  /** Add Jest plugin to nx.json */
49
  addPlugin?: boolean;
50
  /** TypeScript compiler to use */
51
  compiler?: 'tsc' | 'babel' | 'swc';
52
  /** Skip updating package.json */
53
  skipPackageJson?: boolean;
54
  /** Generate JavaScript configuration instead of TypeScript */
55
  js?: boolean;
56
  /** Name of runtime tsconfig file */
57
  runtimeTsconfigFileName?: string;
58
  /** Internal flag for explicit target configuration */
59
  addExplicitTargets?: boolean;
60
  /** Keep existing dependency versions */
61
  keepExistingVersions?: boolean;
62
  /** @deprecated Use compiler option instead */
63
  babelJest?: boolean;
64
  /** @deprecated Use setupFile option instead */
65
  skipSetupFile?: boolean;
66
}
67

68
type NormalizedJestProjectSchema = JestProjectSchema & {
69
  rootProject: boolean;
70
  isTsSolutionSetup: boolean;
71
};
72
```
73

74
**Usage Examples:**
75

76
```typescript
77
import { configurationGenerator } from "@nx/jest";
78
import { Tree } from '@nx/devkit';
79

80
// Basic Jest setup for a library
81
await configurationGenerator(tree, {
82
  project: "my-lib",
83
  testEnvironment: "node"
84
});
85

86
// React component testing setup
87
await configurationGenerator(tree, {
88
  project: "my-react-app",
89
  testEnvironment: "jsdom",
90
  supportTsx: true,
91
  setupFile: "none",
92
  compiler: "swc"
93
});
94

95
// Angular project setup
96
await configurationGenerator(tree, {
97
  project: "my-angular-app",
98
  testEnvironment: "jsdom",
99
  setupFile: "angular",
100
  supportTsx: false
101
});
102
```
103

104
### Init Generator
105

106
Initializes Jest workspace-wide configuration and dependencies.
107

108
```typescript { .api }
109
/**
110
 * Initialize the @nx/jest plugin in the workspace
111
 * @param tree - Nx virtual file system tree
112
 * @param options - Jest initialization options
113
 * @returns Promise resolving to generator callback
114
 */
115
function jestInitGenerator(
116
  tree: Tree, 
117
  options: JestInitSchema
118
): Promise<GeneratorCallback>;
119

120
/**
121
 * Internal implementation of jest init generator
122
 */
123
function jestInitGeneratorInternal(
124
  tree: Tree, 
125
  options: JestInitSchema
126
): Promise<GeneratorCallback>;
127
```
128

129
### Jest Init Schema
130

131
Options for workspace-level Jest initialization.
132

133
```typescript { .api }
134
interface JestInitSchema {
135
  /** Skip formatting generated files */
136
  skipFormat?: boolean;
137
  /** Skip updating package.json */
138
  skipPackageJson?: boolean;
139
  /** Keep existing dependency versions */
140
  keepExistingVersions?: boolean;
141
  /** Update package.json scripts */
142
  updatePackageScripts?: boolean;
143
  /** Add Jest plugin to nx.json */
144
  addPlugin?: boolean;
145
}
146
```
147

148
**Usage Examples:**
149

150
```typescript
151
import { jestInitGenerator } from "@nx/jest";
152

153
// Initialize Jest with plugin support
154
await jestInitGenerator(tree, {
155
  addPlugin: true,
156
  updatePackageScripts: true
157
});
158

159
// Initialize Jest without modifying package.json
160
await jestInitGenerator(tree, {
161
  skipPackageJson: true,
162
  skipFormat: false
163
});
164
```
165

166
### Convert to Inferred Generator
167

168
Migrates existing Jest projects to use the Nx plugin inference system.
169

170
```typescript { .api }
171
/**
172
 * Convert existing Jest project(s) using @nx/jest:jest executor to use @nx/jest/plugin
173
 * @param tree - Nx virtual file system tree
174
 * @param options - Conversion options
175
 * @returns Promise resolving to generator callback
176
 */
177
function convertToInferredGenerator(
178
  tree: Tree,
179
  options: ConvertToInferredSchema
180
): Promise<GeneratorCallback>;
181

182
interface ConvertToInferredSchema {
183
  /** Specific project to convert (optional) */
184
  project?: string;
185
  /** Skip formatting generated files */
186
  skipFormat?: boolean;
187
}
188
```
189

190
**Usage Examples:**
191

192
```typescript
193
import { convertToInferredGenerator } from "@nx/jest";
194

195
// Convert all Jest projects to use plugin inference
196
await convertToInferredGenerator(tree, {});
197

198
// Convert specific project
199
await convertToInferredGenerator(tree, {
200
  project: "my-app"
201
});
202
```
203

204
### Generator Workflow
205

206
The generators follow this typical workflow:
207

208
1. **Dependency Management**: Install required Jest packages and type definitions
209
2. **Configuration Creation**: Generate Jest configuration files (jest.config.ts)
210
3. **TypeScript Setup**: Create or update tsconfig.spec.json for test files
211
4. **Framework Integration**: Add framework-specific setup files if needed
212
5. **Workspace Integration**: Update nx.json and project.json as needed
213
6. **Plugin Configuration**: Add Jest plugin to nx.json if requested
214

215
### Configuration Files Generated
216

217
The generators create several configuration files:
218

219
```typescript
220
// jest.config.ts (example output)
221
export default {
222
  displayName: 'my-project',
223
  preset: '../../jest.preset.js',
224
  testEnvironment: 'jsdom',
225
  transform: {
226
    '^.+\\.[tj]s$': ['ts-jest', { tsconfig: '<rootDir>/tsconfig.spec.json' }],
227
  },
228
  moduleFileExtensions: ['ts', 'js', 'html'],
229
  coverageDirectory: '../../coverage/apps/my-project',
230
};
231

232
// tsconfig.spec.json (example output)
233
{
234
  "extends": "./tsconfig.json",
235
  "compilerOptions": {
236
    "outDir": "../../dist/out-tsc",
237
    "module": "commonjs",
238
    "types": ["jest", "node"]
239
  },
240
  "include": [
241
    "jest.config.ts",
242
    "src/**/*.test.ts",
243
    "src/**/*.spec.ts",
244
    "src/**/*.d.ts"
245
  ]
246
}
247
```
248

249
### Setup Files
250

251
Framework-specific setup files are created based on the `setupFile` option:
252

253
- **angular**: DOM testing utilities and Angular testing setup
254
- **web-components**: Custom elements and Web Components testing setup  
255
- **none**: No additional setup files