Contributing Guide

February 26, 2026 · View on GitHub

Thank you for your interest in contributing to vite-plugin-mock-dev-server! This document provides guidelines and instructions to help you get started.

English | 简体中文

Table of Contents

Code of Conduct

This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.

Getting Started

Prerequisites

  • Node.js: Version ^20 || >=22
  • pnpm: Version >=10.30.1 (this project uses pnpm workspaces)
  • Git: For version control

Repository Setup

  1. Fork the repository

    Click the "Fork" button on the GitHub repository page to create your own fork.

  2. Clone your fork

    git clone https://github.com/YOUR_USERNAME/vite-plugin-mock-dev-server.git
cd vite-plugin-mock-dev-server

  3. Install dependencies

    pnpm install

  4. Verify setup

    # Run linting
pnpm lint

# Run tests
pnpm test

Development Workflow

Project Structure

This is a monorepo managed by pnpm workspaces:

vite-plugin-mock-dev-server/
├── vite-plugin-mock-dev-server/    # Core plugin package
│   ├── src/                        # Source code
│   │   ├── build/                  # Standalone mock server build
│   │   ├── compiler/               # Mock file compiler (esbuild/rolldown)
│   │   ├── cookies/                # Cookie handling
│   │   ├── core/                   # Core plugin logic
│   │   ├── helpers/                # Helper functions
│   │   ├── mockHttp/               # HTTP mock middleware
│   │   ├── mockWebsocket/          # WebSocket mock support
│   │   ├── types/                  # TypeScript type definitions
│   │   └── utils/                  # Utility functions
│   ├── __tests__/                  # Unit tests
│   └── package.json
├── docs/                           # VitePress documentation site
├── example/                        # Example project for testing
├── package.json                    # Root package.json
└── pnpm-workspace.yaml             # pnpm workspace configuration

Development Commands

# Build the plugin
pnpm build

# Start development mode with example project
pnpm dev

# Build example project
pnpm example:build

# Run documentation site in development mode
pnpm docs:dev

# Build documentation site
pnpm docs:build

# Run linting
pnpm lint

# Run tests
pnpm test

# Run tests in watch mode
pnpm test --watch

Running Tests

The project uses Vitest for testing.

# Run all tests
pnpm test

# Run tests with coverage
pnpm test --coverage

# Run tests in watch mode (useful during development)
pnpm test --watch

# Run specific test file
pnpm test src/__tests__/compiler.spec.ts

Debugging

To debug the plugin during development:

  1. Using the example project

    The example/ directory contains a test project that uses the plugin:

    pnpm dev

    This starts the example Vite project with the plugin loaded.

  2. Adding debug logs

    The project uses the debug package. Enable debug logs:

    DEBUG=vite-plugin-mock-dev-server pnpm dev

  3. VS Code debugging

    Create a .vscode/launch.json file:

    {
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Example",
      "runtimeExecutable": "pnpm",
      "runtimeArgs": ["dev"],
      "cwd": "${workspaceFolder}",
      "console": "integratedTerminal"
    }
  ]
}

Coding Guidelines

Code Style

This project uses ESLint with @pengzhanbo/eslint-config for code linting.

# Check code style
pnpm lint

# Auto-fix linting issues
pnpm lint -- --fix

Key style rules:

  • Use single quotes for strings
  • No trailing semicolons
  • 2 spaces indentation
  • Maximum line length: 120 characters

TypeScript Guidelines

  • Strict mode enabled: All code must be type-safe
  • Explicit return types: Public APIs should have explicit return type annotations
  • No any: Avoid using any type; use unknown with type guards when necessary

JSDoc Documentation

All public APIs must include JSDoc comments in the following format:

/**
 * English description
 *
 * 中文描述
 *
 * @param paramName - English description / 中文描述
 * @returns English description / 中文描述
 * @example
 */

Example:

/**
 * Define mock data that can be shared across multiple mock files
 *
 * 定义可在多个 mock 文件间共享的 mock 数据
 *
 * @param key - Unique identifier for the data / 数据的唯一标识符
 * @param initialData - Initial value of the data / 数据的初始值
 * @returns A mock data object with getter, setter, and value properties / 包含 getter、setter 和 value 属性的 mock 数据对象
 * @example
 * ```ts
 * export default defineMockData('posts', [])
 * ```
 */
export function defineMockData<T>(key: string, initialData: T): MockData<T>

Commit Convention

We follow the Angular Commit Convention. Each commit message should follow this format:

<type>(<scope>): <subject>

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting, semicolons, etc.)
  • refactor: Code refactoring
  • perf: Performance improvements
  • test: Adding or updating tests
  • build: Build system changes
  • ci: CI/CD changes
  • chore: Other changes

Examples:

feat(compiler): add support for json5 files
fix(http): resolve cookie parsing issue
docs: update API documentation

Pull Request Process

  1. Create a branch

    git checkout -b feat/your-feature-name
# or
git checkout -b fix/your-bug-fix

  2. Make your changes

    • Write clear, concise code
    • Add tests for new features
    • Update documentation if needed
    • Ensure all tests pass

  3. Commit your changes

    git add .
git commit -m "feat(scope): your commit message"

  4. Push to your fork

    git push origin feat/your-feature-name

  5. Create a Pull Request

    • Go to the original repository on GitHub
    • Click "New Pull Request"
    • Select your fork and branch
    • Fill in the PR template with:
      • Clear description of changes
      • Related issue numbers (if any)
      • Screenshots (if UI changes)

  6. PR Review

    • Maintainers will review your PR
    • Address any requested changes
    • Once approved, your PR will be merged

Release Process

Note: Only maintainers can perform releases.

The project uses bumpp for version management and conventional-changelog for changelog generation.

# Bump version, generate changelog, commit, tag, and push
pnpm release

# Publish to npm
pnpm release:publish

Questions?

If you have any questions or need help, feel free to:

Thank you for contributing! 🎉