0
# Options Resolution
1

2
Configuration resolution system for processing entry options and creating resolved configurations with theme integration, addon support, and utility function initialization.
3

4
## Capabilities
5

6
### Resolve Options Function
7

8
Main configuration resolution function that processes entry options and creates a complete resolved configuration for Slidev operations.
9

10
```typescript { .api }
11
/**
12
 * Resolve Slidev configuration from entry options and mode
13
 * @param entryOptions - User-provided entry configuration
14
 * @param mode - Operating mode for the configuration
15
 * @returns Promise<ResolvedSlidevOptions> - Complete resolved configuration
16
 */
17
function resolveOptions(
18
  entryOptions: SlidevEntryOptions,
19
  mode: 'dev' | 'build' | 'export'
20
): Promise<ResolvedSlidevOptions>;
21

22
interface SlidevEntryOptions {
23
  /** Markdown entry file path */
24
  entry: string;
25
  /** Theme identifier (package name, local path, or 'none') */
26
  theme?: string;
27
  /** Remote control password */
28
  remote?: string;
29
  /** Enable Vite inspect plugin for debugging */
30
  inspect?: boolean;
31
  /** Enable PDF download in build mode */
32
  download?: boolean;
33
  /** Base URL for deployment */
34
  base?: string;
35
}
36
```
37

38
**Usage Examples:**
39

40
```typescript
41
import { resolveOptions } from "@slidev/cli";
42

43
// Basic development configuration
44
const devOptions = await resolveOptions({
45
  entry: "slides.md"
46
}, "dev");
47

48
// Production build with custom theme
49
const buildOptions = await resolveOptions({
50
  entry: "presentation.md",
51
  theme: "@slidev/theme-seriph",
52
  base: "/demo/",
53
  download: true
54
}, "build");
55

56
// Export configuration with custom entry
57
const exportOptions = await resolveOptions({
58
  entry: "./docs/slides.md",
59
  theme: "./my-theme"
60
}, "export");
61
```
62

63
### Resolved Options Structure
64

65
Complete resolved configuration structure containing all necessary information for Slidev operations.
66

67
```typescript { .api }
68
interface ResolvedSlidevOptions extends RootsInfo, SlidevEntryOptions {
69
  /** Parsed presentation data */
70
  data: SlidevData;
71
  /** Raw theme identifier as provided */
72
  themeRaw: string;
73
  /** Resolved theme root directories */
74
  themeRoots: string[];
75
  /** Resolved addon root directories */
76
  addonRoots: string[];
77
  /** All resolved root directories (themes + addons + user) */
78
  roots: string[];
79
  /** Operating mode */
80
  mode: 'dev' | 'build' | 'export';
81
  /** Resolved 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
  /** Parsed user package.json */
93
  userPkgJson: Record<string, any>;
94
  /** User workspace root directory */
95
  userWorkspaceRoot: string;
96
}
97
```
98

99
### Data Utils Creation
100

101
Utility function creation system for resolved configurations with performance optimizations and caching.
102

103
```typescript { .api }
104
/**
105
 * Create utility functions and configurations for resolved options
106
 * @param resolved - Resolved options without utils
107
 * @returns Promise<ResolvedSlidevUtils> - Complete utility configuration
108
 */
109
function createDataUtils(
110
  resolved: Omit<ResolvedSlidevOptions, 'utils'>
111
): Promise<ResolvedSlidevUtils>;
112

113
interface ResolvedSlidevUtils {
114
  /** Configured Shiki syntax highlighter */
115
  shiki: HighlighterGeneric<any, any>;
116
  /** Shiki configuration options */
117
  shikiOptions: MarkdownItShikiOptions;
118
  /** KaTeX math rendering options (null if disabled) */
119
  katexOptions: KatexOptions | null;
120
  /** Generated HTML template for index.html */
121
  indexHtml: string;
122
  /** Vite define constants for build-time replacement */
123
  define: Record<string, string>;
124
  /** Icon resolution paths for unplugin-icons */
125
  iconsResolvePath: string[];
126
  /** Function to check if Monaco types should be ignored */
127
  isMonacoTypesIgnored: (pkg: string) => boolean;
128
  /** Function to get available layouts (cached) */
129
  getLayouts: () => Record<string, string>;
130
}
131
```
132

133
**Usage Examples:**
134

135
```typescript
136
import { createDataUtils, resolveOptions } from "@slidev/cli";
137

138
// Create utils for custom resolved options
139
const partialOptions = {
140
  // ... other resolved options without utils
141
  data: slidevData,
142
  roots: [themeRoot, userRoot],
143
  mode: 'dev' as const
144
};
145

146
const utils = await createDataUtils(partialOptions);
147

148
// Access utility functions
149
const layouts = utils.getLayouts();
150
const isIgnored = utils.isMonacoTypesIgnored('@types/node');
151
console.log("Available layouts:", Object.keys(layouts));
152
```
153

154
### Theme Resolution Process
155

156
Theme resolution system supporting npm packages, local themes, and the special 'none' theme.
157

158
```typescript { .api }
159
// Theme resolution workflow
160
interface ThemeResolution {
161
  /** Theme identifier processing */
162
  identifierResolution: {
163
    npmPackage: string;          // "@slidev/theme-default"
164
    localPath: string;           // "./my-theme" or "/abs/path"  
165
    builtinTheme: string;        // "default", "seriph", etc.
166
    noneTheme: "none";           // Disable theming
167
  };
168
  
169
  /** Theme metadata loading */
170
  metadataLoading: {
171
    packageJson: "theme-package-json";
172
    slidevMeta: "slidev-field-metadata";
173
    defaults: "theme-default-config";
174
    colorSchema: "light-dark-both";
175
  };
176
  
177
  /** Theme root resolution */
178
  rootResolution: {
179
    packageRoot: string;         // Theme package directory
180
    layoutsDir: string;          // Theme layouts directory
181
    stylesDir: string;           // Theme styles directory
182
    componentsDir: string;       // Theme components directory
183
  };
184
}
185

186
// Theme metadata structure
187
interface SlidevThemeMeta {
188
  /** Default configuration overrides */
189
  defaults?: Partial<SlidevConfig>;
190
  /** Supported color schemes */
191
  colorSchema?: 'dark' | 'light' | 'both';
192
  /** Required syntax highlighter */
193
  highlighter?: 'shiki';
194
}
195
```
196

197
### Addon Resolution Process
198

199
Addon resolution system for extending Slidev functionality through npm packages.
200

201
```typescript { .api }
202
// Addon resolution workflow
203
interface AddonResolution {
204
  /** Addon discovery */
205
  discovery: {
206
    configField: "config.addons";    // From slidev.config or frontmatter
207
    npmPackages: string[];           // Array of npm package names
208
    localPaths: string[];            // Local addon directories
209
  };
210
  
211
  /** Addon validation */
212
  validation: {
213
    packageExists: boolean;
214
    validStructure: boolean;
215
    compatibleVersion: boolean;
216
  };
217
  
218
  /** Addon integration */
219
  integration: {
220
    rootDirectories: string[];       // Addon root paths
221
    mergedConfigs: "addon-configs";  // Merged addon configurations
222
    pluginRegistration: "automatic"; // Auto-register Vite plugins
223
  };
224
}
225

226
// Addon package structure requirements
227
interface AddonStructure {
228
  "package.json": {
229
    name: string;
230
    slidev?: {
231
      /** Addon metadata */
232
      addonVersion: string;
233
      compatibleSlidevVersion: string;
234
    };
235
  };
236
  
237
  /** Optional addon files */
238
  "layouts/"?: "vue-layout-components";
239
  "components/"?: "vue-components";
240
  "styles/"?: "css-style-files";
241
  "setup/"?: "setup-scripts";
242
  "vite.config.ts"?: "vite-configuration";
243
}
244
```
245

246
### Configuration Merging Process
247

248
Configuration merging system that combines user config, theme defaults, and addon configurations.
249

250
```typescript { .api }
251
// Configuration precedence (highest to lowest)
252
interface ConfigurationPrecedence {
253
  1: "cli-arguments";           // Command line options
254
  2: "frontmatter";            // Slide frontmatter  
255
  3: "slidev-config";          // slidev.config.ts
256
  4: "addon-configs";          // Addon-provided configs
257
  5: "theme-defaults";         // Theme default configs
258
  6: "builtin-defaults";       // Slidev built-in defaults
259
}
260

261
// Configuration merging rules
262
interface MergingRules {
263
  /** Simple values */
264
  primitives: "last-wins";      // Strings, numbers, booleans
265
  
266
  /** Arrays */
267
  arrays: "concatenate";        // Merge arrays together
268
  
269
  /** Objects */  
270
  objects: "deep-merge";        // Recursive object merging
271
  
272
  /** Special fields */
273
  specialFields: {
274
    css: "array-concatenation";
275
    fonts: "object-deep-merge";
276
    addons: "array-concatenation";
277
    monaco: "object-deep-merge";
278
  };
279
}
280
```
281

282
### Root Directory Resolution
283

284
System for resolving all relevant root directories for asset and component discovery.
285

286
```typescript { .api }
287
// Root directory types and purposes
288
interface RootDirectoryTypes {
289
  /** CLI package root */
290
  cliRoot: {
291
    purpose: "builtin-assets-and-components";
292
    contains: ["client/", "node/", "templates/"];
293
  };
294
  
295
  /** Client assets root */
296
  clientRoot: {
297
    purpose: "client-side-assets";
298
    contains: ["main.ts", "components/", "styles/"];
299
  };
300
  
301
  /** User project root */
302
  userRoot: {
303
    purpose: "user-presentation-files";
304
    contains: ["slides.md", "components/", "public/"];
305
  };
306
  
307
  /** Theme roots */
308
  themeRoots: {
309
    purpose: "theme-provided-assets";
310
    contains: ["layouts/", "components/", "styles/"];
311
  };
312
  
313
  /** Addon roots */
314
  addonRoots: {
315
    purpose: "addon-provided-functionality";
316
    contains: ["layouts/", "components/", "setup/"];
317
  };
318
}
319

320
// Directory resolution order
321
interface ResolutionOrder {
322
  /** Asset resolution priority (first found wins) */
323
  assets: ["userRoot", "themeRoots", "addonRoots", "clientRoot"];
324
  
325
  /** Component resolution priority */
326
  components: ["userRoot", "themeRoots", "addonRoots", "clientRoot"];
327
  
328
  /** Layout resolution priority */
329
  layouts: ["userRoot", "themeRoots", "addonRoots", "clientRoot"];
330
  
331
  /** Setup script resolution priority */
332
  setup: ["userRoot", "themeRoots", "addonRoots", "cliRoot"];
333
}
334
```
335

336
### Build-time Constants Generation
337

338
System for generating build-time constants and feature flags based on configuration.
339

340
```typescript { .api }
341
/**
342
 * Generate Vite define constants for build-time replacement
343
 * @param options - Resolved options without utils
344
 * @returns Record<string, string> - Define constants map
345
 */
346
function getDefine(
347
  options: Omit<ResolvedSlidevOptions, 'utils'>
348
): Record<string, string>;
349

350
// Generated constants
351
interface DefineConstants {
352
  /** Environment flags */
353
  __DEV__: boolean;                              // Development mode
354
  __SLIDEV_CLIENT_ROOT__: string;                // Client root path (@fs format)
355
  __SLIDEV_HASH_ROUTE__: boolean;                // Hash routing enabled
356
  __SLIDEV_HAS_SERVER__: boolean;                // Server available
357
  
358
  /** Feature flags */
359
  __SLIDEV_FEATURE_DRAWINGS__: boolean;          // Drawing tools enabled
360
  __SLIDEV_FEATURE_EDITOR__: boolean;            // Editor enabled
361
  __SLIDEV_FEATURE_DRAWINGS_PERSIST__: boolean;  // Drawing persistence
362
  __SLIDEV_FEATURE_RECORD__: boolean;            // Recording enabled
363
  __SLIDEV_FEATURE_PRESENTER__: boolean;         // Presenter mode
364
  __SLIDEV_FEATURE_PRINT__: boolean;             // Print/export enabled
365
  __SLIDEV_FEATURE_BROWSER_EXPORTER__: boolean;  // Browser export
366
  __SLIDEV_FEATURE_WAKE_LOCK__: boolean;         // Wake lock API
367
}
368
```
369

370
### Error Handling in Resolution
371

372
Error handling and validation during the options resolution process.
373

374
```typescript { .api }
375
// Resolution error scenarios
376
interface ResolutionErrors {
377
  /** Entry file errors */
378
  entryFileErrors: {
379
    notFound: "create-from-template-prompt";
380
    notReadable: "permission-error";
381
    invalidFormat: "format-validation-error";
382
  };
383
  
384
  /** Theme resolution errors */
385
  themeErrors: {
386
    notFound: "fallback-to-default";
387
    invalidStructure: "validation-error";
388
    incompatibleVersion: "version-warning";
389
  };
390
  
391
  /** Addon resolution errors */
392
  addonErrors: {
393
    notFound: "skip-with-warning";
394
    invalidStructure: "skip-with-error";
395
    circularDependency: "resolution-error";
396
  };
397
  
398
  /** Configuration errors */
399
  configErrors: {
400
    parseError: "syntax-error-details";
401
    validationError: "validation-failure-details";
402
    mergeConflict: "conflict-resolution-guidance";
403
  };
404
}
405
```
406

407
**Usage Examples:**
408

409
```typescript
410
import { resolveOptions } from "@slidev/cli";
411

412
async function resolveWithErrorHandling() {
413
  try {
414
    const options = await resolveOptions({
415
      entry: "slides.md",
416
      theme: "nonexistent-theme"
417
    }, "dev");
418
    
419
    console.log("Resolution successful");
420
    
421
  } catch (error) {
422
    if (error.message.includes('theme')) {
423
      console.log("Theme resolution failed, using default theme");
424
      // Retry with default theme
425
    } else if (error.message.includes('entry')) {
426
      console.log("Entry file not found, creating from template");
427
      // Handle entry file creation
428
    } else {
429
      console.error("Resolution failed:", error);
430
    }
431
  }
432
}
433
```
434

435
## Integration with Other Systems
436

437
The options resolution system integrates with all other Slidev components:
438

439
- **CLI Commands**: All commands use `resolveOptions()` as first step
440
- **Development Server**: Uses resolved options for Vite configuration
441
- **Build System**: Uses resolved options for production builds
442
- **Export System**: Uses resolved options for export configuration
443
- **Vite Plugin**: Receives resolved options for plugin configuration
444

445
The resolution process ensures consistent configuration across all Slidev operations while providing flexibility for customization and extension.