Search
Docs Menu
API
Get Started
Edit this page

JavaScript API

Programmatically trigger CLI commands:

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'
console.log('Starting development server...')
const {
  viteConfig, // Resolved Vite configuration
  viteServer, // Vite's development server
} = await dev({
  viteConfig // Vite configuration (optional)
})
await viteServer.listen()
viteServer.printUrls()
viteServer.bindCLIShortcuts({ print: true })
const { port } = viteConfig.server
console.log(`Development server is ready at http://localhost:${port}`)

See: viteConfig option.

Vite types:

build()

Build for production.

import { build } from 'vike/api'
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)
})
viteServer.printUrls()
viteServer.bindCLIShortcuts({ print: true })
const { port } = viteConfig.preview
console.log(`Preview server is ready at http://localhost:${port}`)

See: viteConfig option.

Vite types:

prerender()

Pre-render pages (only needed when prerender.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) {
    // Custom 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