0
# Symbolic Links (symlink)
1

2
Stream-based symbolic link creation functionality that accepts Vinyl File objects and creates symbolic links pointing to their original locations. Supports both file and directory symlinks with platform-specific optimizations.
3

4
## Capabilities
5

6
### symlink Function
7

8
Creates a writable stream that creates symbolic links from Vinyl File objects with comprehensive options for link creation behavior.
9

10
```javascript { .api }
11
/**
12
 * Creates a writable stream that creates symbolic links from Vinyl File objects
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 symlink(outFolder, options);
19

20
interface SymlinkOptions {
21
  /** Working directory for relative paths (default: process.cwd()) */
22
  cwd?: string;
23
  /** Directory permissions mode */
24
  dirMode?: number | ((file: File) => number);
25
  /** Overwrite existing symlinks (default: true) */
26
  overwrite?: boolean;
27
  /** Create relative symlinks (default: false) */
28
  relativeSymlinks?: boolean;
29
  /** Use junctions on Windows (default: true) */
30
  useJunctions?: boolean;
31
}
32
```
33

34
### Symbolic Link Behavior
35

36
The symlink function modifies Vinyl File objects after processing:
37

38
- **Path properties**: `cwd`, `base`, and `path` are updated to match the destination
39
- **Stat information**: Updated to reflect the symlink on filesystem
40
- **Contents**: Set to `null` (symlinks don't have contents)
41
- **Symlink property**: Added or replaced with the original file path
42

43
### Folder Path Resolution
44

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

47
```javascript
48
// Static folder path
49
vfs.symlink('./links');
50

51
// Dynamic folder based on file properties
52
vfs.symlink((file) => {
53
  return file.extname === '.exe' ? './bin' : './lib';
54
});
55
```
56

57
### Platform-Specific Behavior
58

59
**Windows:**
60
- Directory symlinks are created as junctions by default (requires no special permissions)
61
- Standard symlinks may require elevated permissions
62
- useJunctions option controls this behavior
63

64
**Unix-like systems:**
65
- Standard symbolic links for all file types
66
- No special permissions required
67
- useJunctions option is ignored
68

69
### Option Details
70

71
#### dirMode
72
Controls directory permissions when creating parent directories.
73

74
```javascript
75
// Set directory permissions
76
vfs.symlink('./links', { dirMode: 0o755 });
77

78
// Dynamic permissions based on file
79
vfs.symlink('./links', {
80
  dirMode: (file) => file.isDirectory() ? 0o755 : 0o644
81
});
82
```
83

84
#### overwrite
85
Controls behavior when symlinks already exist at the destination.
86

87
```javascript
88
// Overwrite existing symlinks (default)
89
vfs.symlink('./links', { overwrite: true });
90

91
// Skip existing symlinks
92
vfs.symlink('./links', { overwrite: false });
93
```
94

95
#### relativeSymlinks
96
Controls whether symlinks are created as relative or absolute paths.
97

98
```javascript
99
// Create absolute symlinks (default)
100
vfs.symlink('./links', { relativeSymlinks: false });
101

102
// Create relative symlinks
103
vfs.symlink('./links', { relativeSymlinks: true });
104
```
105

106
**Note**: Relative symlinks are automatically converted to absolute when creating junctions on Windows.
107

108
#### useJunctions
109
Windows-specific option controlling directory symlink creation.
110

111
```javascript
112
// Use junctions for directory symlinks on Windows (default)
113
vfs.symlink('./links', { useJunctions: true });
114

115
// Use standard symlinks (may require elevated permissions on Windows)
116
vfs.symlink('./links', { useJunctions: false });
117
```
118

119
### Error Handling
120

121
The symlink function throws errors for invalid inputs:
122

123
```javascript
124
// Throws: "Invalid symlink() folder argument..."
125
try {
126
  vfs.symlink('');
127
} catch (error) {
128
  console.error(error.message);
129
}
130
```
131

132
### Usage Examples
133

134
**Basic symbolic link creation:**
135

136
```javascript
137
const vfs = require('vinyl-fs');
138

139
// Create symlinks for all JavaScript files
140
vfs.src('src/**/*.js')
141
  .pipe(vfs.symlink('./links'));
142
```
143

144
**Advanced configuration:**
145

146
```javascript
147
vfs.src('src/**/*')
148
  .pipe(vfs.symlink('./links', {
149
    relativeSymlinks: true,  // Create relative symlinks
150
    dirMode: 0o755,         // Set directory permissions
151
    overwrite: true         // Replace existing symlinks
152
  }));
153
```
154

155
**Platform-aware symlink creation:**
156

157
```javascript
158
const os = require('os');
159

160
vfs.src('bin/**/*')
161
  .pipe(vfs.symlink('./links', {
162
    // Use junctions on Windows, regular symlinks elsewhere
163
    useJunctions: os.platform() === 'win32',
164
    relativeSymlinks: os.platform() !== 'win32'
165
  }));
166
```
167

168
**Dynamic symlink organization:**
169

170
```javascript
171
vfs.src(['src/**/*.js', 'src/**/*.css', 'src/**/*.html'])
172
  .pipe(vfs.symlink((file) => {
173
    // Organize symlinks by file type
174
    const ext = file.extname.slice(1); // Remove leading dot
175
    return `./links/${ext}`;
176
  }));
177
```
178

179
**Conditional symlink creation:**
180

181
```javascript
182
const path = require('path');
183

184
vfs.src('src/**/*')
185
  .pipe(vfs.symlink('./links', {
186
    // Only overwrite if original file is newer
187
    overwrite: (file) => {
188
      const linkPath = path.join('./links', file.relative);
189
      if (!fs.existsSync(linkPath)) return true;
190
      
191
      const linkStat = fs.lstatSync(linkPath);
192
      return file.stat.mtime > linkStat.mtime;
193
    }
194
  }));
195
```
196

197
**Creating backup symlinks:**
198

199
```javascript
200
const through = require('through2');
201

202
vfs.src('important/**/*')
203
  .pipe(through.obj((file, enc, cb) => {
204
    // Add timestamp to symlink name for versioning
205
    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
206
    file.basename = `${file.stem}-${timestamp}${file.extname}`;
207
    cb(null, file);
208
  }))
209
  .pipe(vfs.symlink('./backups', {
210
    relativeSymlinks: true,
211
    overwrite: false  // Keep all versions
212
  }));
213
```
214

215
### Working with Existing Symlinks
216

217
When processing existing symlinks with `resolveSymlinks: false`:
218

219
```javascript
220
// Preserve existing symlinks and create symlinks to symlinks
221
vfs.src('**/*', { resolveSymlinks: false })
222
  .pipe(vfs.symlink('./mirror-links', {
223
    relativeSymlinks: true
224
  }));
225
```