0
# Development Server
1

2
Node.js API for creating and managing Slidev development servers programmatically with Vite integration.
3

4
## Capabilities
5

6
### Create Server Function
7

8
Creates a Vite development server configured for Slidev presentations with hot module reloading and optional server customization.
9

10
```typescript { .api }
11
/**
12
 * Create a Vite development server for Slidev presentations
13
 * @param options - Resolved Slidev configuration options
14
 * @param viteConfig - Optional Vite configuration overrides
15
 * @param serverOptions - Optional Slidev server configuration
16
 * @returns Promise resolving to ViteDevServer instance
17
 */
18
function createServer(
19
  options: ResolvedSlidevOptions,
20
  viteConfig?: InlineConfig,
21
  serverOptions?: SlidevServerOptions
22
): Promise<ViteDevServer>;
23
```
24

25
**Usage Examples:**
26

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

30
// Basic server setup
31
const options = await resolveOptions({ entry: "slides.md" }, "dev");
32
const server = await createServer(options);
33
await server.listen();
34

35
// Server with custom port and host
36
const serverWithConfig = await createServer(options, {
37
  server: {
38
    port: 4000,
39
    host: "0.0.0.0"
40
  }
41
});
42

43
// Server with data loading customization
44
const serverWithLoader = await createServer(options, {}, {
45
  loadData: async (loadedSource) => {
46
    // Custom data processing
47
    console.log("Loading source files:", Object.keys(loadedSource));
48
    // Return false to trigger server restart
49
    return false;
50
  }
51
});
52
```
53

54
### Server Configuration Types
55

56
Configuration interfaces for customizing server behavior and Vite integration.
57

58
```typescript { .api }
59
interface SlidevServerOptions {
60
  /**
61
   * Custom data loading function called when source files change
62
   * @param loadedSource - Map of loaded source file paths to content
63
   * @returns Promise<SlidevData | false> - Return false to trigger server restart
64
   */
65
  loadData?: (loadedSource: Record<string, string>) => Promise<SlidevData | false>;
66
}
67

68
interface ResolvedSlidevOptions extends RootsInfo, SlidevEntryOptions {
69
  /** Parsed presentation data */
70
  data: SlidevData;
71
  /** Raw theme identifier */
72
  themeRaw: string;
73
  /** Theme root directories */
74
  themeRoots: string[];
75
  /** Addon root directories */
76
  addonRoots: string[];
77
  /** All root directories */
78
  roots: string[];
79
  /** Server mode */
80
  mode: 'dev' | 'build' | 'export';
81
  /** Utility functions and configurations */
82
  utils: ResolvedSlidevUtils;
83
}
84

85
interface RootsInfo {
86
  /** CLI package root directory */
87
  cliRoot: string;
88
  /** Client assets root directory */
89
  clientRoot: string;
90
  /** User project root directory */
91
  userRoot: string;
92
  /** User package.json contents */
93
  userPkgJson: Record<string, any>;
94
  /** User workspace root directory */
95
  userWorkspaceRoot: string;
96
}
97
```
98

99
### Vite Integration
100

101
The server automatically configures Vite with Slidev-specific plugins and optimizations.
102

103
```typescript { .api }
104
// Automatic Vite configuration includes:
105
interface AutoViteConfig {
106
  /** Optimized dependency pre-bundling */
107
  optimizeDeps: {
108
    entries: string[];        // Entry points for optimization
109
    force?: boolean;          // Force re-optimization
110
  };
111
  /** Development server configuration */
112
  server: {
113
    port?: number;            // Server port
114
    host?: string;            // Server host
115
    open?: boolean;           // Auto-open browser
116
    strictPort?: boolean;     // Fail if port unavailable
117
  };
118
  /** Logging configuration */
119
  logLevel: LogLevel;         // Vite logging level
120
  /** Base URL configuration */
121
  base: string;               // Public base path
122
}
123
```
124

125
**Usage Examples:**
126

127
```typescript
128
import { createServer, resolveOptions } from "@slidev/cli";
129
import type { InlineConfig } from "vite";
130

131
// Advanced server configuration
132
const viteConfig: InlineConfig = {
133
  server: {
134
    port: 3000,
135
    host: "localhost",
136
    open: true,
137
    strictPort: true
138
  },
139
  optimizeDeps: {
140
    force: true  // Force dependency re-optimization
141
  },
142
  logLevel: "info",
143
  base: "/presentation/"
144
};
145

146
const options = await resolveOptions({
147
  entry: "slides.md",
148
  theme: "@slidev/theme-default",
149
  base: "/presentation/"
150
}, "dev");
151

152
const server = await createServer(options, viteConfig);
153
await server.listen();
154
```
155

156
### Server Lifecycle Management
157

158
Methods for managing server lifecycle and handling cleanup.
159

160
```typescript { .api }
161
// ViteDevServer methods for lifecycle management
162
interface ViteDevServerLifecycle {
163
  /** Start listening on configured port */
164
  listen(port?: number, isRestart?: boolean): Promise<ViteDevServer>;
165
  
166
  /** Close server and cleanup resources */
167
  close(): Promise<void>;
168
  
169
  /** Restart server (close and recreate) */
170
  restart(forceOptimize?: boolean): Promise<void>;
171
  
172
  /** Server URL information */
173
  resolvedUrls?: {
174
    local: string[];
175
    network: string[];
176
  };
177
}
178
```
179

180
**Usage Examples:**
181

182
```typescript
183
import { createServer, resolveOptions } from "@slidev/cli";
184

185
async function serverLifecycleExample() {
186
  const options = await resolveOptions({ entry: "slides.md" }, "dev");
187
  const server = await createServer(options);
188
  
189
  try {
190
    // Start server
191
    await server.listen(3000);
192
    console.log("Server started:", server.resolvedUrls);
193
    
194
    // Server is running...
195
    
196
    // Restart server if needed
197
    await server.restart();
198
    
199
  } finally {
200
    // Always cleanup
201
    await server.close();
202
  }
203
}
204
```
205

206
### Hot Module Reloading
207

208
The server provides automatic hot reloading for slide content and configuration changes.
209

210
```typescript { .api }
211
// Automatic HMR triggers for:
212
interface HMRTriggers {
213
  /** Slide content changes */
214
  slideContentChanges: boolean;      // *.md files
215
  
216
  /** Configuration changes */
217
  configChanges: boolean;            // slidev.config.*, frontmatter
218
  
219
  /** Theme changes */
220
  themeChanges: boolean;             // Theme switching, theme files
221
  
222
  /** Component changes */
223
  componentChanges: boolean;         // *.vue files
224
  
225
  /** Asset changes */
226
  assetChanges: boolean;             // Images, styles, etc.
227
  
228
  /** Setup file changes */
229
  setupChanges: boolean;             // setup/ directory files
230
}
231

232
// Files that trigger full server restart:
233
interface RestartTriggers {
234
  configFields: string[];           // Monaco, routerMode, fonts, css, mdc, etc.
235
  createFiles: string[];            // global-*.vue, uno.config.*, etc.
236
  changeFiles: string[];            // setup/shiki.ts, setup/katex.ts, etc.
237
}
238
```
239

240
### Error Handling
241

242
Server error handling and recovery mechanisms.
243

244
```typescript { .api }
245
// Common error scenarios and handling
246
interface ServerErrorHandling {
247
  /** Port already in use - automatically finds available port */
248
  portConflicts: "auto-resolve";
249
  
250
  /** Missing dependencies - provides installation guidance */
251
  missingDependencies: "guidance";
252
  
253
  /** Invalid configuration - detailed error messages */
254
  configErrors: "detailed-messages";
255
  
256
  /** Theme resolution failures - fallback to default */
257
  themeErrors: "fallback";
258
  
259
  /** File system watch errors - graceful degradation */
260
  watchErrors: "graceful-degradation";
261
}
262
```
263

264
**Usage Examples:**
265

266
```typescript
267
import { createServer, resolveOptions } from "@slidev/cli";
268

269
async function errorHandlingExample() {
270
  try {
271
    const options = await resolveOptions({ entry: "slides.md" }, "dev");
272
    const server = await createServer(options, {
273
      server: {
274
        port: 3000,
275
        strictPort: false  // Allow port auto-resolution
276
      }
277
    });
278
    
279
    await server.listen();
280
    
281
  } catch (error) {
282
    if (error.code === 'EADDRINUSE') {
283
      console.log("Port in use, trying alternative...");
284
      // Server will automatically find available port
285
    } else if (error.message.includes('theme')) {
286
      console.log("Theme error, falling back to default");
287
    } else {
288
      console.error("Server startup failed:", error);
289
    }
290
  }
291
}
292
```
293

294
## Integration with CLI
295

296
The development server function is used internally by the CLI `slidev` command:
297

298
```bash
299
# CLI command internally calls:
300
slidev [entry]    # → createServer(resolvedOptions, viteConfig)
301
```
302

303
The programmatic API provides the same functionality with additional customization options for embedding Slidev in larger applications or custom development workflows.