tessl/npm-vitepress

Vite & Vue powered static site generator with Vue-based theming and markdown processing

—

Pending

Overview

Eval results

Files

Command-Line Interface

Name: tessl/npm-vitepress
Author: tessl

VitePress provides a comprehensive CLI for project initialization, development server management, building for production, and preview serving. The CLI supports extensive configuration options and can be used both directly and programmatically.

Capabilities

Development Commands

Commands for running development servers and working with VitePress projects during development.

dev

Start the VitePress development server with hot module replacement and fast rebuilds.

# Start development server
vitepress [dev] [root]

# Command variants
vitepress dev
vitepress dev ./docs
vitepress dev --port 3000
vitepress dev --host 0.0.0.0 --port 8080

Options:

--port <port>        # Server port (default: 5173)
--host <host>        # Server host (default: localhost)  
--https              # Enable HTTPS with self-signed certificates
--open [path]        # Open browser on server start
--base <path>        # Override base URL for development
--force              # Force dependency optimization
--cors               # Enable CORS
--strictPort         # Exit if port is already in use
--clearScreen        # Clear screen on restart (default: true)

Usage Examples:

# Basic development server
vitepress dev

# Custom port and host
vitepress dev --port 3000 --host 0.0.0.0

# HTTPS development server  
vitepress dev --https --port 443

# Development with custom base path
vitepress dev --base /my-docs/

# Force optimization and open browser
vitepress dev --force --open

# Development for specific directory
vitepress dev ./my-docs --port 8080

Build Commands

Commands for building VitePress sites for production deployment.

build

Build VitePress site for production with static site generation and optimization.

# Build for production
vitepress build [root]

# Command variants  
vitepress build
vitepress build ./docs
vitepress build --outDir ./dist
vitepress build --base /my-site/

Options:

--outDir <dir>       # Output directory (default: .vitepress/dist)
--base <path>        # Override base URL for build
--target <target>    # Build target (default: 'modules')
--minify [minifier]  # Enable/disable minification (default: 'esbuild')
--sourcemap          # Generate source maps
--ssr                # Enable server-side rendering
--mpa                # Build in Multi-Page Application mode
--emptyOutDir        # Empty output directory before build (default: true)

Usage Examples:

# Basic production build
vitepress build

# Build with custom output directory
vitepress build --outDir ./public

# Build with custom base path
vitepress build --base /docs/

# MPA mode build
vitepress build --mpa

# Build with source maps and no minification
vitepress build --sourcemap --minify false

# Build specific directory
vitepress build ./my-docs --outDir ./build

Preview Commands

Commands for serving and previewing built VitePress sites.

preview / serve

Serve a built VitePress site for testing and preview purposes.

# Preview built site
vitepress preview [root]
vitepress serve [root]

# Command variants
vitepress preview
vitepress serve ./docs
vitepress preview --port 4000

Options:

--port <port>        # Server port (default: 4173)
--host <host>        # Server host (default: localhost)
--https              # Enable HTTPS
--open [path]        # Open browser on server start
--base <path>        # Override base URL for preview
--outDir <dir>       # Directory to serve (default: .vitepress/dist)
--strictPort         # Exit if port is already in use
--cors               # Enable CORS

Usage Examples:

# Basic preview server
vitepress preview

# Preview on custom port
vitepress preview --port 8080

# Preview with custom base path
vitepress preview --base /my-docs/

# HTTPS preview server
vitepress preview --https --port 443

# Preview and open browser
vitepress preview --open

# Serve from custom directory
vitepress preview --outDir ./build

Project Initialization

Commands for creating new VitePress projects and scaffolding.

init

Initialize a new VitePress project with interactive setup.

# Initialize new project
vitepress init [root]

# Command variants
vitepress init
vitepress init ./my-docs
vitepress init --theme default

Interactive Options:

The init command provides an interactive setup wizard that asks for:

Project directory
Site title and description
Theme selection (default, custom, or extend existing)
TypeScript support
Git repository initialization
Package manager choice (npm, yarn, pnpm)

Usage Examples:

# Interactive initialization
vitepress init

# Initialize in specific directory
vitepress init ./documentation

# Non-interactive with defaults
echo -e "y\nMy Docs\nDocumentation site\ndefault\nn\ny\nnpm" | vitepress init

Programmatic API

Functions for using VitePress CLI functionality programmatically in Node.js applications.

init

Programmatic project initialization function.

/**
 * Interactive project initialization
 * @param root - Target directory for initialization (optional)
 * @returns Promise that resolves when initialization is complete
 */
function init(root?: string): Promise<void>;

Usage Examples:

import { init } from "vitepress";

// Interactive initialization
await init();

// Initialize in specific directory
await init("./my-documentation");

// Use in custom setup scripts
async function setupProject(projectName: string) {
  const projectDir = `./${projectName}`;
  
  // Create directory
  await fs.mkdir(projectDir, { recursive: true });
  
  // Initialize VitePress
  await init(projectDir);
  
  console.log(`VitePress project created in ${projectDir}`);
}

scaffold

Programmatic project scaffolding with configuration options.

/**
 * Scaffold VitePress project files programmatically
 * @param options - Scaffolding configuration options
 * @returns Path to created project
 */
function scaffold(options: ScaffoldOptions): string;

interface ScaffoldOptions {
  /**
   * Target directory for the project
   */
  root: string;
  
  /**
   * Site title
   */
  title?: string;
  
  /**
   * Site description
   */
  description?: string;
  
  /**
   * Theme type to use
   * @default 'default'
   */
  theme?: "default" | "custom" | "extend";
  
  /**
   * Enable TypeScript support
   * @default false
   */
  typescript?: boolean;
  
  /**
   * Initialize git repository
   * @default true
   */
  git?: boolean;
  
  /**
   * Package manager to use
   * @default 'npm'
   */
  packageManager?: "npm" | "yarn" | "pnpm";
  
  /**
   * Include sample content
   * @default true
   */
  sampleContent?: boolean;
  
  /**
   * Custom template directory
   */
  template?: string;
}

Usage Examples:

import { scaffold } from "vitepress";

// Basic scaffolding
const projectPath = scaffold({
  root: "./my-docs",
  title: "My Documentation",
  description: "Comprehensive project documentation"
});

// Advanced scaffolding with TypeScript
const tsProjectPath = scaffold({
  root: "./ts-docs",
  title: "TypeScript Docs",
  description: "TypeScript project documentation",
  theme: "custom",
  typescript: true,
  packageManager: "pnpm",
  git: true,
  sampleContent: false
});

// Automated project creation
async function createDocsSite(config: ProjectConfig) {
  // Create the project
  const projectPath = scaffold({
    root: config.directory,
    title: config.title,
    description: config.description,
    typescript: config.useTypeScript,
    packageManager: config.packageManager
  });
  
  // Install dependencies
  execSync(`cd ${projectPath} && ${config.packageManager} install`);
  
  // Start development server
  execSync(`cd ${projectPath} && ${config.packageManager} run dev`);
}

Environment Variables

Environment variables that affect VitePress CLI behavior.

Build Environment Variables

# Node environment
NODE_ENV=production          # Set production mode
NODE_ENV=development         # Set development mode

# VitePress specific
VITEPRESS_BASE=/my-docs/     # Override base URL
VITEPRESS_OUTDIR=./build     # Override output directory
VITEPRESS_PORT=3000          # Override default port
VITEPRESS_HOST=0.0.0.0       # Override default host

# Build optimization
VITEPRESS_CACHE_DIR=.cache   # Custom cache directory
VITEPRESS_TEMP_DIR=.temp     # Custom temp directory
VITEPRESS_PARALLEL=4         # Build parallelism level

# Debug options
DEBUG=vitepress:*            # Enable debug logging
VITEPRESS_DEBUG=true         # Enable VitePress debug mode

Usage Examples:

# Production build with custom base
VITEPRESS_BASE=/docs/ vitepress build

# Development with custom port
VITEPRESS_PORT=8080 vitepress dev

# Debug mode development
DEBUG=vitepress:* vitepress dev

# Parallel build
VITEPRESS_PARALLEL=8 vitepress build

Configuration File Detection

VitePress CLI automatically detects and loads configuration files in the following order:

Configuration File Priority

# Configuration files (in priority order)
.vitepress/config.js         # JavaScript configuration
.vitepress/config.ts         # TypeScript configuration  
.vitepress/config.mjs        # ES modules JavaScript
.vitepress/config.mts        # ES modules TypeScript
vitepress.config.js          # Root JavaScript configuration
vitepress.config.ts          # Root TypeScript configuration

Config File Examples

// .vitepress/config.ts
import { defineConfig } from "vitepress";

export default defineConfig({
  title: "My Site",
  description: "Site description",
  
  // CLI-specific overrides
  srcDir: "./src",
  outDir: "./build",
  cacheDir: "./.vitepress/cache",
  
  themeConfig: {
    nav: [
      { text: "Home", link: "/" },
      { text: "Guide", link: "/guide/" }
    ]
  }
});

Advanced CLI Usage

Advanced patterns and workflows for VitePress CLI usage.

Scripting and Automation

#!/bin/bash
# deploy.sh - Automated deployment script

# Build the site
echo "Building VitePress site..."
vitepress build --base /my-docs/

# Deploy to server
echo "Deploying to production..."
rsync -avz .vitepress/dist/ user@server:/var/www/my-docs/

# Verify deployment
curl -f https://example.com/my-docs/ || exit 1

echo "Deployment successful!"

CI/CD Integration

# .github/workflows/deploy.yml
name: Deploy VitePress Site

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Build VitePress site
        run: vitepress build --base /docs/
        
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: .vitepress/dist

Custom CLI Wrappers

// scripts/dev.ts - Custom development script
import { createServer } from "vitepress";
import { spawn } from "child_process";

async function startDevelopment() {
  // Start VitePress dev server
  const server = await createServer(".", {
    port: 3000,
    host: "0.0.0.0"
  });
  
  await server.listen();
  console.log("VitePress dev server running at http://localhost:3000");
  
  // Start additional services
  const apiServer = spawn("node", ["api-server.js"], { stdio: "inherit" });
  const cssWatcher = spawn("sass", ["--watch", "styles:public/css"], { stdio: "inherit" });
  
  // Handle cleanup
  process.on("SIGINT", () => {
    server.close();
    apiServer.kill();
    cssWatcher.kill();
    process.exit();
  });
}

startDevelopment().catch(console.error);

CLI Error Handling and Debugging

Common CLI issues and debugging techniques.

Debug Mode

# Enable debug logging
DEBUG=vitepress:* vitepress dev
DEBUG=vitepress:config vitepress build
DEBUG=vitepress:build vitepress build

# Verbose output
vitepress dev --debug
vitepress build --debug

Common Issues

# Port already in use
vitepress dev --port 3001

# Permission issues
sudo vitepress dev --port 80
# OR
vitepress dev --port 8080

# Memory issues
NODE_OPTIONS="--max-old-space-size=4096" vitepress build

# TypeScript errors
vitepress build --skipTs

Log Output Analysis

// Custom logging in config
export default defineConfig({
  buildEnd: (config) => {
    console.log("Build completed!");
    console.log("Output directory:", config.outDir);
    console.log("Generated pages:", config.pages.length);
  },
  
  transformPageData: (pageData) => {
    console.log("Processing page:", pageData.relativePath);
    return pageData;
  }
});

Install with Tessl CLI