0
# File System Utilities
1

2
Safe file and directory operations with error handling and workspace-aware functionality. These utilities provide reliable file system operations for generators and other workspace tools.
3

4
## Capabilities
5

6
### JSON File Operations
7

8
Update JSON files safely with error handling and proper formatting.
9

10
```typescript { .api }
11
/**
12
 * Update a JSON file using the filesystem with a callback function
13
 * @param path - Path of the JSON file on the filesystem
14
 * @param callback - Function to manipulate the JSON data
15
 */
16
function updateJsonFile(path: string, callback: (json: any) => any): void;
17
```
18

19
**Usage Example:**
20

21
```typescript
22
import { updateJsonFile } from "@nx/workspace";
23

24
// Update package.json
25
updateJsonFile("./package.json", (json) => {
26
  json.scripts = json.scripts || {};
27
  json.scripts.build = "nx build";
28
  json.scripts.test = "nx test";
29
  return json;
30
});
31

32
// Update project configuration
33
updateJsonFile("./project.json", (json) => {
34
  json.targets = json.targets || {};
35
  json.targets.lint = {
36
    executor: "@nx/linter:eslint",
37
    options: {
38
      lintFilePatterns: ["src/**/*.ts"]
39
    }
40
  };
41
  return json;
42
});
43
```
44

45
### File Copy Operations
46

47
Copy files from source to target directory with stream-based operations.
48

49
```typescript { .api }
50
/**
51
 * Copy a file from source to target directory
52
 * @param file - Source file path
53
 * @param target - Target directory path
54
 */
55
function copyFile(file: string, target: string): void;
56
```
57

58
**Usage Example:**
59

60
```typescript
61
import { copyFile } from "@nx/workspace";
62

63
// Copy configuration file to new location
64
copyFile("./src/config/default.json", "./dist/config/");
65

66
// Copy template files
67
copyFile("./templates/component.ts", "./src/components/");
68
```
69

70
### Safe File Rename Operations
71

72
Rename files and directories with comprehensive error handling and validation.
73

74
```typescript { .api }
75
/**
76
 * Safely rename files/directories with callback error handling
77
 * @param from - Source path
78
 * @param to - Destination path  
79
 * @param cb - Callback function receiving error or null on success
80
 */
81
function renameSync(
82
  from: string, 
83
  to: string, 
84
  cb: (err: Error | null) => void
85
): void;
86
```
87

88
**Usage Example:**
89

90
```typescript
91
import { renameSync } from "@nx/workspace";
92

93
// Rename a project directory
94
renameSync(
95
  "./libs/old-name", 
96
  "./libs/new-name", 
97
  (err) => {
98
    if (err) {
99
      console.error("Failed to rename:", err.message);
100
    } else {
101
      console.log("Successfully renamed project");
102
    }
103
  }
104
);
105

106
// Rename configuration file
107
renameSync(
108
  "./workspace.json",
109
  "./workspace.json.backup", 
110
  (err) => {
111
    if (err) {
112
      console.error("Backup failed:", err.message);
113
    }
114
  }
115
);
116
```
117

118
### Directory Creation
119

120
Create directories with proper error handling (re-exported from Nx core utilities).
121

122
```typescript { .api }
123
/**
124
 * Create directory recursively if it doesn't exist
125
 * @param path - Directory path to create
126
 */
127
function createDirectory(path: string): void;
128
```
129

130
**Usage Example:**
131

132
```typescript
133
import { createDirectory } from "@nx/workspace";
134

135
// Create nested directory structure
136
createDirectory("./libs/shared/components/ui");
137

138
// Create build output directory
139
createDirectory("./dist/apps/my-app");
140
```
141

142
### File System Checks
143

144
Utility functions for checking file and directory existence (re-exported from Nx core).
145

146
```typescript { .api }
147
/**
148
 * Check if a file exists
149
 * @param path - File path to check
150
 * @returns True if file exists, false otherwise
151
 */
152
function fileExists(path: string): boolean;
153

154
/**
155
 * Check if a directory exists
156
 * @param path - Directory path to check
157
 * @returns True if directory exists, false otherwise
158
 */
159
function directoryExists(path: string): boolean;
160

161
/**
162
 * Check if a path is relative
163
 * @param path - Path to check
164
 * @returns True if path is relative, false if absolute
165
 */
166
function isRelativePath(path: string): boolean;
167
```
168

169
**Usage Examples:**
170

171
```typescript
172
import { fileExists, directoryExists, isRelativePath } from "@nx/workspace";
173

174
// Check before performing operations
175
if (fileExists("./package.json")) {
176
  console.log("Package.json found");
177
}
178

179
if (directoryExists("./libs/shared")) {
180
  console.log("Shared library directory exists");
181
}
182

183
// Validate path format
184
if (isRelativePath("./src/app")) {
185
  console.log("Using relative path");
186
}
187
```
188

189
## Error Handling
190

191
All file utilities include proper error handling:
192

193
- **updateJsonFile**: Throws errors for invalid JSON or file access issues
194
- **copyFile**: Emits error events on stream failures  
195
- **renameSync**: Validates source/target paths and creates parent directories
196
- **createDirectory**: Handles permission errors and existing directories gracefully
197

198
## Safety Features
199

200
- **Path validation**: Checks for source file existence before operations
201
- **Parent directory creation**: Automatically creates parent directories when needed
202
- **Conflict prevention**: Prevents overwriting existing files in rename operations
203
- **Stream error handling**: Proper cleanup on file copy failures
204

205
## Types
206

207
```typescript { .api }
208
type FileCallback = (err: Error | null) => void;
209
```