Configuration Guide

VDK CLI provides extensive configuration options to customize scanning behavior, rule generation, and IDE integrations. This guide covers all configuration methods and options.

Configuration Files

Primary Configuration: `vdk.config.json`

The main project-level configuration file:

{
  "version": "2.0.1",
  "project": {
    "name": "my-nextjs-app",
    "type": "web-application",
    "description": "Next.js application with TypeScript and Tailwind CSS"
  },
  "scanner": {
    "projectPath": ".",
    "outputPath": "./.ai/rules",
    "deepScan": false,
    "ignorePatterns": [
      "**/node_modules/**",
      "**/dist/**",
      "**/build/**",
      "**/.git/**",
      "**/.next/**"
    ],
    "useGitIgnore": true,
    "analysisLevel": "comprehensive",
    "includePatterns": [
      "src/**/*.{ts,tsx,js,jsx}",
      "app/**/*.{ts,tsx}",
      "components/**/*.{ts,tsx}"
    ]
  },
  "integrations": {
    "enabled": ["claude-code", "cursor"],
    "autoDetect": true,
    "setupAll": false,
    "claude-code": {
      "memoryFile": "CLAUDE.md",
      "settingsPath": ".claude/settings.json",
      "enableCommands": true,
      "watchMode": false
    },
    "cursor": {
      "rulesPath": ".cursor/rules/",
      "format": "mdc",
      "autoUpdate": true
    }
  },
  "hub": {
    "enabled": true,
    "endpoint": "https://vdk.tools",
    "team": null,
    "autoSync": false,
    "deployment": {
      "public": false,
      "tags": ["nextjs", "typescript", "tailwind"],
      "description": "Next.js project rules"
    }
  },
  "rules": {
    "template": "default",
    "format": "markdown",
    "includeExamples": true,
    "detailLevel": "comprehensive",
    "validationLevel": "strict"
  }
}

Global Configuration: `~/.vdk/config.json`

User-wide settings that apply to all projects:

{
  "user": {
    "name": "John Doe",
    "email": "john@example.com"
  },
  "defaults": {
    "scanner": {
      "deepScan": false,
      "useGitIgnore": true,
      "analysisLevel": "standard"
    },
    "integrations": {
      "preferredIDE": "claude-code",
      "autoDetect": true,
      "setupAll": false
    },
    "hub": {
      "endpoint": "https://vdk.tools",
      "autoSync": false
    },
    "rules": {
      "template": "comprehensive",
      "includeExamples": true,
      "detailLevel": "standard"
    }
  },
  "templates": {
    "customPath": "~/.vdk/templates",
    "defaults": {
      "react": "react-typescript",
      "nextjs": "nextjs-app-router",
      "node": "node-express"
    }
  }
}

Configuration Methods

1. Configuration File

Create or edit vdk.config.json in your project root:

# Initialize with default config
vdk config init

# Edit configuration
vdk config edit

# Validate configuration
vdk config validate

2. Command Line Options

Override configuration via CLI options:

# Override scanner options
vdk init --deep --ignorePattern "**/tests/**" --projectPath ./src

# Override output path
vdk init --outputPath ./custom-rules

# Override integration settings
vdk init --claude-code --watch

3. Environment Variables

Control VDK behavior with environment variables:

# Debug mode
export VDK_DEBUG=true

# Custom hub endpoint
export VDK_HUB_URL=https://custom-hub.example.com

# Disable telemetry
export VDK_TELEMETRY=false

# Custom templates directory
export VDK_TEMPLATES_DIR=/path/to/templates

# Scanner timeout
export VDK_SCAN_TIMEOUT=300000

# Memory limit
export VDK_MEMORY_LIMIT=2048

4. VDK Config Commands

Manage configuration programmatically:

# View current configuration
vdk config list

# Get specific value
vdk config get scanner.deepScan

# Set configuration value
vdk config set scanner.deepScan true

# Reset to defaults
vdk config reset

# Backup configuration
vdk config backup

# Restore from backup
vdk config restore

Scanner Configuration

Basic Scanner Options

{
  "scanner": {
    "projectPath": ".",
    "outputPath": "./.ai/rules",
    "deepScan": false,
    "ignorePatterns": ["**/node_modules/**"],
    "useGitIgnore": true
  }
}

Advanced Scanner Options

{
  "scanner": {
    "analysisLevel": "comprehensive",
    "includePatterns": [
      "src/**/*.{ts,tsx,js,jsx}",
      "app/**/*.{ts,tsx}",
      "lib/**/*.ts"
    ],
    "excludePatterns": [
      "**/*.test.{ts,tsx,js,jsx}",
      "**/*.spec.{ts,tsx,js,jsx}",
      "**/__tests__/**"
    ],
    "maxDepth": 10,
    "maxFiles": 10000,
    "timeout": 120000,
    "batchSize": 100,
    "streamProcessing": false,
    "cacheResults": true,
    "incrementalScan": false
  }
}

Language-Specific Analyzers

{
  "scanner": {
    "analyzers": {
      "typescript": {
        "enabled": true,
        "strictMode": true,
        "parseDecorators": true,
        "includeTypes": true,
        "maxFileSize": "1MB"
      },
      "javascript": {
        "enabled": true,
        "esVersion": "ES2022",
        "parseJSX": true,
        "includeFlowTypes": false
      },
      "python": {
        "enabled": true,
        "version": "3.9+",
        "parseDocstrings": true,
        "includeTypeHints": true
      }
    }
  }
}

Pattern Detection Configuration

{
  "scanner": {
    "patternDetection": {
      "architectural": {
        "enabled": true,
        "patterns": ["mvc", "mvvm", "component-based", "microservices"]
      },
      "design": {
        "enabled": true,
        "patterns": ["singleton", "factory", "observer", "repository"]
      },
      "framework": {
        "enabled": true,
        "autoDetect": true,
        "specific": ["react", "nextjs", "express", "django"]
      }
    }
  }
}

Integration Configuration

Claude Code Integration

{
  "integrations": {
    "claude-code": {
      "enabled": true,
      "memoryFile": "CLAUDE.md",
      "settingsPath": ".claude/settings.json",
      "commandsPath": ".claude/commands/",
      "enableCommands": true,
      "customCommands": [
        {
          "name": "vdk-analyze",
          "description": "Analyze project with VDK",
          "command": "vdk init --verbose"
        }
      ],
      "memoryFormat": "comprehensive",
      "autoUpdate": true,
      "watchMode": false,
      "contextDepth": "deep"
    }
  }
}

Cursor Integration

{
  "integrations": {
    "cursor": {
      "enabled": true,
      "rulesPath": ".cursor/rules/",
      "format": "mdc",
      "schema": "cursor-mdc-v1",
      "enableDirectives": true,
      "autoUpdate": true,
      "validateOnSave": true,
      "directiveConfig": {
        "context": true,
        "patterns": true,
        "rules": true,
        "technologies": true
      }
    }
  }
}

Windsurf Integration

{
  "integrations": {
    "windsurf": {
      "enabled": true,
      "rulesPath": ".windsurf/rules/",
      "workspacePath": ".windsurf/workspace.json",
      "xmlTags": true,
      "multiAgent": true,
      "agentPersonas": ["developer", "designer", "devops"],
      "contextSwitching": true,
      "templateMode": "advanced"
    }
  }
}

GitHub Copilot Integration

{
  "integrations": {
    "github-copilot": {
      "enabled": true,
      "instructionsPath": ".github/copilot/instructions.json",
      "guidelinesPath": ".github/copilot/guidelines.json",
      "workspacePath": ".vscode/settings.json",
      "enhanceContext": true,
      "patternLearning": true,
      "fileContext": true
    }
  }
}

Hub Configuration

Basic Hub Settings

{
  "hub": {
    "enabled": true,
    "endpoint": "https://vdk.tools",
    "apiKey": null,
    "team": null,
    "autoSync": false
  }
}

Advanced Hub Settings

{
  "hub": {
    "enabled": true,
    "endpoint": "https://vdk.tools",
    "apiKey": "${VDK_HUB_TOKEN}",
    "team": "frontend-team",
    "autoSync": true,
    "syncInterval": "daily",
    "deployment": {
      "public": false,
      "tags": ["nextjs", "typescript", "tailwind"],
      "description": "Next.js project with TypeScript",
      "category": "web-application",
      "license": "MIT"
    },
    "collaboration": {
      "allowContributions": true,
      "reviewRequired": true,
      "notifications": true
    },
    "versioning": {
      "strategy": "semver",
      "autoIncrement": "patch",
      "changelog": true
    }
  }
}

Rule Generation Configuration

Rule Templates

{
  "rules": {
    "template": "comprehensive",
    "customTemplate": null,
    "format": "markdown",
    "includeExamples": true,
    "detailLevel": "comprehensive",
    "validationLevel": "strict",
    "sections": [
      "project-context",
      "technology-stack",
      "coding-conventions",
      "architectural-patterns",
      "examples"
    ]
  }
}

Rule Customization

{
  "rules": {
    "customization": {
      "headerFormat": "# {title}\n\n{description}",
      "sectionOrder": [
        "overview",
        "technologies",
        "patterns",
        "conventions",
        "examples"
      ],
      "includeMetadata": true,
      "addTimestamps": true,
      "versioningEnabled": true
    },
    "content": {
      "maxExamples": 5,
      "exampleLength": "medium",
      "includeComments": true,
      "codeBlockLanguage": "auto",
      "linkToDocumentation": true
    }
  }
}

Performance Configuration

Memory and Processing

{
  "performance": {
    "memory": {
      "maxHeapSize": "2048MB",
      "cacheSize": "512MB",
      "gcThreshold": "1024MB"
    },
    "processing": {
      "maxConcurrency": 4,
      "batchSize": 100,
      "timeout": 120000,
      "retryCount": 3,
      "streamProcessing": false
    },
    "caching": {
      "enabled": true,
      "ttl": 3600,
      "maxSize": "1GB",
      "strategy": "lru"
    }
  }
}

Optimization Settings

{
  "optimization": {
    "incrementalScanning": true,
    "skipUnchangedFiles": true,
    "parallelAnalysis": true,
    "lazyLoading": true,
    "compressionEnabled": true,
    "minificationEnabled": false
  }
}

Environment-Specific Configuration

Development Configuration

{
  "environments": {
    "development": {
      "scanner": {
        "deepScan": true,
        "includeDevDependencies": true,
        "includeTestFiles": true
      },
      "rules": {
        "detailLevel": "comprehensive",
        "includeExamples": true,
        "includeDebugInfo": true
      },
      "integrations": {
        "autoUpdate": true,
        "watchMode": true
      }
    }
  }
}

Production Configuration

{
  "environments": {
    "production": {
      "scanner": {
        "deepScan": false,
        "excludeTestFiles": true,
        "optimizeForSpeed": true
      },
      "rules": {
        "detailLevel": "standard",
        "includeExamples": false,
        "minified": true
      },
      "hub": {
        "autoSync": true,
        "deployment": {
          "public": true
        }
      }
    }
  }
}

CI/CD Configuration

{
  "environments": {
    "ci": {
      "scanner": {
        "timeout": 60000,
        "batchSize": 50,
        "streamProcessing": true
      },
      "rules": {
        "validationOnly": true,
        "outputFormat": "json"
      },
      "integrations": {
        "enabled": [],
        "validationMode": true
      }
    }
  }
}

Configuration Validation

Schema Validation

VDK validates configuration against a JSON schema:

# Validate current configuration
vdk config validate

# Validate specific file
vdk config validate --file ./custom-config.json

# Show configuration schema
vdk config schema

# Fix common configuration issues
vdk config fix

Configuration Testing

# Test configuration with dry run
vdk init --dry-run --config ./test-config.json

# Validate scanner configuration
vdk scan --validate-config

# Test hub connectivity
vdk hub test --config ./config.json

Configuration Examples

React + TypeScript Project

{
  "project": {
    "name": "react-typescript-app",
    "type": "spa",
    "framework": "react"
  },
  "scanner": {
    "includePatterns": ["src/**/*.{ts,tsx}"],
    "analyzers": {
      "typescript": { "strictMode": true },
      "react": { "hooksAnalysis": true }
    }
  },
  "integrations": {
    "enabled": ["claude-code", "cursor"]
  }
}

Next.js Full-Stack Project

{
  "project": {
    "name": "nextjs-fullstack",
    "type": "web-application",
    "framework": "nextjs"
  },
  "scanner": {
    "includePatterns": [
      "app/**/*.{ts,tsx}",
      "components/**/*.{ts,tsx}",
      "lib/**/*.ts"
    ],
    "patternDetection": {
      "architectural": {
        "patterns": ["app-router", "server-components"]
      }
    }
  }
}

Node.js API Project

{
  "project": {
    "name": "nodejs-api",
    "type": "api",
    "framework": "express"
  },
  "scanner": {
    "includePatterns": ["src/**/*.ts", "routes/**/*.ts"],
    "excludePatterns": ["**/*.test.ts"],
    "analyzers": {
      "node": { "version": "18+" },
      "express": { "routeAnalysis": true }
    }
  }
}

Configuration Best Practices

1. Use Environment Variables for Secrets

{
  "hub": {
    "apiKey": "${VDK_HUB_TOKEN}",
    "endpoint": "${VDK_HUB_URL:-https://vdk.tools}"
  }
}

2. Organize by Environment

# Different configs for different environments
vdk.config.json          # Development
vdk.config.prod.json     # Production
vdk.config.ci.json       # CI/CD

3. Version Control Configuration

# Include in git
git add vdk.config.json

# Exclude sensitive data
echo "vdk.config.local.json" >> .gitignore

4. Document Configuration

## VDK Configuration

This project uses VDK CLI with the following configuration:

- **Scanner**: Comprehensive analysis with TypeScript support
- **Integrations**: Claude Code + Cursor
- **Hub**: Connected to team workspace
- **Templates**: Custom React patterns

To update configuration:
```bash
vdk config edit
vdk init --overwrite


### 5. Regular Configuration Maintenance

```bash
# Weekly maintenance script
#!/bin/bash
vdk config validate
vdk config backup
vdk update
vdk init --overwrite

Next Steps

Command Examples - Real-world configuration examples
Integration Setup - Configure specific IDEs
Advanced Configuration - Advanced customization options
Troubleshooting - Fix configuration issues

Scanner

On this page