0
# File System Utilities
1

2
File system operations including directory creation, recursive deletion, and file copying with cross-platform path handling.
3

4
## Capabilities
5

6
### Make Directory Function
7

8
Creates directories recursively, similar to `mkdir -p`.
9

10
```typescript { .api }
11
/**
12
 * Create directory recursively
13
 * @param dir - Directory path to create
14
 */
15
function mkdirp(dir: string): void;
16
```
17

18
**Usage Examples:**
19

20
```typescript
21
import { mkdirp } from "@sveltejs/package/src/filesystem.js";
22

23
// Create nested directories
24
mkdirp("dist/types/components");
25

26
// Create single directory
27
mkdirp("temp");
28
```
29

30
### Remove Directory Function
31

32
Removes files and directories recursively, similar to `rm -rf`.
33

34
```typescript { .api }
35
/**
36
 * Remove directory or file recursively
37
 * @param path - Path to remove
38
 */
39
function rimraf(path: string): void;
40
```
41

42
**Usage Examples:**
43

44
```typescript
45
import { rimraf } from "@sveltejs/package/src/filesystem.js";
46

47
// Remove directory and all contents
48
rimraf("dist");
49

50
// Remove single file
51
rimraf("temp/file.txt");
52
```
53

54
### Posixify Function
55

56
Converts Windows-style paths to POSIX-style paths for consistent path handling.
57

58
```typescript { .api }
59
/**
60
 * Convert Windows paths to POSIX format
61
 * @param str - Path string to convert
62
 * @returns POSIX-style path
63
 */
64
function posixify(str: string): string;
65
```
66

67
**Usage Examples:**
68

69
```typescript
70
import { posixify } from "@sveltejs/package/src/filesystem.js";
71

72
// Convert Windows path
73
const windowsPath = "src\\lib\\components\\Button.svelte";
74
const posixPath = posixify(windowsPath);
75
// Result: "src/lib/components/Button.svelte"
76

77
// POSIX paths are unchanged
78
const alreadyPosix = "src/lib/index.js";
79
const stillPosix = posixify(alreadyPosix);
80
// Result: "src/lib/index.js"
81
```
82

83
### Walk Directory Function
84

85
Recursively walks a directory and returns all file and directory paths.
86

87
```typescript { .api }
88
/**
89
 * Recursively walk directory and return all paths
90
 * @param cwd - Directory to walk
91
 * @param dirs - Whether to include directories in results (default: false)
92
 * @returns Array of relative paths
93
 */
94
function walk(cwd: string, dirs?: boolean): string[];
95
```
96

97
**Usage Examples:**
98

99
```typescript
100
import { walk } from "@sveltejs/package/src/filesystem.js";
101

102
// Get all files
103
const files = walk("src/lib");
104
// Result: ["index.js", "components/Button.svelte", "utils/helpers.js"]
105

106
// Get files and directories
107
const all = walk("src/lib", true);
108
// Result: ["index.js", "components", "components/Button.svelte", "utils", "utils/helpers.js"]
109
```
110

111
### Copy Files Function
112

113
Copies files or directories from source to target with optional filtering and replacement.
114

115
```typescript { .api }
116
/**
117
 * Copy files or directories
118
 * @param source - Source path
119
 * @param target - Target path
120
 * @param opts - Copy options
121
 * @returns Array of copied file paths
122
 */
123
function copy(source: string, target: string, opts?: CopyOptions): string[];
124

125
interface CopyOptions {
126
  filter?: (basename: string) => boolean;
127
  replace?: Record<string, string>;
128
}
129
```
130

131
**Usage Examples:**
132

133
```typescript
134
import { copy } from "@sveltejs/package/src/filesystem.js";
135

136
// Copy single file
137
const files = copy("src/index.js", "dist/index.js");
138
// Result: ["index.js"]
139

140
// Copy directory
141
const copiedFiles = copy("src/assets", "dist/assets");
142
// Result: ["logo.png", "styles.css", "fonts/main.woff"]
143

144
// Copy with filter (exclude test files)
145
const filtered = copy("src", "dist", {
146
  filter: (basename) => !basename.endsWith('.test.js')
147
});
148

149
// Copy with string replacements
150
const replaced = copy("src/lib", "dist/lib", {
151
  replace: {
152
    'development': 'production',
153
    'localhost': 'example.com'
154
  }
155
});
156
```
157

158
## File System Operations
159

160
### Directory Operations
161

162
The file system utilities handle cross-platform directory operations:
163

164
- **Creation**: `mkdirp` creates parent directories as needed
165
- **Removal**: `rimraf` safely removes directories with all contents
166
- **Walking**: `walk` traverses directory trees with optional directory inclusion
167

168
### File Operations
169

170
- **Copying**: `copy` handles both individual files and directory trees
171
- **Path Normalization**: `posixify` ensures consistent path separators
172
- **Filtering**: Copy operations support custom filter functions
173

174
### Cross-Platform Compatibility
175

176
All utilities handle platform differences:
177

178
- Path separators are normalized to forward slashes
179
- File permissions are preserved where supported
180
- Symbolic links are handled appropriately
181

182
## Error Handling
183

184
The file system utilities handle common error conditions:
185

186
- **Missing Directories**: `mkdirp` creates intermediate directories
187
- **Non-existent Sources**: `copy` and `rimraf` handle missing source paths gracefully
188
- **Permission Errors**: Operations respect file system permissions
189
- **Path Conflicts**: Overwrite behavior is configurable in copy operations
190

191
## Types
192

193
```typescript { .api }
194
interface CopyOptions {
195
  filter?: (basename: string) => boolean;
196
  replace?: Record<string, string>;
197
}
198
```