0
# Build and Processing
1

2
Core build methods for processing files through the plugin pipeline and outputting results. These methods orchestrate the complete Metalsmith workflow from reading files to writing output.
3

4
## Capabilities
5

6
### Build Method
7

8
Execute the complete build process: read files, process through plugins, and write to destination.
9

10
```javascript { .api }
11
/**
12
 * Build with current settings, outputting to destination directory
13
 * @param callback - Optional callback for completion
14
 * @returns Promise resolving to processed files (if no callback provided)
15
 */
16
build(callback?: BuildCallback): Promise<Files> | void;
17

18
type BuildCallback = (error: Error | null, files: Files) => void;
19
```
20

21
**Usage Examples:**
22

23
```javascript
24
import Metalsmith from "metalsmith";
25

26
// Promise-based build
27
try {
28
  const files = await metalsmith.build();
29
  console.log(`Built ${Object.keys(files).length} files`);
30
} catch (error) {
31
  console.error('Build failed:', error);
32
}
33

34
// Callback-based build
35
metalsmith.build((error, files) => {
36
  if (error) {
37
    console.error('Build failed:', error);
38
    return;
39
  }
40
  console.log(`Built ${Object.keys(files).length} files`);
41
});
42
```
43

44
### Process Method
45

46
Process files through plugins without writing to the filesystem. Useful for in-memory processing and testing.
47

48
```javascript { .api }
49
/**
50
 * Process files through plugins without writing to filesystem
51
 * @param callback - Optional callback for completion
52
 * @returns Promise resolving to processed files (if no callback provided)
53
 */
54
process(callback?: BuildCallback): Promise<Files> | void;
55
```
56

57
**Usage Examples:**
58

59
```javascript
60
// Process files in memory only
61
const processedFiles = await metalsmith.process();
62

63
// Useful for testing or preview mode
64
metalsmith.process((error, files) => {
65
  if (error) throw error;
66
  
67
  // Files are processed but not written to disk
68
  Object.keys(files).forEach(filepath => {
69
    console.log(`Processed: ${filepath}`);
70
    console.log(`Content: ${files[filepath].contents.toString()}`);
71
  });
72
});
73
```
74

75
### Run Method
76

77
Run a specific set of files through the plugin pipeline with optional custom plugin list.
78

79
```javascript { .api }
80
/**
81
 * Run files through plugin pipeline
82
 * @param files - Files object to process
83
 * @param callback - Callback for completion
84
 */
85
run(files: Files, callback: BuildCallback): void;
86

87
/**
88
 * Run files through specific plugins
89
 * @param files - Files object to process
90
 * @param plugins - Array of plugins to use (defaults to instance plugins)
91
 * @param callback - Callback for completion
92
 */
93
run(files: Files, plugins: Plugin[], callback: BuildCallback): void;
94

95
/**
96
 * Run files through plugin pipeline (Promise version)
97
 * @param files - Files object to process
98
 * @param plugins - Optional array of plugins to use
99
 * @returns Promise resolving to processed files
100
 */
101
run(files: Files, plugins?: Plugin[]): Promise<Files>;
102
```
103

104
**Usage Examples:**
105

106
```javascript
107
import Metalsmith from "metalsmith";
108
import markdown from "@metalsmith/markdown";
109

110
// Run with default plugins
111
const inputFiles = {
112
  'index.md': {
113
    contents: Buffer.from('# Hello World'),
114
    title: 'Home Page'
115
  }
116
};
117

118
const outputFiles = await metalsmith.run(inputFiles);
119

120
// Run with specific plugins only
121
const customPlugins = [markdown()];
122
const result = await metalsmith.run(inputFiles, customPlugins);
123

124
// Callback version
125
metalsmith.run(inputFiles, (error, files) => {
126
  if (error) throw error;
127
  console.log('Processed files:', Object.keys(files));
128
});
129
```
130

131
### Build Pipeline Process
132

133
The build pipeline follows this sequence:
134

135
1. **Clean** (if enabled): Remove destination directory contents
136
2. **Read**: Load files from source directory with front-matter parsing
137
3. **Process**: Execute plugins in sequence
138
4. **Write**: Output processed files to destination directory
139

140
**Build Process Control:**
141

142
```javascript
143
// Full build with all steps
144
await metalsmith
145
  .clean(true)          // Clean destination first
146
  .source('src')        // Read from src/
147
  .destination('build') // Write to build/
148
  .build();
149

150
// Process only (skip file I/O)
151
await metalsmith.process(); // Only steps 3 (plugins)
152

153
// Custom processing
154
const files = await metalsmith.read();           // Step 2 only
155
const processed = await metalsmith.run(files);   // Step 3 only  
156
await metalsmith.write(processed);               // Step 4 only
157
```
158

159
### Error Handling
160

161
Build methods provide comprehensive error handling for all stages of processing.
162

163
```javascript
164
// Promise error handling
165
try {
166
  await metalsmith.build();
167
} catch (error) {
168
  if (error.code === 'invalid_frontmatter') {
169
    console.error('Front-matter parsing failed:', error.message);
170
  } else if (error.code === 'failed_read') {
171
    console.error('File reading failed:', error.message);
172
  } else if (error.code === 'failed_write') {
173
    console.error('File writing failed:', error.message);
174
  } else {
175
    console.error('Plugin error:', error.message);
176
  }
177
}
178

179
// Callback error handling
180
metalsmith.build((error, files) => {
181
  if (error) {
182
    console.error('Build error:', error.message);
183
    console.error('Stack trace:', error.stack);
184
    return;
185
  }
186
  
187
  console.log('Build successful');
188
});
189
```
190

191
### Watch Mode Processing
192

193
Process files continuously when source files change (experimental feature).
194

195
```javascript { .api }
196
/**
197
 * Enable file watching for continuous rebuilds
198
 * @param options - Watch configuration or boolean
199
 * @returns Metalsmith instance or current watch settings
200
 */
201
watch(options?: boolean | string | string[] | WatchOptions): Metalsmith | boolean | WatchOptions;
202

203
interface WatchOptions {
204
  /** Paths to watch (default: source directory) */
205
  paths?: string[];
206
  /** Wait for write operations to complete */
207
  awaitWriteFinish?: boolean;
208
  /** Additional chokidar options */
209
  [key: string]: any;
210
}
211
```
212

213
**Watch Mode Examples:**
214

215
```javascript
216
// Enable watching of source directory
217
metalsmith
218
  .clean(false)     // Use partial rebuilds
219
  .watch(true)      // Watch source directory
220
  .build((error, files) => {
221
    if (error) {
222
      console.error('Build error:', error);
223
      return;
224
    }
225
    console.log(`Rebuilt ${Object.keys(files).length} files`);
226
  });
227

228
// Watch specific directories
229
metalsmith
230
  .watch(['src', 'templates'])
231
  .process((error, files) => {
232
    // Continuous in-memory processing
233
    console.log('Files reprocessed');
234
  });
235

236
// Stop watching
237
metalsmith.watch(false);
238
```
239

240
### Build Performance
241

242
Tips for optimizing build performance:
243

244
```javascript
245
// Limit file concurrency to prevent resource exhaustion
246
metalsmith.concurrency(50);
247

248
// Use partial rebuilds in watch mode
249
metalsmith.clean(false);
250

251
// Enable debug logging to identify slow plugins
252
metalsmith.env('DEBUG', '@metalsmith/*');
253

254
// Measure build time
255
const startTime = performance.now();
256
await metalsmith.build();
257
const buildTime = ((performance.now() - startTime) / 1000).toFixed(1);
258
console.log(`Build completed in ${buildTime}s`);
259
```