0
# Build System
1

2
Production build functionality for generating static sites and Single Page Applications (SPAs) from Slidev presentations with optimized assets and optional PDF generation.
3

4
## Capabilities
5

6
### Build Function
7

8
Creates optimized static site builds of Slidev presentations suitable for deployment to web servers or CDNs.
9

10
```typescript { .api }
11
/**
12
 * Build hostable SPA from Slidev presentation
13
 * @param options - Resolved Slidev configuration options
14
 * @param viteConfig - Optional Vite build configuration overrides
15
 * @param args - Build command arguments and options
16
 * @returns Promise that resolves when build completes
17
 */
18
function build(
19
  options: ResolvedSlidevOptions,
20
  viteConfig?: InlineConfig,
21
  args: BuildArgs
22
): Promise<void>;
23
```
24

25
**Usage Examples:**
26

27
```typescript
28
import { build, resolveOptions } from "@slidev/cli";
29

30
// Basic build
31
const options = await resolveOptions({ entry: "slides.md" }, "build");
32
await build(options, {}, { out: "dist", inspect: false });
33

34
// Build with custom configuration
35
await build(options, {
36
  build: {
37
    outDir: "public",
38
    assetsDir: "assets"
39
  },
40
  base: "/presentation/"
41
}, {
42
  out: "public",
43
  base: "/presentation/",
44
  download: true,
45
  inspect: false
46
});
47

48
// Build multiple presentations
49
const presentations = ["intro.md", "advanced.md"];
50
for (const entry of presentations) {
51
  const opts = await resolveOptions({ entry }, "build");
52
  await build(opts, {}, {
53
    out: `dist/${entry.replace('.md', '')}`,
54
    inspect: false
55
  });
56
}
57
```
58

59
### Build Arguments Configuration
60

61
Configuration interface for build command arguments and options.
62

63
```typescript { .api }
64
interface BuildArgs extends ExportArgs {
65
  /** Output directory for built files */
66
  out: string;
67
  /** Base URL for deployment (e.g., "/demo/") */
68
  base?: string;
69
  /** Enable PDF download in built site */
70
  download?: boolean;
71
  /** Enable Vite inspect plugin for debugging */
72
  inspect: boolean;
73
}
74

75
interface ExportArgs {
76
  /** Output file path */
77
  'output'?: string;
78
  /** Export format: pdf|png|pptx|md */
79
  'format'?: string;
80
  /** Timeout for rendering in milliseconds */
81
  'timeout'?: number;
82
  /** Wait time before exporting in milliseconds */
83
  'wait'?: number;
84
  /** Wait until event: networkidle|load|domcontentloaded|none */
85
  'wait-until'?: string;
86
  /** Page ranges to export (e.g., "1,4-5,6") */
87
  'range'?: string;
88
  /** Export as dark theme */
89
  'dark'?: boolean;
90
  /** Export pages for every click animation */
91
  'with-clicks'?: boolean;
92
  /** Override Playwright browser executable path */
93
  'executable-path'?: string;
94
  /** Export pages with table of contents */
95
  'with-toc'?: boolean;
96
  /** Export slide by slide (breaks cross-slide links) */
97
  'per-slide'?: boolean;
98
  /** Scale factor for image export */
99
  'scale'?: number;
100
  /** Export PNG without browser background */
101
  'omit-background'?: boolean;
102
}
103
```
104

105
### Build Process Workflow
106

107
The build system follows a structured workflow for processing presentations.
108

109
```typescript { .api }
110
// Build process stages:
111
interface BuildWorkflow {
112
  /** 1. Generate temporary index.html */
113
  generateIndexHtml(): Promise<void>;
114
  
115
  /** 2. Execute Vite build process */  
116
  viteBuild(): Promise<void>;
117
  
118
  /** 3. Process OG image generation */
119
  generateOgImage(): Promise<void>;
120
  
121
  /** 4. Create deployment files */
122
  createDeploymentFiles(): Promise<void>;
123
  
124
  /** 5. Generate PDF download (if enabled) */
125
  generatePdfDownload(): Promise<void>;
126
  
127
  /** 6. Cleanup temporary files */
128
  cleanup(): Promise<void>;
129
}
130
```
131

132
**Detailed Process:**
133

134
```typescript
135
// 1. Index HTML Generation
136
interface IndexHtmlGeneration {
137
  /** Create temporary index.html from template */
138
  temporaryFile: string;           // options.utils.indexHtml content
139
  originalBackup?: string;         // Backup existing index.html
140
  restoration: "automatic";       // Restore original after build
141
}
142

143
// 2. Vite Build Configuration
144
interface ViteBuildConfig {
145
  /** Build optimizations */
146
  chunkSizeWarningLimit: 2000;    // Increased for presentation assets
147
  outDir: string;                 // From args.out
148
  assetsDir: string;              // Asset organization
149
  base: string;                   // From args.base
150
}
151

152
// 3. OG Image Processing
153
interface OgImageProcessing {
154
  /** Auto-generation conditions */
155
  autoGenerate: boolean;          // config.seoMeta.ogImage === 'auto'
156
  relativeImage: boolean;         // ogImage starts with '.'
157
  copyExisting: boolean;          // Copy existing og-image.png
158
  generateNew: boolean;           // Generate from first slide
159
}
160

161
// 4. Deployment Files
162
interface DeploymentFiles {
163
  /** SPA routing support */
164
  "404.html": "copy-of-index";    // GitHub Pages SPA support
165
  "_redirects": "spa-routing";    // Netlify SPA support
166
}
167

168
// 5. PDF Download Generation
169
interface PdfDownloadGeneration {
170
  /** Conditional generation */
171
  enabled: boolean;               // args.download or config.download
172
  outputPath: string;             // 'slidev-exported.pdf' in build dir
173
  serverPort: number;             // Temporary server for export
174
}
175
```
176

177
### Vite Configuration Integration
178

179
The build system integrates deeply with Vite's build process and configuration.
180

181
```typescript { .api }
182
/**
183
 * Vite configuration resolution for build mode
184
 * @param options - Resolved Slidev options
185
 * @param baseConfig - Base Vite configuration
186
 * @param userConfig - User-provided Vite configuration
187
 * @param mode - Build mode ('build')
188
 * @returns Promise<InlineConfig> - Resolved Vite configuration
189
 */
190
function resolveViteConfigs(
191
  options: ResolvedSlidevOptions,
192
  baseConfig: InlineConfig,
193
  userConfig: InlineConfig,
194
  mode: 'build'
195
): Promise<InlineConfig>;
196

197
// Automatic build optimizations:
198
interface BuildOptimizations {
199
  /** Code splitting */
200
  codeSplitting: {
201
    chunks: "vendor" | "app" | "theme";
202
    dynamicImports: boolean;
203
  };
204
  
205
  /** Asset optimization */
206
  assetOptimization: {
207
    images: "optimized";
208
    fonts: "subsetted";
209
    icons: "tree-shaken";
210
  };
211
  
212
  /** Bundle analysis */
213
  bundleAnalysis: {
214
    chunkSizeWarning: 2000;      // KB threshold
215
    inspectPlugin: boolean;      // Via args.inspect
216
  };
217
}
218
```
219

220
### Asset Processing
221

222
Comprehensive asset processing during the build phase.
223

224
```typescript { .api }
225
// Asset types and processing:
226
interface AssetProcessing {
227
  /** Static assets */
228
  staticAssets: {
229
    images: "copy-optimized";     // PNG, JPG, SVG, etc.
230
    fonts: "copy-subsetted";      // WOFF, WOFF2, TTF
231
    videos: "copy-as-is";         // MP4, WebM
232
    documents: "copy-as-is";      // PDF, etc.
233
  };
234
  
235
  /** Generated assets */
236
  generatedAssets: {
237
    css: "extracted-minified";   // From Vue SFCs and imports
238
    js: "bundled-minified";      // Application bundles
239
    html: "templated-minified";  // Main HTML file
240
  };
241
  
242
  /** Theme assets */
243
  themeAssets: {
244
    layouts: "compiled";         // Vue layout components
245
    styles: "merged";            // Theme-specific styles
246
    components: "tree-shaken";   // Used components only
247
  };
248
}
249
```
250

251
### Output Structure
252

253
Standard output directory structure for built presentations.
254

255
```typescript { .api }
256
// Built output structure:
257
interface BuildOutput {
258
  /** Root files */
259
  "index.html": "main-entry-point";
260
  "404.html": "spa-fallback";
261
  "_redirects": "netlify-config";
262
  "og-image.png"?: "social-media-preview";
263
  "slidev-exported.pdf"?: "download-version";
264
  
265
  /** Asset directories */
266
  "assets/": {
267
    "*.js": "javascript-bundles";
268
    "*.css": "stylesheet-files";
269
    "*.woff2": "font-files";
270
    "*.png|jpg|svg": "image-assets";
271
  };
272
  
273
  /** Static files */
274
  "public/": "copied-static-files";
275
}
276
```
277

278
### Error Handling and Recovery
279

280
Build error handling and recovery mechanisms.
281

282
```typescript { .api }
283
// Build error scenarios:
284
interface BuildErrorHandling {
285
  /** Vite build failures */
286
  viteBuildError: {
287
    cleanup: "restore-index-html";
288
    logging: "detailed-error-info";
289
    recovery: "manual-intervention";
290
  };
291
  
292
  /** Asset processing failures */
293
  assetError: {
294
    ogImage: "skip-generation";
295
    pdfExport: "warn-and-continue";
296
    staticAssets: "copy-available";
297
  };
298
  
299
  /** Configuration errors */
300
  configError: {
301
    validation: "pre-build-check";
302
    reporting: "detailed-messages";
303
    suggestions: "fix-recommendations";
304
  };
305
  
306
  /** File system errors */
307
  fileSystemError: {
308
    permissions: "check-and-report";
309
    diskSpace: "check-and-warn";
310
    cleanup: "best-effort";
311
  };
312
}
313
```
314

315
**Usage Examples:**
316

317
```typescript
318
import { build, resolveOptions } from "@slidev/cli";
319

320
async function buildWithErrorHandling() {
321
  try {
322
    const options = await resolveOptions({
323
      entry: "slides.md",
324
      base: "/demo/"
325
    }, "build");
326
    
327
    await build(options, {
328
      build: {
329
        outDir: "dist",
330
        reportCompressedSize: false  // Faster builds
331
      }
332
    }, {
333
      out: "dist",
334
      base: "/demo/",
335
      download: true,
336
      inspect: false
337
    });
338
    
339
    console.log("Build completed successfully");
340
    
341
  } catch (error) {
342
    if (error.message.includes('ENOSPC')) {
343
      console.error("Insufficient disk space for build");
344
    } else if (error.message.includes('permission')) {
345
      console.error("Permission denied writing to output directory");
346
    } else {
347
      console.error("Build failed:", error.message);
348
    }
349
  }
350
}
351
```
352

353
## Integration with CLI
354

355
The build function is used internally by the CLI `slidev build` command:
356

357
```bash
358
# CLI command internally calls:
359
slidev build [entry..]    # → build(resolvedOptions, viteConfig, args)
360
```
361

362
The programmatic API provides additional control over the build process for custom deployment workflows and CI/CD integration.