0
# Generators
1

2
@nx/js provides comprehensive project scaffolding generators for creating libraries, initializing workspaces, and setting up various development tools and configurations.
3

4
## Capabilities
5

6
### Library Generator
7

8
Creates new TypeScript or JavaScript libraries with configurable bundlers, test runners, and build configurations.
9

10
```typescript { .api }
11
/**
12
 * Creates a new TypeScript/JavaScript library with comprehensive configuration options
13
 * @param tree - The virtual file system tree
14
 * @param schema - Library generation configuration
15
 * @returns Promise resolving to a GeneratorCallback for additional setup
16
 */
17
function libraryGenerator(
18
  tree: Tree,
19
  schema: LibraryGeneratorSchema
20
): Promise<GeneratorCallback>;
21

22
interface LibraryGeneratorSchema {
23
  directory: string;                    // Required: Library directory path
24
  name?: string;                        // Library name (inferred from directory if not provided)
25
  skipFormat?: boolean;                 // Skip formatting generated files
26
  tags?: string;                        // Comma-separated tags for the library
27
  skipTsConfig?: boolean;               // Skip TypeScript configuration updates
28
  skipPackageJson?: boolean;            // Skip package.json updates
29
  includeBabelRc?: boolean;             // Include .babelrc configuration
30
  unitTestRunner?: 'jest' | 'vitest' | 'none'; // Test runner selection
31
  linter?: Linter | LinterType;         // Linting configuration
32
  testEnvironment?: 'jsdom' | 'node';   // Test environment selection
33
  importPath?: string;                  // Custom import path for the library
34
  js?: boolean;                         // Generate JavaScript instead of TypeScript
35
  pascalCaseFiles?: boolean;            // Use PascalCase for generated file names
36
  strict?: boolean;                     // Enable strict TypeScript compilation
37
  publishable?: boolean;                // Make library publishable to npm
38
  buildable?: boolean;                  // Make library buildable
39
  setParserOptionsProject?: boolean;    // Set parserOptions.project for ESLint
40
  config?: 'workspace' | 'project' | 'npm-scripts'; // Configuration strategy
41
  compiler?: Compiler;                  // Compiler selection: 'tsc' | 'swc'
42
  bundler?: Bundler;                   // Bundler selection
43
  skipTypeCheck?: boolean;              // Skip type checking in build
44
  minimal?: boolean;                    // Generate minimal library structure
45
  rootProject?: boolean;                // Generate as root project
46
  simpleName?: boolean;                 // Use simple naming (deprecated)
47
  addPlugin?: boolean;                  // Add plugin to workspace
48
  useProjectJson?: boolean;             // Use project.json configuration
49
  useTscExecutor?: boolean;             // Use TypeScript executor
50
}
51

52
type Compiler = 'tsc' | 'swc';
53
type Bundler = 'swc' | 'tsc' | 'rollup' | 'vite' | 'esbuild' | 'none';
54
```
55

56
**Usage Example:**
57

58
```typescript
59
import { Tree } from "@nx/devkit";
60
import { libraryGenerator } from "@nx/js";
61

62
// Create a publishable TypeScript library with Jest testing
63
await libraryGenerator(tree, {
64
  directory: 'libs/data-utils',
65
  name: 'data-utils',
66
  bundler: 'rollup',
67
  unitTestRunner: 'jest',
68
  linter: 'eslint',
69
  publishable: true,
70
  buildable: true,
71
  importPath: '@myorg/data-utils'
72
});
73
```
74

75
### Convert to SWC Generator
76

77
Converts existing TypeScript projects from TSC to SWC compilation for faster builds.
78

79
```typescript { .api }
80
/**
81
 * Converts a TypeScript project to use SWC instead of TSC for compilation
82
 * @param tree - The virtual file system tree
83
 * @param schema - Conversion configuration
84
 * @returns Promise resolving to a GeneratorCallback for dependency updates
85
 */
86
function convertToSwcGenerator(
87
  tree: Tree,
88
  schema: ConvertToSwcGeneratorSchema
89
): Promise<GeneratorCallback>;
90

91
interface ConvertToSwcGeneratorSchema {
92
  project: string;                      // Required: Project name to convert
93
  targets?: string[];                   // Build targets to convert (default: ['build'])
94
}
95
```
96

97
**Usage Example:**
98

99
```typescript
100
import { Tree } from "@nx/devkit";
101
import { convertToSwcGenerator } from "@nx/js";
102

103
// Convert a library to use SWC compilation
104
await convertToSwcGenerator(tree, {
105
  project: 'my-lib',
106
  targets: ['build', 'test']
107
});
108
```
109

110
### Setup Prettier Generator
111

112
Configures Prettier as the workspace code formatter with default configuration.
113

114
```typescript { .api }
115
/**
116
 * Sets up Prettier code formatting for the workspace
117
 * @param tree - The virtual file system tree
118
 * @param options - Prettier setup configuration
119
 * @returns Promise resolving to a GeneratorCallback for dependency installation
120
 */
121
function setupPrettierGenerator(
122
  tree: Tree,
123
  options: GeneratorOptions
124
): Promise<GeneratorCallback>;
125

126
interface GeneratorOptions {
127
  skipFormat?: boolean;                 // Skip formatting generated files
128
  skipPackageJson?: boolean;            // Skip package.json updates
129
}
130
```
131

132
**Usage Example:**
133

134
```typescript
135
import { Tree } from "@nx/devkit";
136
import { setupPrettierGenerator } from "@nx/js";
137

138
// Set up Prettier with default configuration
139
await setupPrettierGenerator(tree, {
140
  skipFormat: false,
141
  skipPackageJson: false
142
});
143
```
144

145
### Setup Verdaccio Generator
146

147
Configures Verdaccio local package registry for local development and testing.
148

149
```typescript { .api }
150
/**
151
 * Sets up Verdaccio local package registry for the workspace
152
 * @param tree - The virtual file system tree
153
 * @param options - Verdaccio setup configuration
154
 * @returns Promise resolving to a GeneratorCallback for dependency installation
155
 */
156
function setupVerdaccio(
157
  tree: Tree,
158
  options: SetupVerdaccioGeneratorSchema
159
): Promise<GeneratorCallback>;
160

161
interface SetupVerdaccioGeneratorSchema {
162
  skipFormat: boolean;                  // Skip formatting generated files
163
}
164
```
165

166
**Usage Example:**
167

168
```typescript
169
import { Tree } from "@nx/devkit";
170
import { setupVerdaccio } from "@nx/js";
171

172
// Set up local Verdaccio registry
173
await setupVerdaccio(tree, {
174
  skipFormat: false
175
});
176
```
177

178
### Release Version Generator
179

180
Handles version bumping for releases with workspace dependency updates (internal use only).
181

182
```typescript { .api }
183
/**
184
 * Updates version information for releases across workspace dependencies
185
 * @param tree - The virtual file system tree
186
 * @param options - Version release configuration
187
 * @returns Promise resolving to a GeneratorCallback for additional setup
188
 */
189
function releaseVersionGenerator(
190
  tree: Tree,
191
  options: ReleaseVersionGeneratorSchema
192
): Promise<GeneratorCallback>;
193

194
interface ReleaseVersionGeneratorSchema {
195
  // Internal schema - specific options not publicly documented
196
  [key: string]: any;
197
}
198
```
199

200
**Note:** This generator is hidden and should not be invoked directly. Use `nx release version` instead.
201

202
### TypeScript Sync Generator
203

204
Synchronizes TypeScript project references based on the project graph to ensure consistent dependencies.
205

206
```typescript { .api }
207
/**
208
 * Synchronizes TypeScript project references based on project dependencies
209
 * @param tree - The virtual file system tree
210
 * @returns Promise resolving to sync results with out-of-sync details
211
 */
212
function typescriptSyncGenerator(tree: Tree): Promise<SyncGeneratorResult>;
213

214
interface SyncGeneratorResult {
215
  outOfSyncMessage?: string;           // Description of sync issues found
216
  outOfSyncDetails?: string[];         // Detailed list of files that were out of sync
217
}
218
```
219

220
**Usage Example:**
221

222
```typescript
223
import { Tree } from "@nx/devkit";
224
import { typescriptSyncGenerator } from "@nx/js";
225

226
// Sync TypeScript project references
227
const result = await typescriptSyncGenerator(tree);
228
if (result.outOfSyncMessage) {
229
  console.log('TypeScript references were updated:', result.outOfSyncMessage);
230
}
231
```
232

233
### Setup Build Generator
234

235
Adds build configuration to existing projects with support for multiple bundlers.
236

237
```typescript { .api }
238
/**
239
 * Adds build configuration to an existing project
240
 * @param tree - The virtual file system tree
241
 * @param options - Build setup configuration
242
 * @returns Promise resolving to a GeneratorCallback for any additional setup
243
 */
244
function setupBuildGenerator(
245
  tree: Tree,
246
  options: SetupBuildGeneratorSchema
247
): Promise<GeneratorCallback>;
248

249
interface SetupBuildGeneratorSchema {
250
  project: string;                                              // Required: Project name
251
  bundler: 'tsc' | 'swc' | 'vite' | 'rollup' | 'esbuild';     // Required: Bundler selection
252
  main?: string;                                                // Main entry file
253
  tsConfig?: string;                                            // TypeScript configuration file
254
  buildTarget?: string;                                         // Build target name
255
}
256
```
257

258
**Usage Example:**
259

260
```typescript
261
import { Tree } from "@nx/devkit";
262
import { setupBuildGenerator } from "@nx/js";
263

264
// Add Rollup build configuration to a project
265
await setupBuildGenerator(tree, {
266
  project: 'my-existing-lib',
267
  bundler: 'rollup',
268
  main: 'src/index.ts',
269
  buildTarget: 'build'
270
});
271
```
272

273
## Common Patterns
274

275
### Generator Callbacks
276

277
All generators return `GeneratorCallback` functions that handle additional setup like dependency installation:
278

279
```typescript
280
const callback = await libraryGenerator(tree, options);
281
// Execute callback to install dependencies and perform additional setup
282
await callback();
283
```
284

285
### Tree Modifications
286

287
Generators use the Nx Tree API to modify the file system:
288

289
```typescript
290
import { Tree, writeJson, generateFiles } from "@nx/devkit";
291

292
// Generators receive a Tree instance for file operations
293
function myGenerator(tree: Tree, options: MyOptions) {
294
  // Add files
295
  generateFiles(tree, joinPathFragments(__dirname, 'files'), '.', options);
296
  
297
  // Modify package.json
298
  const packageJson = readJson(tree, 'package.json');
299
  packageJson.scripts.build = 'nx build';
300
  writeJson(tree, 'package.json', packageJson);
301
  
302
  return () => {
303
    // Return callback for post-generation tasks
304
  };
305
}
306
```
307

308
### Schema Validation
309

310
All generators use JSON Schema validation for their options. Schema files are located alongside each generator's implementation.