0
# Executors
1

2
@nx/js provides high-performance executors for building, running, and managing JavaScript/TypeScript projects with full Nx integration including caching, dependency graph awareness, and incremental builds.
3

4
## Capabilities
5

6
### TypeScript Compiler (tsc)
7

8
Builds TypeScript projects using the TypeScript compiler with support for incremental compilation and batch processing.
9

10
```typescript { .api }
11
/**
12
 * Builds a TypeScript project using the TypeScript compiler
13
 * @param options - TypeScript compilation options
14
 * @param context - Nx executor context
15
 * @returns AsyncGenerator yielding build results with success status
16
 */
17
function tscExecutor(
18
  options: ExecutorOptions,
19
  context: ExecutorContext
20
): AsyncGenerator<{ success: boolean; options?: Record<string, any> }>;
21

22
/**
23
 * Batch executor for building multiple TypeScript projects efficiently
24
 * @param taskGraph - Graph of tasks to execute
25
 * @param inputs - Input options for each task
26
 * @param overrides - Override options for all tasks
27
 * @param context - Nx executor context
28
 * @returns AsyncGenerator yielding batch execution results
29
 */
30
function tscBatchExecutor(
31
  taskGraph: TaskGraph,
32
  inputs: Record<string, ExecutorOptions>,
33
  overrides: ExecutorOptions,
34
  context: ExecutorContext
35
): AsyncGenerator<BatchExecutorTaskResult>;
36

37
interface BatchExecutorTaskResult {
38
  success: boolean;                        // Operation success status
39
  error?: string;                          // Error message if failed
40
  terminalOutput?: string;                 // Terminal output from the task
41
  startTime?: number;                      // Task start timestamp
42
  endTime?: number;                        // Task end timestamp
43
}
44

45
interface TaskGraph {
46
  tasks: Record<string, Task>;             // Task definitions by ID
47
  dependencies: Record<string, string[]>;  // Task dependencies
48
  roots: string[];                         // Root task IDs
49
}
50

51
interface Task {
52
  id: string;                              // Unique task identifier
53
  target: { project: string; target: string; configuration?: string };
54
  projectRoot: string;                     // Project root directory
55
  overrides: Record<string, any>;          // Task option overrides
56
}
57

58
interface ExecutorOptions {
59
  assets: Array<AssetGlob | string>;    // Static assets to copy
60
  main: string;                         // Main entry-point file (required)
61
  rootDir?: string;                     // Root directory for compilation
62
  outputPath: string;                   // Output directory (required)
63
  tsConfig: string;                     // TypeScript configuration file (required)
64
  generateExportsField?: boolean;       // Update package.json exports field
65
  additionalEntryPoints?: string[];     // Additional entry-points for exports
66
  watch: boolean;                       // Enable watch mode
67
  clean?: boolean;                      // Clean output before build
68
  transformers: TransformerEntry[];     // TypeScript transformer plugins
69
  external?: 'all' | 'none' | string[]; // External dependencies (deprecated)
70
  externalBuildTargets?: string[];      // External build target names
71
  generateLockfile?: boolean;           // Generate matching lockfile
72
  generatePackageJson?: boolean;        // Generate package.json in output
73
  includeIgnoredAssetFiles?: boolean;   // Include ignored files in assets
74
}
75
```
76

77
**Usage Example:**
78

79
```typescript
80
// In project.json
81
{
82
  "targets": {
83
    "build": {
84
      "executor": "@nx/js:tsc",
85
      "outputs": ["{options.outputPath}"],
86
      "options": {
87
        "outputPath": "dist/libs/my-lib",
88
        "main": "libs/my-lib/src/index.ts",
89
        "tsConfig": "libs/my-lib/tsconfig.lib.json",
90
        "generatePackageJson": true,
91
        "assets": ["libs/my-lib/*.md"]
92
      }
93
    }
94
  }
95
}
96
```
97

98
### SWC Compiler
99

100
Builds TypeScript/JavaScript projects using SWC for faster compilation with optional type checking.
101

102
```typescript { .api }
103
/**
104
 * Builds a project using SWC for fast compilation
105
 * @param options - SWC compilation options
106
 * @param context - Nx executor context
107
 * @returns AsyncGenerator yielding build results with success status
108
 */
109
function swcExecutor(
110
  options: SwcExecutorOptions,
111
  context: ExecutorContext
112
): AsyncGenerator<{ success: boolean; options?: Record<string, any> }>;
113

114
interface SwcExecutorOptions extends ExecutorOptions {
115
  skipTypeCheck?: boolean;              // Skip TypeScript type checking
116
  swcExclude?: string[];               // SWC glob/regex patterns to exclude (deprecated)
117
}
118
```
119

120
**Usage Example:**
121

122
```typescript
123
// In project.json
124
{
125
  "targets": {
126
    "build": {
127
      "executor": "@nx/js:swc",
128
      "outputs": ["{options.outputPath}"],
129
      "options": {
130
        "outputPath": "dist/libs/my-lib",
131
        "main": "libs/my-lib/src/index.ts",
132
        "tsConfig": "libs/my-lib/tsconfig.lib.json",
133
        "skipTypeCheck": false,
134
        "generatePackageJson": true
135
      }
136
    }
137
  }
138
}
139
```
140

141
### Node Application Runner
142

143
Executes Node.js applications with debugging support, automatic rebuilding, and process management.
144

145
```typescript { .api }
146
/**
147
 * Executes a Node.js application with debugging and watch capabilities
148
 * @param options - Node execution options
149
 * @param context - Nx executor context
150
 * @returns AsyncGenerator yielding execution results
151
 */
152
function nodeExecutor(
153
  options: NodeExecutorOptions,
154
  context: ExecutorContext
155
): AsyncGenerator<{ success: boolean; options?: Record<string, any> }>;
156

157
enum InspectType {
158
  Inspect = 'inspect',
159
  InspectBrk = 'inspect-brk',
160
}
161

162
interface NodeExecutorOptions {
163
  inspect: boolean | InspectType;       // Debug inspection settings (default: 'inspect')
164
  runtimeArgs: string[];                // Extra arguments for node process
165
  args: string[];                       // Extra arguments for the application
166
  waitUntilTargets: string[];           // Targets to complete before starting
167
  buildTarget: string;                  // Build target for the app (required)
168
  buildTargetOptions: Record<string, any>; // Additional build target options
169
  host: string;                         // Debug host (default: 'localhost')
170
  port: number;                         // Debug port (default: 9229)
171
  watch?: boolean;                      // Enable file watching (default: true)
172
  debounce?: number;                    // Restart delay in ms (default: 500)
173
  runBuildTargetDependencies?: boolean; // Run build dependencies first
174
}
175
```
176

177
**Usage Example:**
178

179
```typescript
180
// In project.json
181
{
182
  "targets": {
183
    "serve": {
184
      "executor": "@nx/js:node",
185
      "options": {
186
        "buildTarget": "my-app:build",
187
        "inspect": "inspect",
188
        "port": 9229,
189
        "watch": true,
190
        "debounce": 1000
191
      }
192
    }
193
  }
194
}
195
```
196

197
### Verdaccio Local Registry
198

199
Starts a local npm registry using Verdaccio for local package development and testing.
200

201
```typescript { .api }
202
/**
203
 * Starts a Verdaccio local package registry
204
 * @param options - Verdaccio configuration options
205
 * @param context - Nx executor context
206
 * @returns Promise resolving to success status and port number
207
 */
208
function verdaccioExecutor(
209
  options: VerdaccioExecutorSchema,
210
  context: ExecutorContext
211
): Promise<{ success: boolean; port: number }>;
212

213
interface VerdaccioExecutorSchema {
214
  location: 'global' | 'user' | 'project' | 'none'; // npm config location (default: 'user')
215
  storage?: string;                     // Custom storage directory path
216
  port?: number;                        // Registry port (required)
217
  listenAddress: string;                // Listen address (default: 'localhost')
218
  config?: string;                      // Custom Verdaccio config file
219
  clear?: boolean;                      // Clear storage before start (default: true)
220
  scopes?: string[];                    // Package scopes to configure
221
}
222
```
223

224
**Usage Example:**
225

226
```typescript
227
// In project.json
228
{
229
  "targets": {
230
    "local-registry": {
231
      "executor": "@nx/js:verdaccio",
232
      "options": {
233
        "port": 4873,
234
        "location": "user",
235
        "clear": true,
236
        "scopes": ["@myorg"]
237
      }
238
    }
239
  }
240
}
241
```
242

243
### Package Publisher
244

245
Publishes packages to npm registry with support for different package managers and authentication (internal use only).
246

247
```typescript { .api }
248
/**
249
 * Publishes a package to npm registry
250
 * @param options - Publishing configuration
251
 * @param context - Nx executor context
252
 * @returns Promise resolving to success status
253
 */
254
function runExecutor(
255
  options: PublishExecutorSchema,
256
  context: ExecutorContext
257
): Promise<{ success: boolean }>;
258

259
interface PublishExecutorSchema {
260
  packageRoot?: string;                 // Root directory with package manifest
261
  registry?: string;                    // Target npm registry URL
262
  tag?: string;                         // Distribution tag for published package
263
  otp?: number;                         // One-time password for 2FA
264
  dryRun?: boolean;                     // Run without actually publishing
265
  access?: 'public' | 'restricted';     // Package access level
266
  firstRelease?: boolean;               // Indicates first release
267
}
268
```
269

270
**Note:** This executor is hidden and should not be invoked directly. Use `nx release publish` instead.
271

272
### Copy Workspace Modules
273

274
Copies workspace modules into the output directory for containerization and deployment.
275

276
```typescript { .api }
277
/**
278
 * Copies workspace modules into output directory after build
279
 * @param schema - Copy configuration options
280
 * @param context - Nx executor context
281
 * @returns Promise resolving to success status
282
 */
283
function copyWorkspaceModules(
284
  schema: CopyWorkspaceModulesOptions,
285
  context: ExecutorContext
286
): Promise<{ success: boolean }>;
287

288
interface CopyWorkspaceModulesOptions {
289
  buildTarget: string;                  // Build target that produces output (required)
290
  outputPath?: string;                  // Output path (usually inferred from build target)
291
}
292
```
293

294
**Usage Example:**
295

296
```typescript
297
// In project.json
298
{
299
  "targets": {
300
    "docker-prep": {
301
      "executor": "@nx/js:copy-workspace-modules",
302
      "options": {
303
        "buildTarget": "my-app:build"
304
      }
305
    }
306
  }
307
}
308
```
309

310
### Prune Lockfile
311

312
Creates pruned lockfiles for deployments by including only dependencies needed by the built application.
313

314
```typescript { .api }
315
/**
316
 * Creates a pruned lockfile based on project dependencies
317
 * @param schema - Prune lockfile configuration
318
 * @param context - Nx executor context
319
 * @returns Promise resolving to success status
320
 */
321
function pruneLockfileExecutor(
322
  schema: PruneLockfileOptions,
323
  context: ExecutorContext
324
): Promise<{ success: boolean }>;
325

326
interface PruneLockfileOptions {
327
  buildTarget: string;                  // Build target that produces output (required)
328
  outputPath?: string;                  // Output path (usually inferred from build target)
329
}
330
```
331

332
**Usage Example:**
333

334
```typescript
335
// In project.json
336
{
337
  "targets": {
338
    "docker-lockfile": {
339
      "executor": "@nx/js:prune-lockfile",
340
      "options": {
341
        "buildTarget": "my-app:build"
342
      }
343
    }
344
  }
345
}
346
```
347

348
## Common Types
349

350
```typescript { .api }
351
interface FileInputOutput {
352
  input: string;                        // Source file path
353
  output: string;                       // Destination file path
354
}
355

356
interface AssetGlob extends FileInputOutput {
357
  glob: string;                         // Glob pattern for matching files
358
  ignore?: string[];                    // Patterns to ignore
359
  dot?: boolean;                        // Include dotfiles
360
  includeIgnoredFiles?: boolean;        // Include ignored files
361
}
362

363
interface TransformerPlugin {
364
  name: string;                         // Transformer plugin name
365
  options: Record<string, unknown>;     // Plugin configuration options
366
}
367

368
type TransformerEntry = string | TransformerPlugin;
369

370
interface NormalizedExecutorOptions extends ExecutorOptions {
371
  rootDir: string;                      // Resolved root directory
372
  projectRoot: string;                  // Project root directory
373
  mainOutputPath: string;               // Resolved main output path
374
  generatePackageJson: boolean;         // Whether to generate package.json
375
  files: Array<FileInputOutput>;        // Resolved file mappings
376
  root?: string;                        // Workspace root
377
  sourceRoot?: string;                  // Source root directory
378
}
379
```
380

381
## Executor Patterns
382

383
### Watch Mode Support
384

385
Many executors support watch mode for development:
386

387
```typescript
388
// Watch mode automatically rebuilds when files change
389
{
390
  "executor": "@nx/js:tsc",
391
  "options": {
392
    "watch": true,
393
    // ... other options
394
  }
395
}
396
```
397

398
### Asset Handling
399

400
Executors can copy static assets alongside compiled code:
401

402
```typescript
403
{
404
  "executor": "@nx/js:tsc",
405
  "options": {
406
    "assets": [
407
      "libs/my-lib/*.md",                    // Simple glob
408
      {
409
        "input": "libs/my-lib/assets",       // Source directory
410
        "output": "./assets",                // Destination directory
411
        "glob": "**/*"                       // File pattern
412
      }
413
    ]
414
  }
415
}
416
```
417

418
### Batch Execution
419

420
The TypeScript executor supports batch processing for improved performance:
421

422
```typescript
423
{
424
  "executor": "@nx/js:tsc",
425
  "options": {
426
    // Regular options
427
  },
428
  "batchImplementation": "@nx/js:tsc"      // Enable batch processing
429
}
430
```
431

432
### External Dependencies
433

434
Control which dependencies are bundled vs. treated as external:
435

436
```typescript
437
{
438
  "executor": "@nx/js:tsc",
439
  "options": {
440
    "externalBuildTargets": ["build-deps"], // External build targets
441
    "generatePackageJson": true              // Include dependencies in package.json
442
  }
443
}
444
```