0
# Nx
1

2
Nx is an AI-first build platform designed for monorepo development that provides task orchestration, project graph generation, and CLI tools for managing complex software projects. Originally, @nrwl/tao was a separate CLI package for generating code and running commands, but it has been deprecated and merged into the main nx package as of v19. The nx package now incorporates all the functionality that was previously provided by @nrwl/tao, including code generation, workspace management, task execution, and monorepo orchestration.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { createProjectGraphAsync, readNxJson, logger } from "nx/src/devkit-exports";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { createProjectGraphAsync, readNxJson, logger } = require("nx/src/devkit-exports");
21
```
22

23
CLI Usage:
24

25
```bash
26
# Global installation
27
npm install -g nx
28

29
# Local installation (recommended)
30
npm install --save-dev nx
31
npx nx <command>
32
```
33

34
## Basic Usage
35

36
```typescript
37
import { 
38
  createProjectGraphAsync, 
39
  readNxJson, 
40
  readProjectConfiguration,
41
  logger 
42
} from "nx/src/devkit-exports";
43

44
// Read workspace configuration
45
const nxConfig = readNxJson();
46
console.log('Workspace name:', nxConfig.workspaceLayout);
47

48
// Create project dependency graph
49
const projectGraph = await createProjectGraphAsync();
50
console.log('Projects:', Object.keys(projectGraph.nodes));
51

52
// Read specific project configuration
53
const projectConfig = readProjectConfiguration('my-app');
54
console.log('Project targets:', Object.keys(projectConfig.targets));
55

56
// Use logger for consistent output
57
logger.info('Operation completed successfully');
58
```
59

60
CLI Basic Usage:
61

62
```bash
63
# Create new workspace
64
npx create-nx-workspace@latest my-workspace
65

66
# Generate new project
67
nx generate @nx/react:app my-app
68

69
# Run tasks
70
nx build my-app
71
nx test my-app
72
nx lint my-app
73

74
# Run tasks on multiple projects
75
nx run-many --target=build --all
76
nx affected --target=test
77

78
# View project graph
79
nx graph
80
```
81

82
## Architecture
83

84
Nx is built around several key architectural components:
85

86
- **CLI Interface**: 41 command-line tools for workspace operations and project management
87
- **DevKit API**: Extensive programmatic APIs for project graph manipulation, file operations, and task execution
88
- **Plugin System**: Extensible architecture supporting custom generators, executors, and project graph plugins
89
- **Task Orchestration**: Advanced task runner with dependency-aware execution, caching, and distribution
90
- **Project Graph**: Dependency analysis system that understands project relationships and code changes
91
- **Caching System**: Intelligent caching with local and remote (Nx Cloud) support for build acceleration
92
- **Migration System**: Automated code migration and workspace upgrade tools
93

94
## Capabilities
95

96
### Command Line Interface
97

98
Complete CLI toolkit for monorepo management including project generation, task execution, dependency analysis, workspace maintenance, and cloud integration.
99

100
```typescript { .api }
101
// All CLI commands export command objects for programmatic access
102
export * from './add/command-object';
103
export * from './affected/command-object'; 
104
export * from './generate/command-object';
105
export * from './run/command-object';
106
// ... 20 more CLI commands
107
```
108

109
[Command Line Interface](./cli.md)
110

111
### DevKit API - Core Functions
112

113
Essential APIs for workspace and project management, providing programmatic access to Nx's core functionality.
114

115
```typescript { .api }
116
function createProjectGraphAsync(): Promise<ProjectGraph>;
117
function readNxJson(): NxJsonConfiguration;
118
function readProjectConfiguration(projectName: string): ProjectConfiguration;
119
function updateProjectConfiguration(projectName: string, config: ProjectConfiguration): void;
120
function getProjects(): Map<string, ProjectConfiguration>;
121

122
interface ProjectGraph {
123
  nodes: Record<string, ProjectGraphProjectNode>;
124
  dependencies: Record<string, ProjectGraphDependency[]>;
125
}
126

127
interface NxJsonConfiguration {
128
  workspaceLayout?: WorkspaceLayout;
129
  tasksRunnerOptions?: TasksRunnerOptions;
130
  namedInputs?: NamedInputs;
131
  targetDefaults?: TargetDefaults;
132
}
133
```
134

135
[Core DevKit API](./devkit-core.md)
136

137
### DevKit API - File Operations
138

139
File system utilities and virtual file tree operations for generators and automated code modifications.
140

141
```typescript { .api }
142
function readJsonFile<T = any>(path: string): T;
143
function writeJsonFile<T = any>(path: string, data: T): void;
144
function updateJsonFile<T = any>(path: string, updater: (data: T) => T): void;
145

146
interface Tree {
147
  read(filePath: string): Buffer | null;
148
  write(filePath: string, content: Buffer | string): void;
149
  exists(filePath: string): boolean;
150
  delete(filePath: string): void;
151
  rename(from: string, to: string): void;
152
}
153
```
154

155
[File Operations](./devkit-files.md)
156

157
### DevKit API - Task System
158

159
Task execution, caching, and orchestration APIs for building advanced build tools.
160

161
```typescript { .api }
162
function runExecutor<T = any>(
163
  targetDescription: Target,
164
  overrides: Partial<T>,
165
  context: ExecutorContext
166
): Promise<AsyncIterableIterator<{ success: boolean }>>;
167

168
interface Task {
169
  id: string;
170
  target: Target;
171
  projectRoot: string;
172
  overrides: any;
173
}
174

175
interface TaskGraph {
176
  tasks: Record<string, Task>;
177
  dependencies: Record<string, string[]>;
178
  roots: string[];
179
}
180
```
181

182
[Task System](./devkit-tasks.md)
183

184
### Generators and Executors
185

186
Built-in code generation and task execution tools, plus APIs for creating custom generators and executors.
187

188
```typescript { .api }
189
function formatFiles(tree: Tree): Promise<void>;
190
function generateFiles(tree: Tree, templatePath: string, targetPath: string, substitutions: any): void;
191
function installPackagesTask(tree: Tree): GeneratorCallback;
192

193
interface GeneratorCallback {
194
  (): void | Promise<void>;
195
}
196

197
interface ExecutorContext {
198
  root: string;
199
  cwd: string;
200
  workspace: WorkspaceJsonConfiguration;
201
  isVerbose: boolean;
202
  projectName?: string;
203
  targetName?: string;
204
  configurationName?: string;
205
}
206
```
207

208
[Generators and Executors](./generators-executors.md)
209

210
### Plugin System
211

212
APIs for creating custom plugins that extend Nx's project detection, dependency analysis, and task configuration.
213

214
```typescript { .api }
215
interface NxPlugin {
216
  name: string;
217
  createNodes?: CreateNodes;
218
  createDependencies?: CreateDependencies;
219
  processProjectGraph?: ProcessProjectGraph;
220
}
221

222
type CreateNodes = (configFilePath: string) => CreateNodesResult;
223
type CreateDependencies = (opts: CreateDependenciesContext) => RawProjectGraphDependency[];
224
```
225

226
[Plugin System](./plugins.md)
227

228
## Core Types
229

230
```typescript { .api }
231
interface ProjectConfiguration {
232
  name?: string;
233
  root: string;
234
  sourceRoot?: string;
235
  projectType?: ProjectType;
236
  targets?: { [targetName: string]: TargetConfiguration };
237
  tags?: string[];
238
  implicitDependencies?: string[];
239
}
240

241
interface TargetConfiguration {
242
  executor: string;
243
  outputs?: string[];
244
  options?: any;
245
  configurations?: { [config: string]: any };
246
  defaultConfiguration?: string;
247
  dependsOn?: TargetDependency[];
248
}
249

250
interface Target {
251
  project: string;
252
  target: string;
253
  configuration?: string;
254
}
255

256
type ProjectType = 'application' | 'library';
257
```