0
# @nx/js
1

2
The @nx/js plugin provides comprehensive tooling for developing JavaScript and TypeScript projects within Nx workspaces. It includes executors for building, running, and publishing JavaScript/TypeScript code, generators for scaffolding projects and configurations, and utilities for TypeScript compilation, package.json management, and asset handling.
3

4
## Package Information
5

6
- **Package Name**: @nx/js
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @nx/js`
10

11
## Core Imports
12

13
```typescript
14
import {
15
  // Generators
16
  libraryGenerator,
17
  initGenerator,
18
  setupPrettierGenerator,
19
  setupVerdaccio,
20
  // Package JSON utilities
21
  createPackageJson,
22
  updatePackageJson,
23
  createEntryPoints,
24
  // TypeScript utilities
25
  runTypeCheck,
26
  readTsConfig,
27
  createTsConfig,
28
  loadTsTransformers,
29
  printDiagnostics,
30
  getSourceNodes,
31
  // Asset handling
32
  copyAssets,
33
  assetGlobsToFiles,
34
  // Lock file utilities
35
  createLockFile,
36
  getLockFileName,
37
  // Other utilities
38
  addTslibDependencies,
39
  isValidVariable
40
} from "@nx/js";
41
```
42

43
For CommonJS:
44

45
```javascript
46
const {
47
  libraryGenerator,
48
  initGenerator,
49
  setupPrettierGenerator,
50
  setupVerdaccio,
51
  createPackageJson,
52
  updatePackageJson,
53
  runTypeCheck,
54
  readTsConfig,
55
  copyAssets,
56
  createLockFile,
57
  getLockFileName
58
} = require("@nx/js");
59
```
60

61
## Basic Usage
62

63
```typescript
64
import { Tree } from "@nx/devkit";
65
import { libraryGenerator, updatePackageJson } from "@nx/js";
66

67
// Generate a new TypeScript library
68
await libraryGenerator(tree, {
69
  directory: 'libs/my-lib',
70
  name: 'my-lib',
71
  bundler: 'tsc',
72
  unitTestRunner: 'jest',
73
  linter: 'eslint'
74
});
75

76
// Update package.json for build output
77
updatePackageJson({
78
  outputPath: 'dist/libs/my-lib',
79
  main: './src/index.js',
80
  generatePackageJson: true
81
}, context, target, dependencies);
82
```
83

84
## Architecture
85

86
The @nx/js plugin is built around several key components:
87

88
- **Generators**: Project scaffolding tools for libraries, configurations, and setup
89
- **Executors**: Build and runtime tools for TypeScript/SWC compilation, Node.js execution, and publishing
90
- **TypeScript Utilities**: Comprehensive TypeScript compilation, type checking, and AST manipulation tools
91
- **Package Management**: Package.json creation, updating, and dependency management utilities
92
- **Asset Handling**: Static asset copying and processing capabilities
93
- **Build System Integration**: Deep integration with Nx's caching, dependency graph, and task execution
94

95
## Capabilities
96

97
### Project Generation
98

99
Comprehensive project scaffolding with support for multiple bundlers, test runners, and configurations. Includes workspace initialization and library creation.
100

101
```typescript { .api }
102
function libraryGenerator(
103
  tree: Tree,
104
  schema: LibraryGeneratorSchema
105
): Promise<GeneratorCallback>;
106

107
function initGenerator(
108
  tree: Tree,
109
  schema: InitSchema
110
): Promise<GeneratorCallback>;
111
```
112

113
[Generators](./generators.md)
114

115
### Build Execution  
116

117
High-performance executors for TypeScript compilation, SWC building, Node.js application running, and package publishing with full Nx integration.
118

119
```typescript { .api }
120
function tscExecutor(
121
  options: ExecutorOptions,
122
  context: ExecutorContext
123
): AsyncGenerator<{ success: boolean; options?: Record<string, any> }>;
124

125
function swcExecutor(
126
  options: SwcExecutorOptions,
127
  context: ExecutorContext
128
): AsyncGenerator<{ success: boolean; options?: Record<string, any> }>;
129
```
130

131
[Executors](./executors.md)
132

133
### TypeScript Compilation
134

135
Complete TypeScript toolchain including compilation, type checking, configuration management, and AST manipulation utilities.
136

137
```typescript { .api }
138
function runTypeCheck(options: TypeCheckOptions): Promise<TypeCheckResult>;
139

140
function readTsConfig(tsConfigPath: string, sys?: ts.System): ts.ParsedCommandLine;
141

142
function loadTsTransformers(
143
  plugins: TransformerEntry[],
144
  moduleResolver?: typeof require.resolve
145
): { compilerPluginHooks: CompilerPluginHooks; hasPlugin: boolean; };
146
```
147

148
[TypeScript Utilities](./typescript-utilities.md)
149

150
### Package Management
151

152
Package.json creation, updating, and dependency management with support for exports fields, entry points, and build artifact integration.
153

154
```typescript { .api }
155
function updatePackageJson(
156
  options: UpdatePackageJsonOption,
157
  context: ExecutorContext,
158
  target: ProjectGraphProjectNode,
159
  dependencies: DependentBuildableProjectNode[],
160
  fileMap?: ProjectFileMap
161
): void;
162

163
function createPackageJson(
164
  projectName: string,
165
  graph: ProjectGraph,
166
  options: CreatePackageJsonOptions
167
): PackageJson;
168
```
169

170
[Package Management](./package-management.md)
171

172
### Asset Handling
173

174
Static asset copying and processing with glob pattern support, output path management, and watch mode capabilities.
175

176
```typescript { .api }
177
function copyAssets(
178
  options: CopyAssetsOptions,
179
  context: ExecutorContext
180
): Promise<CopyAssetsResult>;
181

182
function assetGlobsToFiles(
183
  assets: Array<AssetGlob | string>,
184
  rootDir: string,
185
  outDir: string
186
): FileInputOutput[];
187
```
188

189
[Asset Management](./asset-management.md)
190

191
### Additional Utilities
192

193
Lock file management, local registry scripts, dependency handling, and other development utilities.
194

195
```typescript { .api }
196
function copyPackageJson(
197
  options: CopyPackageJsonOptions,
198
  context: ExecutorContext
199
): Promise<CopyPackageJsonResult>;
200

201
function createLockFile(
202
  packageManager: 'npm' | 'yarn' | 'pnpm',
203
  workspaceRoot: string,
204
  projectRoot: string,
205
  packageJson: any
206
): Promise<void>;
207

208
function addLocalRegistryScripts(
209
  tree: Tree,
210
  options: LocalRegistryOptions
211
): void;
212

213
function isValidVariable(name: string): boolean;
214
```
215

216
[Additional Utilities](./additional-utilities.md)
217

218
## Types
219

220
```typescript { .api }
221
interface LibraryGeneratorSchema {
222
  directory: string;
223
  name?: string;
224
  skipFormat?: boolean;
225
  tags?: string;
226
  skipTsConfig?: boolean;
227
  skipPackageJson?: boolean;
228
  includeBabelRc?: boolean;
229
  unitTestRunner?: 'jest' | 'vitest' | 'none';
230
  linter?: Linter | LinterType;
231
  testEnvironment?: 'jsdom' | 'node';
232
  importPath?: string;
233
  js?: boolean;
234
  pascalCaseFiles?: boolean;
235
  strict?: boolean;
236
  publishable?: boolean;
237
  buildable?: boolean;
238
  setParserOptionsProject?: boolean;
239
  config?: 'workspace' | 'project' | 'npm-scripts';
240
  compiler?: Compiler;
241
  bundler?: Bundler;
242
  skipTypeCheck?: boolean;
243
  minimal?: boolean;
244
  rootProject?: boolean;
245
  simpleName?: boolean;
246
  addPlugin?: boolean;
247
  useProjectJson?: boolean;
248
  useTscExecutor?: boolean;
249
}
250

251
interface ExecutorOptions {
252
  assets: Array<AssetGlob | string>;
253
  main: string;
254
  rootDir?: string;
255
  outputPath: string;
256
  tsConfig: string;
257
  generateExportsField?: boolean;
258
  additionalEntryPoints?: string[];
259
  watch: boolean;
260
  clean?: boolean;
261
  transformers: TransformerEntry[];
262
  external?: 'all' | 'none' | string[];
263
  externalBuildTargets?: string[];
264
  generateLockfile?: boolean;
265
  generatePackageJson?: boolean;
266
  includeIgnoredAssetFiles?: boolean;
267
}
268

269
interface TypeCheckOptions {
270
  mode?: 'noEmit' | 'emitDeclarationOnly';
271
  tsConfigPath: string;
272
  workspaceRoot: string;
273
  incremental?: boolean;
274
  cacheDir?: string;
275
}
276

277
interface TypeCheckResult {
278
  warnings: string[];
279
  errors: string[];
280
  inputFilesCount: number;
281
  totalFilesCount: number;
282
  incremental: boolean;
283
}
284

285
type Compiler = 'tsc' | 'swc';
286
type Bundler = 'swc' | 'tsc' | 'rollup' | 'vite' | 'esbuild' | 'none';
287
type SupportedFormat = 'cjs' | 'esm';
288

289
interface FileInputOutput {
290
  input: string;
291
  output: string;
292
}
293

294
interface AssetGlob extends FileInputOutput {
295
  glob: string;
296
  ignore?: string[];
297
  dot?: boolean;
298
  includeIgnoredFiles?: boolean;
299
}
300
```