0
# @nrwl/tao
1

2
@nrwl/tao is a CLI compatibility layer for older Nx workspaces that serves as a bridge between legacy workspace configurations and the newer Nx CLI. It provides backward compatibility for legacy commands and migration support while re-exporting essential Nx APIs for programmatic usage.
3

4
## Package Information
5

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

11
## Core Imports
12

13
ESM imports:
14
```typescript
15
import { logger, Workspaces, Tree } from "@nrwl/tao";
16
```
17

18
CommonJS imports:
19
```javascript
20
const { logger, Workspaces, Tree } = require("@nrwl/tao");
21
```
22

23
Specific module imports:
24
```typescript
25
import { logger } from "@nrwl/tao/shared/logger";
26
import { Workspaces } from "@nrwl/tao/shared/workspace";
27
import { Tree } from "@nrwl/tao/shared/tree";
28
```
29

30
## Basic Usage
31

32
```typescript
33
import { logger, Workspaces, workspaceRoot } from "@nrwl/tao";
34

35
// Basic logging
36
logger.info("Starting workspace operation");
37
logger.warn("This is a warning message");
38

39
// Workspace management
40
const workspaces = new Workspaces(workspaceRoot);
41
const nxConfig = workspaces.readNxJson();
42
const projects = workspaces.readProjectsConfigurations();
43

44
console.log(`Found ${Object.keys(projects.projects).length} projects`);
45
```
46

47
## Architecture
48

49
@nrwl/tao is built as a thin compatibility layer with two primary components:
50

51
- **CLI Binary**: Handles command redirection for backward compatibility (tao migrate → tao _migrate)
52
- **API Re-exports**: Provides access to 8 core Nx functional areas through direct re-exports
53

54
The package acts as a stable interface to essential Nx functionality, ensuring older tooling and scripts continue to work while providing access to modern Nx capabilities.
55

56
## Capabilities
57

58
### Logging Utilities
59

60
Formatted logging system with consistent branding and error handling for CLI applications.
61

62
```typescript { .api }
63
export const logger: {
64
  warn(s: string | any): void;
65
  error(s: string | Error | any): void;
66
  info(s: string | any): void;
67
  log(...s: any[]): void;
68
  debug(...s: any[]): void;
69
  fatal(...s: any[]): void;
70
};
71

72
export const NX_PREFIX: string;
73
export const NX_ERROR: string;
74
export function stripIndent(str: string): string;
75
```
76

77
[Logging](./logging.md)
78

79
### Nx Configuration
80

81
Types and interfaces for nx.json configuration management and workspace setup.
82

83
```typescript { .api }
84
export interface NxJsonConfiguration<T = "*"> {
85
  extends?: string;
86
  implicitDependencies?: ImplicitDependencyEntry<T>;
87
  targetDefaults?: TargetDefaults;
88
  npmScope?: string;
89
  affected?: NxAffectedConfig;
90
  workspaceLayout?: { libsDir: string; appsDir: string };
91
  tasksRunnerOptions?: { [tasksRunnerName: string]: { runner: string; options?: any } };
92
  cli?: { packageManager?: PackageManager; defaultCollection?: string };
93
  plugins?: string[];
94
  defaultProject?: string;
95
}
96

97
export type PackageManager = 'yarn' | 'pnpm' | 'npm';
98
```
99

100
[Configuration](./configuration.md)
101

102
### Package Manager Detection
103

104
Cross-platform package manager utilities for detecting and working with npm, yarn, and pnpm.
105

106
```typescript { .api }
107
export function detectPackageManager(dir?: string): PackageManager;
108
export function getPackageManagerCommand(packageManager?: PackageManager): PackageManagerCommands;
109
export function getPackageManagerVersion(packageManager?: PackageManager): string;
110
```
111

112
[Package Manager](./package-manager.md)
113

114
### Project Graph Analysis
115

116
Types and interfaces for analyzing project dependencies and workspace structure.
117

118
```typescript { .api }
119
export interface ProjectGraph {
120
  nodes: Record<string, ProjectGraphProjectNode>;
121
  externalNodes?: Record<string, ProjectGraphExternalNode>;
122
  dependencies: Record<string, ProjectGraphDependency[]>;
123
  allWorkspaceFiles?: FileData[];
124
  version?: string;
125
}
126

127
export interface ProjectGraphDependency {
128
  type: DependencyType | string;
129
  target: string;
130
  source: string;
131
}
132
```
133

134
[Project Graph](./project-graph.md)
135

136
### Virtual File System
137

138
Tree API for code generation and file system operations with change tracking.
139

140
```typescript { .api }
141
export interface Tree {
142
  root: string;
143
  read(filePath: string): Buffer | null;
144
  read(filePath: string, encoding: BufferEncoding): string | null;
145
  write(filePath: string, content: Buffer | string, options?: TreeWriteOptions): void;
146
  exists(filePath: string): boolean;
147
  delete(filePath: string): void;
148
  rename(from: string, to: string): void;
149
  listChanges(): FileChange[];
150
}
151

152
export function flushChanges(root: string, fileChanges: FileChange[]): void;
153
```
154

155
[Tree API](./tree-api.md)
156

157
### Workspace Management
158

159
Comprehensive workspace discovery, project configuration parsing, and workspace utilities.
160

161
```typescript { .api }
162
export class Workspaces {
163
  constructor(root: string);
164
  readProjectsConfigurations(opts?: { _ignorePluginInference?: boolean }): ProjectsConfigurations;
165
  readNxJson(): NxJsonConfiguration;
166
  hasNxJson(): boolean;
167
  calculateDefaultProjectName(cwd: string, projects: ProjectsConfigurations, nxJson: NxJsonConfiguration): string;
168
}
169

170
export function toProjectName(fileName: string): string;
171
export function globForProjectFiles(root: string, pluginsGlobPatterns: string[], nxJson?: NxJsonConfiguration): string[];
172
```
173

174
[Workspace Management](./workspace-management.md)
175

176
### Angular CLI Adapter
177

178
Bridge functionality for running Angular schematics, migrations, and builders within Nx workspaces.
179

180
```typescript { .api }
181
export function scheduleTarget(
182
  root: string,
183
  opts: { project: string; target: string; configuration: string; runOptions: any },
184
  verbose: boolean
185
): Promise<Observable<BuilderOutput>>;
186

187
export function generate(root: string, opts: GenerateOptions, verbose: boolean): Promise<number>;
188
export function runMigration(root: string, packageName: string, migrationName: string, isVerbose: boolean): Promise<{ loggingQueue: string[]; madeChanges: boolean }>;
189
```
190

191
[Angular CLI Adapter](./angular-cli-adapter.md)
192

193
### Workspace Root Detection
194

195
Utilities for finding and working with workspace root directories.
196

197
```typescript { .api }
198
export const workspaceRoot: string;
199
export function workspaceRootInner(dir: string, candidateRoot: string | null): string;
200
```
201

202
[Workspace Root](./workspace-root.md)