Search
Docs Menu
API
Get Started
Edit this page

JavaScript API

Programmatically trigger CLI commands.

import { dev, build, preview, prerender } from 'vike/api'
 
// Same as `$ vike dev`
await dev()
console.log('Development server is ready')
 
// Same as `$ vike build`
await build()
console.log('Build is done')
 
// Same as `$ vike preview`
await preview()
console.log('Preview server is ready')
 
// Same as `$ vike prerender`
await prerender()
console.log('Pre-rendering is done')

Common use cases:

  • Building your own CLI in the context of Build Your Own Framework.
  • Writing a custom build script, for example to add a post-processing build step.

dev()

Start the development server.

import { dev } from 'vike/api'
const {
  viteConfig, // Resolved Vite configuration
  viteServer, // Vite's development server
} = await dev({
  viteConfig // Vite configuration (optional)
})
console.log('Development server is ready')

See: viteConfig option.

Vite types:

build()

Build for production.

import { build } from 'vike/api'
const {
  rollupOutputClient, // Generated dist/client/ files for the client-side
  rollupOutputServer, // Generated dist/server/ files for the server-side
} = await build({
  viteConfig // Vite configuration (optional)
})
console.log('Build is done')

See: viteConfig option.

preview()

Start preview server using production build (only works for SSG apps).

import { preview } from 'vike/api'
const {
  viteConfig, // Resolved Vite configuration
  viteServer, // Vite's development server
} = await preview({
  viteConfig // Vite configuration (optional)
})
console.log('Preview server is ready')

See: viteConfig option.

Vite types:

prerender()

Pre-render pages (only needed when partial.disableAutoRun is true).

import { prerender } from 'vike/api'
const {
  viteConfig // Resolved Vite configuration
} = await prerender({
  viteConfig, // Vite configuration (optional)
  pageContextInit, // Initial pageContext (optional)
  onPagePrerender // Called before writing an HTML file (optional)
})
console.log('Pre-rendering is done')

For more settings, see API > prerender.

Vite types:

Options:

  • viteConfig: See viteConfig option.
  • pageContextInit: Initial pageContext values. 
    prerender({
  pageContextInit: {
    someData: 42,
    // ...
  }
})
    See also: API > pageContext > Lifecycle.
  • onPagePrerender(): control where/how HTML files are written.
    ⚠️
    Don't use this option without having contacted a Vike maintainer: this functionality may be changed/removed at any time.
    prerender({
  // If onPagePrerender() is set, then Vike won't create HTML files
  onPagePrerender(pageContext) {
    // Cusotm logic for writing HTML files to the filesystem
    // ...
  }
})

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