Node API

Node API is provided by @vuepress/core package. It is a dependency of the vuepress package, and you can also install it separately:

npm i -D @vuepress/core@next

App

The app instance is available in all hooks of Plugin API.

The BuildApp and DevApp share almost the same properties and methods, except build and dev method.

createBuildApp

• Signature:

const createBuildApp: (config: AppConfig) => BuildApp

• Parameters:

Parameter	Type	Description
config	AppConfig	Config to create a VuePress app.

• Details:

  Create a build mode app instance, which is used for building static files.

• Example:

const build = async () => {
  const app = createBuildApp({
    // ...options
  })

  // initialize and prepare
  await app.init()
  await app.prepare()

  // build
  await app.build()

  // process onGenerated hook
  await app.pluginApi.hooks.onGenerated.process(app)
}

• Also see:
  • Node API > App Methods > build

createDevApp

• Signature:

const createDevApp: (config: AppConfig) => DevApp

• Parameters:

Parameter	Type	Description
config	AppConfig	Config to create a VuePress app.

• Details:

  Create a dev mode app instance, which is used for starting a dev server.

• Example:

const dev = async () => {
  const app = createDevApp({
    // ...options
  })

  // initialize and prepare
  await app.init()
  await app.prepare()

  // start dev server
  const closeDevServer = await app.dev()

  // set up file watchers
  const watchers = []

  // restart dev server
  const restart = async () => {
    await Promise.all([
      // close all watchers
      ...watchers.map((item) => item.close()),
      // close current dev server
      closeDevServer(),
    ])
    await dev()
  }

  // process onWatched hook
  await app.pluginApi.hooks.onWatched.process(app, watchers, restart)
}

• Also see:
  • Node API > App Methods > dev

App Properties

options

• Type: AppOptions

• Details:

  Options of VuePress app.

  The options come from the config argument in createBuildApp / createDevApp, while all optional fields will be filled with a default value.

siteData

• Type: SiteData

• Details:

  Site data that set by user, including all the site config, which will be used in client side.

version

• Type: string

• Details:

  Version of VuePress app, i.e. version of @vuepress/core package.

env.isBuild

• Type: boolean

• Details:

  Environment flag used to identify whether the app is running in build mode, i.e. whether a BuildApp instance.

env.isDev

• Type: boolean

• Details:

  Environment flag used to identify whether the app is running in dev mode, i.e. whether a DevApp instance.

env.isDebug

• Type: boolean

• Details:

  Environment flag used to identify whether the debug mode is enabled.

markdown

• Type: MarkdownIt

• Details:

  The markdown-it instance used for parsing markdown content.

  It is only available in and after onInitialized hook.

pages

• Type: Page[]

• Details:

  The Page object array.

  It is only available in and after onInitialized hook.

App Methods

dir

• Utils:

  • dir.cache(): resolve to cache directory
  • dir.temp(): resolve to temp directory
  • dir.source(): resolve to source directory
  • dir.dest(): resolve to dest directory
  • dir.client(): resolve to @vuepress/client directory
  • dir.public(): resolve to public directory

• Signature:

type AppDirFunction = (...args: string[]) => string

• Details:

  Utils to resolve the absolute file path in corresponding directory.

  If you don't provide any arguments, it will return the absolute path of the directory.

• Example:

// resolve the absolute file path of the `${sourceDir}/README.md`
const homeSourceFile = app.dir.source('README.md')

writeTemp

• Signature:

writeTemp(file: string, content: string): Promise<string>

• Parameters:

Parameter	Type	Description
file	string	Filepath of the temp file that going to be written. Relative to temp directory.
content	string	Content of the temp file that going to be written.

• Details:

  A method to write temp file.

  The written file could be imported via @temp alias in client files.

• Example:

export default {
  // write temp file in onPrepared hook
  async onPrepared() {
    await app.writeTemp('foo.js', "export const foo = 'bar'")
  },
}

// import temp file in client code
import { foo } from '@temp/foo'

init

• Signature:

init(): Promise<void>

• Details:

  Initialize VuePress app.

• Also see:

  • Advanced > Architecture > Core Process and Hooks

prepare

• Signature:

prepare(): Promise<void>

• Details:

  Prepare client temp files.

• Also see:

  • Advanced > Architecture > Core Process and Hooks

build

• Signature:

build(): Promise<void>

• Details:

  Generate static site files.

  This method is only available in BuildApp.

• Also see:

  • Node API > App > createBuildApp
  • Advanced > Architecture > Core Process and Hooks

dev

• Signature:

dev(): Promise<() => Promise<void>>

• Details:

  Start dev server.

  This method is only available in DevApp.

• Also see:

  • Node API > App > createDevApp
  • Advanced > Architecture > Core Process and Hooks

Page

createPage

• Signature:

const createPage: (app: App, options: PageOptions) => Promise<Page>

• Parameters:

Parameter	Type	Description
app	App	The VuePress app instance.
options	PageOptions	Options to create VuePress page.

• Details:

  Create a VuePress page object.

• Example:

import { createPage } from '@vuepress/core'

export default {
  // create an extra page in onInitialized hook
  async onInitialized(app) {
    app.pages.push(
      await createPage(app, {
        path: '/foo.html',
        frontmatter: {
          layout: 'Layout',
        },
        content: `\
# Foo Page

Hello, world.
`,
      }),
    )
  },
}

• Also see:
  • Node API > App Properties > pages
  • Cookbook > Adding Extra Pages

Page Properties

key

• Type: string

• Details:

  Identifier of the page.

  The page key would be used as the name of the page route.

• Also see:

  • Built-in Components > Content

path

• Type: string

• Details:

  Route path of the page.

• Also see:

  • Guide > Page > Routing
  • Node API > Page Properties > pathInferred

title

• Type: string

• Details:

  Title of the page.

• Also see:

  • Frontmatter > title

lang

• Type: string

• Details:

  Language of the page.

• Example:

  • 'en-US'
  • 'zh-CN'

• Also see:

  • Frontmatter > lang

frontmatter

• Type: PageFrontmatter

• Details:

  Frontmatter of the page.

• Also see:

  • Frontmatter

headers

• Type: PageHeader[]

interface PageHeader {
  level: number
  title: string
  slug: string
  children: PageHeader[]
}

• Details:

  Headers of the page.

• Also see:

  • Config > markdown.headers

data

• Type: PageData

interface PageData {
  key: string
  path: string
  title: string
  lang: string
  frontmatter: PageFrontmatter
  headers: PageHeader[]
}

• Details:

  Data of the page.

  Page data would be available in client side.

• Also see:

  • Client API > usePageData
  • Plugin API > extendsPage

content

• Type: string

• Details:

  Raw content of the page.

contentRendered

• Type: string

• Details:

  Rendered content of the page.

date

• Type: string

• Details:

  Date of the page, in 'yyyy-MM-dd' format.

• Example:

  • '0000-00-00'
  • '2021-08-16'

• Also see:

  • Frontmatter > date

deps

• Type: string[]

• Details:

  Dependencies of the page.

  For example, if users import code snippet in the page, the absolute file path of the imported file would be added to deps.

• Also see:

  • Config > markdown.importCode

links

• Type: MarkdownLink[]

interface MarkdownLink {
  raw: string
  relative: string
  absolute: string
}

• Details:

  Links included in the page content.

markdownEnv

• Type: Record<string, unknown>

• Details:

  The env object when parsing markdown content with markdown-it.

  Some markdown-it plugins may store extra information inside this object, and you can make use of them for advanced customization.

  Notice that some other page properties are also extracted from the original env object. Those properties have already been removed from page.markdownEnv.

• Also see:

  • markdown-it > API Documentation > MarkdownIt > parse

pathInferred

• Type: string | null

• Details:

  Route path of the page that inferred from file path.

  By default, the route path is inferred from the relative file path of the Markdown source file. However, users may explicitly set the route path, e.g. permalink, which would be used as the final route path of the page. So we keep the inferred path as a page property in case you may need it.

  It would be null if the page does not come from a Markdown source file.

• Example:

  • '/'
  • '/foo.html'

• Also see:

  • Guide > Page > Routing
  • Node API > Page Properties > path

pathLocale

• Type: string

• Details:

  Locale prefix of the page route path.

  It is inferred from the relative file path of the Markdown source file and the key of locales option in user config.

• Example:

  • '/'
  • '/en/'
  • '/zh/'

• Also see:

  • Config > locales

permalink

• Type: string | null

• Details:

  Permalink of the page.

• Also see:

  • Frontmatter > permalink
  • Frontmatter > permalinkPattern

routeMeta

• Type: Record<string, unknown>

• Details:

  Custom data to be attached to the route record of vue-router.

• Also see:

  • Frontmatter > routeMeta
  • vue-router > API Reference > RouteRecordRaw > meta

What's the difference between route meta and page data?

Both route meta and page data is available in client side. However, route meta is attached to the route record, so the route meta of all pages would be loaded at once when users enter your site. In the contrast, page data is saved in separated files, which would be loaded only when users enter the corresponding page.

Therefore, it's not recommended to store large amounts of info into route meta, otherwise the initial loading speed will be affected a lot when your site has a large number of pages.

sfcBlocks

• Type: MarkdownSfcBlocks

• Details:

  Extracted vue SFC blocks of the page.

• Also see:

  • Config > markdown.sfc

slug

• Type: string

• Details:

  Slug of the page.

  It is inferred from the filename of the Markdown source file.

filePath

• Type: string | null

• Details:

  Absolute path of the Markdown source file of the page.

  It would be null if the page does not come from a Markdown source file.

filePathRelative

• Type: string | null

• Details:

  Relative path of the Markdown source file of the page.

  It would be null if the page does not come from a Markdown source file.