Search
Docs Menu
API
Get Started
Edit this page

JavaScript API

You can programmatically trigger CLI commands by using following functions:

Common use cases:

  • Writing a custom build script for adding post-processing.
  • Building your own CLI in the context of Build Your Own Framework.

dev()

Start the development server:

import { dev } from 'vike/api'
 
console.log('Starting development server...')
 
const { viteServer, viteConfig } = await dev()
await viteServer.listen()
viteServer.printUrls()
viteServer.bindCLIShortcuts({ print: true })
 
const { port } = viteConfig.server
console.log(`Development server is ready at http://localhost:${port}`)

Return & options:

const {
  viteConfig, // Resolved Vite configuration
  viteServer, // Vite's development server
} = await dev({
  vikeConfig, // Vike configuration (optional)
  viteConfig, // Vite configuration (optional)
})
 
// You can access the globalContext object:
import { getGlobalContext } from 'vike'
const globalContext = await getGlobalContext()

See:

Vite types:

build()

Build for production:

import { build } from 'vike/api'
 
console.log('Building app...')
await build()
console.log('Build is done')

Return & options:

await build({
  vikeConfig, // Vike configuration (optional)
  viteConfig, // Vite configuration (optional)
})
 
// You can access the globalContext object:
import { getGlobalContext } from 'vike'
const globalContext = await getGlobalContext()
// If you pre-render pages
console.log(globalContext.prerenderContext)

See:

Vite types:

preview()

Start a server to preview the production build:

import { preview } from 'vike/api'
 
console.log('Starting preview server...')
 
const { viteConfig, viteServer } = await preview()
viteServer.printUrls()
viteServer.bindCLIShortcuts({ print: true })
 
const { port } = viteConfig.preview
console.log(`Preview server is ready at http://localhost:${port}`)

Return & options:

const {
  viteConfig, // Resolved Vite configuration
  viteServer, // Vite's development server
} = await preview({
  vikeConfig, // Vike configuration (optional)
  viteConfig, // Vite configuration (optional)
})
 
// You can access the globalContext object:
import { getGlobalContext } from 'vike'
const globalContext = await getGlobalContext()

See:

Vite types:

prerender()

Pre-render pages (see prerender.disableAutoRun):

import { prerender } from 'vike/api'
 
console.log('Pre-rendering pages...')
await prerender()
console.log('Pre-rendering is done')

Return & options:

const {
  viteConfig // Resolved Vite configuration
} = await prerender({
  vikeConfig, // Vike configuration (optional)
  viteConfig, // Vite configuration (optional)
  pageContextInit, // Initial pageContext (optional)
  onPagePrerender // Called before writing an HTML file (optional)
})
 
// You can access the globalContext object:
import { getGlobalContext } from 'vike'
const globalContext = await getGlobalContext()
console.log(globalContext.prerenderContext)

See:

  • Option viteConfig
  • Access globalContext
  • Option vikeConfig

    You can pass +prerender settings like this:

    await prerender({
  vikeConfig: {
    prerender: {
      keepDistServer: true,
      parallel: false
    }
  }
})
  • pageContextInit: Initial pageContext values. 
    prerender({
  pageContextInit: {
    someData: 42,
    // ...
  }
})

    See also: API > pageContext > Lifecycle.

  • onPagePrerender(): control where/how HTML files are written.
    ⚠️
    This option is a beta feature: expect breaking changes in any minor version update.
    prerender({
  // If onPagePrerender() is set, then Vike won't create HTML files
  onPagePrerender(pageContext) {
    // Custom logic for writing HTML files to the filesystem
    // ...
  }
})

Vite types:

Access globalContext

You can access the globalContext object like this:

import { someApiFunction } from 'vike/api'
import { getGlobalContext } from 'vike'
 
await someApiFunction()
const globalContext = await getGlobalContext()

See: API > getGlobalContext()

Option vikeConfig

All API functions accept the option vikeConfig to pass Vike settings.

You can only pass serializable Vike settings (e.g. +prerender is serializable but +Layout isn't), and you cannot pass Vike hooks. (If you want to understand why, see [Error] Runtime code defined in config file and API > Config Files > Pointer imports.)

We generally recommend to define your Vike settings in your pages/+config.js file instead of using the vikeConfig option. The API automatically loads your +config.js files (just like the CLI).

Option viteConfig

All API functions accept the option viteConfig (with type InlineConfig).

We generally recommend to define your Vite settings in your vite.config.js file instead of using the viteConfig option. The API automatically loads your vite.config.js file (just like the CLI).

If you want to define Vite settings outside of your app (typically when building your own framework) you can do this:

import { dev } from 'vike/api'
 
await dev({
  viteConfig: {
    // vite.config.js can live in node_modules/my-framework/src/vite.config.ts
    configFile: './path/to/vite.config.js',
    // The app's root can be somewhere completely else than vite.config.js
    root: './path/to/app/'
    // Some Vite settings overriding vite.config.js
    /* ... */
  }
})
console.log('Development server is ready')

If you want to define your entire Vite config programmatically:

import { build } from 'vike/api'
 
await build({
  viteConfig: {
    // Don't load any vite.config.js
    configFile: false,
    // All Vite settings
    /* ... */
  }
})
console.log('Build is done')

See also