tessl/npm-vitepress

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

—

Pending

Overview

Eval results

Files

Build and Development API

Name: tessl/npm-vitepress
Author: tessl

VitePress provides APIs for building static sites for production, running development servers with hot reloading, and serving built sites for preview. All build and development functions support extensive customization options.

Capabilities

Build Functions

Production build functionality for generating optimized static sites.

build

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

/**
 * Builds VitePress site for production
 * @param root - Project root directory (defaults to current directory)
 * @param buildOptions - Build configuration options
 * @returns Promise that resolves when build is complete
 */
function build(
  root?: string,
  buildOptions?: BuildOptions & VitePressSpecificBuildOptions
): Promise<void>;

interface VitePressSpecificBuildOptions {
  /**
   * Override base URL for build
   */
  base?: string;
  
  /**
   * Enable Multi-Page Application mode (requires string value for internal routing)
   */
  mpa?: string;
  
  /**
   * Hook called after config resolution
   */
  onAfterConfigResolve?: (config: SiteConfig) => Awaitable<void>;
}

// Note: build() function accepts Vite's BuildOptions extended with VitePress-specific options above

Usage Examples:

import { build } from "vitepress";

// Basic build
await build();

// Build with VitePress-specific options  
await build("./docs", {
  base: "/my-site/",
  onAfterConfigResolve: async (config) => {
    console.log("Config resolved for:", config.site.title);
  }
});

// Build with Vite options (passed through)
await build("./docs", {
  outDir: "./dist",
  minify: true,
  sourcemap: true
});

// MPA mode build
await build("./docs", {
  mpa: "spa-fallback"  // mpa requires string value
});

Development Server Functions

Development server with hot module replacement and fast rebuilds.

createServer

Creates and configures a Vite development server for VitePress with HMR support.

/**
 * Creates Vite development server for VitePress
 * @param root - Project root directory (defaults to current directory)
 * @param serverOptions - Vite server options with VitePress extensions
 * @param recreateServer - Function to recreate server on config changes
 * @returns Promise resolving to Vite dev server instance
 */
function createServer(
  root?: string,
  serverOptions?: ServerOptions,
  recreateServer?: () => Promise<ViteDevServer>
): Promise<ViteDevServer>;

interface ServerOptions extends ViteServerOptions {
  /**
   * Override base URL for development
   */
  base?: string;
  
  /**
   * Enable/disable HMR
   * @default true
   */
  hmr?: boolean | HMROptions;
  
  /**
   * Server host
   * @default 'localhost'
   */
  host?: string | boolean;
  
  /**
   * Server port
   * @default 5173
   */
  port?: number;
  
  /**
   * Enable HTTPS
   * @default false
   */
  https?: boolean | ServerHttpsOptions;
  
  /**
   * Open browser on server start
   * @default false
   */
  open?: boolean | string;
  
  /**
   * CORS configuration
   */
  cors?: boolean | CorsOptions;
  
  /**
   * Proxy configuration
   */
  proxy?: Record<string, string | ProxyOptions>;
  
  /**
   * Custom middleware
   */
  middlewares?: Connect.Server;
  
  /**
   * Force dependency optimization
   * @default false
   */
  force?: boolean;
  
  /**
   * Clear screen on restart
   * @default true
   */
  clearScreen?: boolean;
}

interface HMROptions {
  /**
   * HMR server port
   */
  port?: number;
  
  /**
   * HMR server host
   */
  host?: string;
  
  /**
   * HMR connection options
   */
  clientPort?: number;
  server?: Server;
}

Usage Examples:

import { createServer } from "vitepress";

// Basic development server
const server = await createServer();
await server.listen();
console.log("VitePress dev server running at http://localhost:5173");

// Custom server configuration
const server = await createServer("./docs", {
  port: 3000,
  host: "0.0.0.0",
  open: true,
  cors: true,
  proxy: {
    "/api": "http://localhost:8080"
  }
});

await server.listen(3000);

// HTTPS development server
const server = await createServer("./docs", {
  https: {
    key: readFileSync("path/to/server.key"),
    cert: readFileSync("path/to/server.crt")
  },
  port: 443
});

// Server with custom middleware
const server = await createServer("./docs", {
  middlewares: (app) => {
    app.use("/custom", (req, res, next) => {
      // Custom middleware logic
      next();
    });
  }
});

Preview Server Functions

Serve built VitePress sites for testing and preview.

serve

Serves a built VitePress site using a lightweight static file server.

/**
 * Serves built VitePress site
 * @param options - Server configuration options
 * @returns Promise resolving to server instance
 */
function serve(options?: ServeOptions): Promise<Server>;

interface ServeOptions {
  /**
   * Project root directory
   * @default process.cwd()
   */
  root?: string;
  
  /**
   * Override base URL
   */
  base?: string;
  
  /**
   * Server port
   * @default 4173
   */
  port?: number;
  
  /**
   * Server host
   * @default 'localhost'
   */
  host?: string | boolean;
  
  /**
   * Open browser on start
   * @default false
   */
  open?: boolean | string;
  
  /**
   * CORS configuration
   * @default false
   */
  cors?: boolean;
  
  /**
   * Strict port (fail if port is in use)
   * @default false
   */
  strictPort?: boolean;
  
  /**
   * Custom headers for responses
   */
  headers?: Record<string, string>;
  
  /**
   * Compression options
   */
  compression?: {
    /**
     * Enable gzip compression
     * @default true
     */
    gzip?: boolean;
    
    /**
     * Enable brotli compression
     * @default true
     */
    brotli?: boolean;
    
    /**
     * Compression level (1-9)
     * @default 6
     */
    level?: number;
  };
  
  /**
   * Cache control headers
   */
  cache?: {
    /**
     * Cache control for HTML files
     * @default 'no-cache'
     */
    html?: string;
    
    /**
     * Cache control for assets
     * @default 'max-age=31536000,immutable'
     */
    assets?: string;
  };
}

Usage Examples:

import { serve } from "vitepress";

// Basic preview server
const server = await serve();
console.log("Preview server running at http://localhost:4173");

// Custom preview server
const server = await serve({
  root: "./docs",
  port: 8080,
  host: "0.0.0.0",
  open: true,
  cors: true,
  headers: {
    "X-Custom-Header": "VitePress"
  }
});

// Preview with custom caching
const server = await serve({
  port: 3000,
  cache: {
    html: "no-cache, no-store, must-revalidate",
    assets: "max-age=86400"
  },
  compression: {
    gzip: true,
    brotli: true,
    level: 9
  }
});

// Preview with base path
const server = await serve({
  base: "/my-docs/",
  port: 4000
});

Server Management

Utilities for managing server lifecycle and configuration.

Server Instance Methods

Methods available on the server instances returned by createServer and serve.

interface ViteDevServer {
  /**
   * Start the server
   */
  listen(port?: number, isRestart?: boolean): Promise<ViteDevServer>;
  
  /**
   * Close the server
   */
  close(): Promise<void>;
  
  /**
   * Restart the server
   */
  restart(forceOptimize?: boolean): Promise<void>;
  
  /**
   * Server configuration
   */
  config: ResolvedConfig;
  
  /**
   * HTTP server instance
   */
  httpServer: Server;
  
  /**
   * WebSocket server for HMR
   */
  ws: WebSocketServer;
  
  /**
   * Module graph
   */
  moduleGraph: ModuleGraph;
  
  /**
   * Transform request
   */
  transformRequest(
    url: string,
    options?: TransformOptions
  ): Promise<TransformResult | null>;
  
  /**
   * Warm up files
   */
  warmupRequest(url: string): Promise<void>;
  
  /**
   * SSR transform
   */
  ssrTransform(
    code: string,
    inMap: SourceMap | null,
    url: string
  ): Promise<TransformResult | null>;
  
  /**
   * Load SSR module
   */
  ssrLoadModule(
    url: string,
    opts?: { fixStacktrace?: boolean }
  ): Promise<Record<string, any>>;
}

interface Server {
  /**
   * Server address info
   */
  address(): AddressInfo | string | null;
  
  /**
   * Close the server
   */
  close(callback?: (err?: Error) => void): Server;
  
  /**
   * Listen on port
   */
  listen(port?: number, hostname?: string, callback?: () => void): Server;
  listen(port?: number, callback?: () => void): Server;
  listen(callback?: () => void): Server;
}

Build Optimization

Advanced build optimization features and configuration.

Bundle Analysis

interface BuildResult {
  /**
   * Build output files
   */
  output: OutputBundle;
  
  /**
   * Build warnings
   */
  warnings: RollupWarning[];
  
  /**
   * Build statistics
   */
  stats?: {
    /**
     * Total build time in milliseconds
     */
    buildTime: number;
    
    /**
     * Number of files processed
     */
    fileCount: number;
    
    /**
     * Total output size in bytes
     */
    outputSize: number;
    
    /**
     * Chunk information
     */
    chunks: ChunkInfo[];
  };
}

interface ChunkInfo {
  /**
   * Chunk name
   */
  name: string;
  
  /**
   * Chunk size in bytes
   */
  size: number;
  
  /**
   * Chunk type
   */
  type: "entry" | "chunk" | "asset";
  
  /**
   * Modules in this chunk
   */
  modules: string[];
}

Performance Monitoring

interface PerformanceMetrics {
  /**
   * Page load time metrics
   */
  loadTime: {
    /**
     * Time to first byte
     */
    ttfb: number;
    
    /**
     * First contentful paint
     */
    fcp: number;
    
    /**
     * Largest contentful paint
     */
    lcp: number;
  };
  
  /**
   * Bundle size metrics
   */
  bundleSize: {
    /**
     * JavaScript bundle size
     */
    js: number;
    
    /**
     * CSS bundle size
     */
    css: number;
    
    /**
     * Total asset size
     */
    assets: number;
  };
  
  /**
   * Build performance
   */
  buildPerformance: {
    /**
     * Build duration
     */
    duration: number;
    
    /**
     * Memory usage
     */
    memory: number;
    
    /**
     * CPU usage
     */
    cpu: number;
  };
}

Install with Tessl CLI