Command Line Interface

Complete reference for VitePress CLI commands and options.

Installation

Global Installation

npm install -g vitepress

Local Installation

npm install -D vitepress

Commands

vitepress dev

Start the development server.

vitepress dev [root]

Arguments:

• root - Path to the docs directory (default: current directory)

Options:

• --port <port> - Specify port (default: 5173)
• --host <host> - Specify hostname (default: localhost)
• --https - Use HTTPS
• --open - Open browser on server start
• --base <path> - Public base path
• --outDir <dir> - Output directory for build
• --cache <dir> - Cache directory
• --logLevel <level> - Log level (info | warn | error | silent)

Examples:

# Start dev server on default port
vitepress dev

# Start on specific port
vitepress dev --port 3000

# Start with HTTPS
vitepress dev --https

# Specify docs directory
vitepress dev docs

# Open browser automatically
vitepress dev --open

vitepress build

Build the site for production.

vitepress build [root]

Arguments:

• root - Path to the docs directory (default: current directory)

Options:

• --outDir <dir> - Output directory (default: .vitepress/dist)
• --base <path> - Public base path
• --target <target> - Build target (default: modules)
• --minify [minifier] - Enable/disable minification
• --sourcemap - Generate source maps
• --ssr - Build for server-side rendering
• --mpa - Build in MPA mode

Examples:

# Basic build
vitepress build

# Build to custom directory
vitepress build --outDir dist

# Build with source maps
vitepress build --sourcemap

# Build for SSR
vitepress build --ssr

vitepress preview

Preview the production build locally.

vitepress preview [root]

Arguments:

• root - Path to the docs directory (default: current directory)

Options:

• --port <port> - Specify port (default: 4173)
• --host <host> - Specify hostname
• --https - Use HTTPS
• --open - Open browser on server start
• --outDir <dir> - Directory to serve (default: .vitepress/dist)

Examples:

# Preview on default port
vitepress preview

# Preview on specific port
vitepress preview --port 8080

# Preview with HTTPS
vitepress preview --https

vitepress init

Initialize a new VitePress project.

vitepress init [project-name]

Arguments:

• project-name - Name of the project directory

Options:

• --template <template> - Use a specific template
• --git - Initialize git repository
• --install - Install dependencies automatically

Examples:

# Initialize in current directory
vitepress init

# Initialize new project
vitepress init my-docs

# Initialize with template
vitepress init --template blog

# Initialize with git and auto-install
vitepress init my-docs --git --install

Configuration

Config File Detection

VitePress automatically detects configuration files in this order:

1. .vitepress/config.js
2. .vitepress/config.ts
3. .vitepress/config.mjs
4. .vitepress/config.mts

Environment Variables

Development:

• NODE_ENV=development - Set automatically in dev mode
• VITEPRESS_DEV=true - Set automatically in dev mode

Build:

• NODE_ENV=production - Set automatically in build mode
• VITEPRESS_BUILD=true - Set automatically in build mode

Custom Variables:

# Set custom base path
BASE_PATH=/docs vitepress build

# Set custom port
PORT=3000 vitepress dev

# Enable debug mode
DEBUG=vitepress:* vitepress dev

Advanced Usage

Custom Scripts

Add scripts to your package.json:

{
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs",
    "docs:clean": "rm -rf docs/.vitepress/dist docs/.vitepress/cache"
  }
}

CI/CD Integration

GitHub Actions:

name: Deploy VitePress site to Pages

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
          cache: npm
      
      - run: npm ci
      - run: npm run docs:build
      
      - uses: actions/deploy-pages@v2
        with:
          artifact_name: github-pages
          path: docs/.vitepress/dist

Netlify:

# netlify.toml
[build]
  command = "npm run docs:build"
  publish = "docs/.vitepress/dist"

[build.environment]
  NODE_VERSION = "18"

Vercel:

{
  "buildCommand": "npm run docs:build",
  "outputDirectory": "docs/.vitepress/dist",
  "installCommand": "npm install"
}

Docker Integration

Dockerfile:

FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .
RUN npm run docs:build

FROM nginx:alpine
COPY --from=0 /app/docs/.vitepress/dist /usr/share/nginx/html

EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

Docker Compose:

version: '3.8'
services:
  vitepress:
    build: .
    ports:
      - "80:80"
    volumes:
      - ./docs:/app/docs
    environment:
      - NODE_ENV=production

Debugging

Debug Mode

Enable debug logging:

# Debug all VitePress internals
DEBUG=vitepress:* vitepress dev

# Debug specific modules
DEBUG=vitepress:config,vitepress:build vitepress build

# Debug with verbose output
vitepress dev --logLevel info

Common Issues

Port Already in Use:

# Find process using port
lsof -ti:5173

# Kill process
kill -9 $(lsof -ti:5173)

# Use different port
vitepress dev --port 3000

Build Failures:

# Clear cache
rm -rf node_modules/.vite docs/.vitepress/cache

# Reinstall dependencies
npm ci

# Build with verbose logging
vitepress build --logLevel info

Memory Issues:

# Increase Node.js memory limit
NODE_OPTIONS="--max-old-space-size=4096" vitepress build

# Use alternative build approach
vitepress build --target esnext

Performance Optimization

Build Optimization

# Enable minification
vitepress build --minify

# Disable source maps for production
vitepress build --no-sourcemap

# Use specific target for better performance
vitepress build --target es2020

Development Optimization

# Disable host check for faster startup
vitepress dev --host 0.0.0.0

# Use specific cache directory
vitepress dev --cache .cache

# Reduce log output
vitepress dev --logLevel warn

Programmatic API

Using VitePress Programmatically

import { createServer, build, preview } from 'vitepress'

// Development server
const server = await createServer('docs', {
  port: 3000,
  host: 'localhost'
})

await server.listen()
console.log('Server running at http://localhost:3000')

// Build
await build('docs', {
  outDir: 'dist',
  base: '/my-site/',
  minify: true
})

// Preview
const previewServer = await preview('docs', {
  port: 4000,
  outDir: 'dist'
})

Custom Build Process

import { defineConfig } from 'vitepress'
import { spawn } from 'child_process'

export default defineConfig({
  // ... config

  buildEnd: async (siteConfig) => {
    // Custom post-build processing
    console.log('Build completed, running custom tasks...')
    
    // Generate sitemap
    await generateSitemap(siteConfig)
    
    // Optimize images
    await optimizeImages()
    
    // Deploy to CDN
    await deployToCDN()
  }
})

async function generateSitemap(config) {
  // Custom sitemap generation logic
}

async function optimizeImages() {
  return new Promise((resolve) => {
    const child = spawn('imagemin', ['dist/**/*.{jpg,png}', '--out-dir=dist'])
    child.on('close', resolve)
  })
}

Troubleshooting

Common Error Messages

"Cannot resolve module":

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

"Port 5173 is already in use":

# Use different port
vitepress dev --port 3000

# Or kill existing process
npx kill-port 5173

"Build failed with exit code 1":

# Check for syntax errors in config
node -c .vitepress/config.js

# Build with verbose logging
vitepress build --logLevel info

"Out of memory" errors:

# Increase memory limit
export NODE_OPTIONS="--max-old-space-size=8192"
vitepress build

Getting Help

Check Version:

vitepress --version

View Help:

vitepress --help
vitepress dev --help
vitepress build --help

Community Resources:

• GitHub Issues
• Discord Community
• Stack Overflow

Migration

From VuePress 1.x

# Install migration tool
npm install -g vitepress-migration-tool

# Run migration
vitepress-migrate ./docs

# Manual adjustments may be needed

From Other SSGs

# From GitBook
gitbook-to-vitepress ./gitbook-docs ./vitepress-docs

# From Docusaurus
docusaurus-to-vitepress ./docusaurus-docs ./vitepress-docs

Best Practices

Development Workflow

1. Use npm scripts for consistent commands
2. Set up proper .gitignore for cache and build files
3. Use environment variables for configuration
4. Implement proper error handling in build scripts

Production Deployment

1. Always run vitepress build before deployment
2. Use CDN for static assets
3. Implement proper caching headers
4. Monitor build performance and optimize as needed

Performance Monitoring

1. Use build time analysis tools
2. Monitor bundle size
3. Implement performance budgets
4. Regular dependency updates