0
# File Writing (dest)
1

2
Stream-based file writing functionality that accepts Vinyl File objects and writes them to the filesystem. Automatically creates directories, handles file permissions, and supports sourcemap output.
3

4
## Capabilities
5

6
### dest Function
7

8
Creates a writable stream that saves Vinyl File objects to the filesystem with comprehensive options for file writing behavior.
9

10
```javascript { .api }
11
/**
12
 * Creates a writable stream that saves Vinyl File objects to filesystem
13
 * @param {string|function} outFolder - Destination folder path or function returning path
14
 * @param {Object} [options] - Configuration options
15
 * @returns {Transform} Transform stream that consumes Vinyl File objects
16
 * @throws {Error} When outFolder argument is invalid
17
 */
18
function dest(outFolder, options);
19

20
interface DestOptions {
21
  /** Working directory for relative paths (default: process.cwd()) */
22
  cwd?: string;
23
  /** File permissions mode (default: file.stat.mode) */
24
  mode?: number | ((file: File) => number);
25
  /** Directory permissions mode */
26
  dirMode?: number | ((file: File) => number);
27
  /** Overwrite existing files (default: true) */
28
  overwrite?: boolean;
29
  /** Append to existing files (default: false) */
30
  append?: boolean;
31
  /** Output encoding (default: 'utf8') */
32
  encoding?: string | boolean;
33
  /** Sourcemap handling (default: false) */
34
  sourcemaps?: boolean | string;
35
  /** Create relative symlinks (default: false) */
36
  relativeSymlinks?: boolean;
37
  /** Use junctions on Windows (default: true) */
38
  useJunctions?: boolean;
39
}
40
```
41

42
### Folder Path Resolution
43

44
The outFolder parameter can be a string or function:
45

46
```javascript
47
// Static folder path
48
vfs.dest('./output');
49

50
// Dynamic folder based on file properties
51
vfs.dest((file) => {
52
  return file.extname === '.css' ? './css' : './js';
53
});
54
```
55

56
### File Modification Behavior
57

58
After writing files, vinyl-fs attempts to preserve file metadata:
59

60
- **Timestamps**: Sets `mtime` and `atime` if they differ from filesystem
61
- **Permissions**: Updates file mode if different and process owns the file
62
- **Ownership**: Only on Unix-like systems with proper permissions
63

64
**Note**: Metadata updates are disabled on Windows due to platform limitations.
65

66
### Option Details
67

68
#### mode
69
Controls file permissions for written files.
70

71
```javascript
72
// Use original file permissions (default)
73
vfs.dest('./output', { mode: undefined });
74

75
// Set specific permissions
76
vfs.dest('./output', { mode: 0o644 });
77

78
// Dynamic permissions based on file
79
vfs.dest('./output', {
80
  mode: (file) => file.extname === '.sh' ? 0o755 : 0o644
81
});
82
```
83

84
#### dirMode
85
Controls directory permissions when creating directories.
86

87
```javascript
88
// Set directory permissions
89
vfs.dest('./output', { dirMode: 0o755 });
90
```
91

92
#### overwrite
93
Controls behavior when files already exist.
94

95
```javascript
96
// Overwrite existing files (default)
97
vfs.dest('./output', { overwrite: true });
98

99
// Skip existing files
100
vfs.dest('./output', { overwrite: false });
101
```
102

103
#### append
104
Controls whether new content is appended to existing files.
105

106
```javascript
107
// Replace existing content (default)
108
vfs.dest('./output', { append: false });
109

110
// Append to existing files
111
vfs.dest('./logs', { append: true });
112
```
113

114
#### sourcemaps
115
Controls sourcemap output behavior.
116

117
```javascript
118
// Write inline sourcemaps
119
vfs.dest('./output', { sourcemaps: true });
120

121
// Write external sourcemaps to same folder
122
vfs.dest('./output', { sourcemaps: '.' });
123

124
// Write external sourcemaps to specific folder
125
vfs.dest('./output', { sourcemaps: './maps' });
126
```
127

128
#### relativeSymlinks
129
Controls symbolic link creation behavior.
130

131
```javascript
132
// Create absolute symlinks (default)
133
vfs.dest('./output', { relativeSymlinks: false });
134

135
// Create relative symlinks
136
vfs.dest('./output', { relativeSymlinks: true });
137
```
138

139
#### useJunctions
140
Windows-specific option for directory symlinks.
141

142
```javascript
143
// Use junctions for directory symlinks on Windows (default)
144
vfs.dest('./output', { useJunctions: true });
145

146
// Use standard symlinks (may require elevated permissions)
147
vfs.dest('./output', { useJunctions: false });
148
```
149

150
### Error Handling
151

152
The dest function throws errors for invalid inputs:
153

154
```javascript
155
// Throws: "Invalid dest() folder argument..."
156
try {
157
  vfs.dest('');
158
} catch (error) {
159
  console.error(error.message);
160
}
161
```
162

163
### Usage Examples
164

165
**Basic file writing:**
166

167
```javascript
168
const vfs = require('vinyl-fs');
169

170
vfs.src('src/**/*.js')
171
  .pipe(vfs.dest('./output'));
172
```
173

174
**Advanced configuration:**
175

176
```javascript
177
vfs.src('src/**/*.js')
178
  .pipe(vfs.dest('./output', {
179
    mode: 0o644,           // Set file permissions
180
    dirMode: 0o755,        // Set directory permissions
181
    sourcemaps: '.',       // Write external sourcemaps
182
    overwrite: true        // Replace existing files
183
  }));
184
```
185

186
**Dynamic output paths:**
187

188
```javascript
189
vfs.src(['src/**/*.js', 'src/**/*.css'])
190
  .pipe(vfs.dest((file) => {
191
    // Organize by file type
192
    return file.extname === '.css' ? './dist/css' : './dist/js';
193
  }));
194
```
195

196
**Conditional writing:**
197

198
```javascript
199
vfs.src('src/**/*')
200
  .pipe(vfs.dest('./output', {
201
    // Only overwrite if source is newer
202
    overwrite: (file) => {
203
      const destPath = path.join('./output', file.relative);
204
      if (!fs.existsSync(destPath)) return true;
205
      
206
      const destStat = fs.statSync(destPath);
207
      return file.stat.mtime > destStat.mtime;
208
    }
209
  }));
210
```
211

212
**Appending to log files:**
213

214
```javascript
215
const through = require('through2');
216

217
vfs.src('logs/*.log')
218
  .pipe(through.obj((file, enc, cb) => {
219
    file.contents = Buffer.concat([
220
      file.contents,
221
      Buffer.from('\n--- Processing complete ---\n')
222
    ]);
223
    cb(null, file);
224
  }))
225
  .pipe(vfs.dest('archive/', { append: true }));
226
```