0
# Core API
1

2
Core entry point functions for creating and operating VuePress applications.
3

4
## Capabilities
5

6
### createApp Function
7

8
Creates a VuePress application instance with the provided configuration.
9

10
```javascript { .api }
11
/**
12
 * Creates a VuePress application instance
13
 * @param options - Application configuration options
14
 * @returns App instance for further processing
15
 */
16
function createApp(options?: AppOptions): App;
17

18
interface AppOptions {
19
  /** Source directory containing markdown files (default: 'docs.fallback' directory) */
20
  sourceDir?: string;
21
  /** Array of plugin configurations */
22
  plugins?: PluginConfig[];
23
  /** Theme name or configuration object */
24
  theme?: string | ThemeConfig;
25
  /** Temporary directory path */
26
  temp?: string;
27
  /** Output directory path for build */
28
  dest?: string;
29
  /** Site configuration object */
30
  siteConfig?: SiteConfig;
31
}
32
```
33

34
**Usage Examples:**
35

36
```javascript
37
const { createApp } = require("vuepress");
38

39
// Basic app creation
40
const app = createApp({
41
  sourceDir: "./docs",
42
});
43

44
// App with plugins and theme
45
const app = createApp({
46
  sourceDir: "./docs",
47
  plugins: [
48
    ["@vuepress/plugin-blog", { /* options */ }],
49
    ["@vuepress/plugin-search", { searchMaxSuggestions: 10 }],
50
  ],
51
  theme: "@vuepress/theme-default",
52
  dest: "./dist",
53
});
54

55
// Process the app for build or dev
56
await app.process();
57
```
58

59
### dev Function
60

61
Starts a development server with hot module replacement for real-time editing.
62

63
```javascript { .api }
64
/**
65
 * Starts development server with hot module replacement
66
 * @param options - Development server configuration
67
 * @returns Promise resolving to App instance
68
 */
69
async function dev(options?: DevOptions): Promise<App>;
70

71
interface DevOptions {
72
  /** Source directory containing markdown files */
73
  sourceDir?: string;
74
  /** Array of plugin configurations */
75
  plugins?: PluginConfig[];
76
  /** Theme name or configuration object */
77
  theme?: string | ThemeConfig;
78
  /** Temporary directory path */
79
  temp?: string;
80
  /** Site configuration object */
81
  siteConfig?: SiteConfig;
82
}
83
```
84

85
**Usage Examples:**
86

87
```javascript
88
const { dev } = require("vuepress");
89

90
// Start development server
91
await dev({
92
  sourceDir: "./docs",
93
  theme: "@vuepress/theme-default",
94
});
95

96
// Development with custom configuration
97
await dev({
98
  sourceDir: "./my-docs",
99
  plugins: [
100
    ["@vuepress/plugin-pwa"],
101
  ],
102
  siteConfig: {
103
    title: "My Documentation",
104
    description: "A comprehensive guide",
105
    base: "/docs/",
106
  },
107
});
108
```
109

110
### build Function
111

112
Builds the site for production, generating static HTML files.
113

114
```javascript { .api }
115
/**
116
 * Builds the site for production
117
 * @param options - Build configuration
118
 * @returns Promise resolving to App instance
119
 */
120
async function build(options?: BuildOptions): Promise<App>;
121

122
interface BuildOptions {
123
  /** Source directory containing markdown files */
124
  sourceDir?: string;
125
  /** Array of plugin configurations */
126
  plugins?: PluginConfig[];
127
  /** Theme name or configuration object */
128
  theme?: string | ThemeConfig;
129
  /** Output directory path (default: sourceDir/.vuepress/dist) */
130
  dest?: string;
131
  /** Temporary directory path */
132
  temp?: string;
133
  /** Site configuration object */
134
  siteConfig?: SiteConfig;
135
}
136
```
137

138
**Usage Examples:**
139

140
```javascript
141
const { build } = require("vuepress");
142

143
// Basic production build
144
await build({
145
  sourceDir: "./docs",
146
  dest: "./dist",
147
});
148

149
// Build with advanced configuration
150
await build({
151
  sourceDir: "./src",
152
  dest: "./public",
153
  plugins: [
154
    ["@vuepress/plugin-google-analytics", { ga: "UA-12345678-1" }],
155
    ["@vuepress/plugin-sitemap", { hostname: "https://example.com" }],
156
  ],
157
  siteConfig: {
158
    title: "Production Site",
159
    base: "/",
160
    head: [
161
      ["link", { rel: "icon", href: "/favicon.ico" }],
162
    ],
163
  },
164
});
165
```
166

167
### eject Function
168

169
Ejects the default theme files to the local project for customization.
170

171
```javascript { .api }
172
/**
173
 * Ejects default theme files to local project
174
 * @param dir - Target directory for ejected theme (creates .vuepress/theme subdirectory)
175
 * @returns Promise that resolves when ejection is complete
176
 */
177
async function eject(dir: string): Promise<void>;
178
```
179

180
**Usage Examples:**
181

182
```javascript
183
const { eject } = require("vuepress");
184

185
// Eject default theme to customize
186
await eject("./docs");
187
// Creates ./docs/.vuepress/theme with default theme files
188

189
// Eject to different directory
190
await eject("./my-project");
191
// Creates ./my-project/.vuepress/theme with default theme files
192
```
193

194
### version Constant
195

196
Package version string for compatibility checking.
197

198
```javascript { .api }
199
/** Package version string from package.json */
200
const version: string;
201
```
202

203
**Usage Examples:**
204

205
```javascript
206
const { version } = require("vuepress");
207

208
console.log(`VuePress version: ${version}`);
209
// Output: VuePress version: 1.9.10
210

211
// Version compatibility checking
212
if (version.startsWith("1.")) {
213
  console.log("Using VuePress v1.x");
214
}
215
```
216

217
## Configuration Interfaces
218

219
### PluginConfig
220

221
```javascript { .api }
222
type PluginConfig = 
223
  | string 
224
  | [string, any] 
225
  | Plugin 
226
  | [Plugin, any];
227

228
interface Plugin {
229
  name?: string;
230
  multiple?: boolean;
231
  plugins?: PluginConfig[];
232
  [optionName: string]: any;
233
}
234
```
235

236
### ThemeConfig
237

238
```javascript { .api }
239
interface ThemeConfig {
240
  /** Theme entry point path or module name */
241
  path?: string;
242
  /** Theme configuration options */
243
  [key: string]: any;
244
}
245
```