MCP WordPress Server

# Build System Guide Complete guide to the TypeScript compilation and build process for the MCP WordPress Server. ## 🏗️ Build Architecture The project uses a modern TypeScript build system with optimization for both development and production environments. ### Build Pipeline ```text TypeScript Source → Compilation → Bundling → Distribution ↓ ↓ ↓ Type Check Optimization NPM Package Docker Image ``` ## 🔧 Build Configuration ### TypeScript Configuration (`tsconfig.json`) ```json { "compilerOptions": { "target": "ES2020", "module": "commonjs", "lib": ["ES2020"], "outDir": "./dist", "rootDir": "./src", "strict": true, "esModuleInterop": true, "skipLibCheck": true, "forceConsistentCasingInFileNames": true, "declaration": true, "declarationMap": true, "sourceMap": true, "removeComments": false, "experimentalDecorators": true, "emitDecoratorMetadata": true }, "include": ["src/**/*"], "exclude": ["node_modules", "dist", "tests"] } ``` ### Build Scripts ```json { "scripts": { "build": "tsc", "build:watch": "tsc --watch", "build:production": "tsc --project tsconfig.prod.json", "typecheck": "tsc --noEmit", "prebuild": "npm run clean", "postbuild": "npm run copy-assets", "clean": "rimraf dist", "copy-assets": "copyfiles -u 1 src/**/*.json dist/" } } ``` ## 🚀 Build Commands ### Development Build ```bash # Standard development build npm run build # Watch mode for continuous development npm run build:watch # Type checking only (fast) npm run typecheck ``` ### Production Build ```bash # Optimized production build npm run build:production # Clean build (removes existing dist/) npm run clean && npm run build # Full verification build npm run typecheck && npm run build && npm test ``` ### Build Analysis ```bash # Check build output ls -la dist/ # Analyze bundle size npm run build && du -sh dist/* # Check TypeScript compilation npm run typecheck -- --listFiles ``` ## 📁 Output Structure ### Build Artifacts ```text dist/ ├── index.js # Main entry point ├── index.d.ts # Type definitions ├── server.js # Server compatibility layer ├── types/ # Type definitions │ ├── wordpress.d.ts │ ├── mcp.d.ts │ └── client.d.ts ├── client/ # WordPress client │ ├── WordPressClient.js │ ├── api.js │ └── managers/ ├── tools/ # MCP tools │ ├── posts.js │ ├── pages.js │ └── ... ├── cache/ # Cache system ├── performance/ # Performance monitoring ├── security/ # Security utilities └── utils/ # Shared utilities ``` ### Source Map Support - **Source Maps**: Enabled for debugging - **Declaration Maps**: TypeScript declaration source maps - **Inline Sources**: Source content embedded in maps ## 🔍 Build Optimization ### TypeScript Compiler Options ```typescript // Performance optimizations { "compilerOptions": { "incremental": true, // Faster rebuilds "tsBuildInfoFile": ".tsbuildinfo", // Build cache "skipLibCheck": true, // Skip type checking of .d.ts files "removeComments": true, // Smaller output (production) "importHelpers": true, // Reduce code duplication "target": "ES2020" // Modern JavaScript features } } ``` ### Build Performance **Incremental Builds**: - TypeScript build cache enabled - Faster subsequent builds - Watch mode optimization **Parallel Processing**: - Type checking and compilation separated - Concurrent build steps where possible ## 🐳 Docker Build ### Dockerfile Build Process ```dockerfile # Multi-stage build for optimization FROM node:18-alpine AS builder WORKDIR /app COPY package*.json ./ RUN npm ci --only=production COPY . . RUN npm run build:production # Production image FROM node:18-alpine AS production WORKDIR /app COPY --from=builder /app/dist ./dist COPY --from=builder /app/node_modules ./node_modules COPY --from=builder /app/package.json ./ EXPOSE 3000 CMD ["node", "dist/index.js"] ``` ### Docker Build Commands ```bash # Build Docker image docker build -t mcp-wordpress . # Build with specific tag docker build -t mcp-wordpress:latest . # Multi-platform build docker buildx build --platform linux/amd64,linux/arm64 -t mcp-wordpress . ``` ## 📦 Package Build ### NPM Package Preparation ```json { "main": "dist/index.js", "types": "dist/index.d.ts", "files": ["dist/", "src/", "README.md", "LICENSE"], "engines": { "node": ">=18.0.0" } } ``` ### Package Build Process ```bash # Prepare package for publishing npm run build:production npm run test npm pack # Verify package contents tar -tzf mcp-wordpress-*.tgz ``` ## 🔧 Development Workflow ### Hot Reload Development ```bash # Start development with hot reload npm run build:watch & npm run dev # Alternative: Use nodemon for automatic restart npm install -g nodemon nodemon --watch dist --exec "npm run dev" ``` ### IDE Integration **VS Code Configuration** (`.vscode/tasks.json`): ```json { "version": "2.0.0", "tasks": [ { "type": "typescript", "tsconfig": "tsconfig.json", "option": "watch", "group": { "kind": "build", "isDefault": true } } ] } ``` ### Build Debugging ```bash # Debug TypeScript compilation npm run typecheck -- --verbose # Show compilation details npm run build -- --listFiles --listEmittedFiles # Check for unused exports npm run build -- --noUnusedLocals --noUnusedParameters ``` ## 🧪 Build Testing ### Build Verification ```bash # Verify clean build npm run clean npm run build npm test # Test built package npm pack npm install -g mcp-wordpress-*.tgz mcp-wordpress --version ``` ### Build Performance Testing ```bash # Measure build time time npm run build # Profile TypeScript compilation npm run build -- --generateTrace trace.json # Analyze build performance npm install -g @typescript/analyze-trace analyze-trace trace.json ``` ## 📊 Build Monitoring ### Build Metrics **Key Performance Indicators**: - **Build Time**: < 30 seconds for full build - **Incremental Build**: < 5 seconds - **Bundle Size**: < 10MB uncompressed - **Type Check Time**: < 15 seconds ### CI/CD Integration ```yaml # GitHub Actions build job build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: "20" cache: "npm" - run: npm ci - run: npm run typecheck - run: npm run build - run: npm test - uses: actions/upload-artifact@v3 with: name: build-artifacts path: dist/ ``` ## 🔍 Troubleshooting ### Common Build Issues **TypeScript Compilation Errors**: ```bash # Clear TypeScript cache rm .tsbuildinfo # Check for type conflicts npm run typecheck -- --strict ``` **Memory Issues**: ```bash # Increase Node.js memory limit export NODE_OPTIONS="--max-old-space-size=4096" npm run build ``` **Module Resolution Issues**: ```bash # Check module resolution npm run typecheck -- --traceResolution > resolution.log # Verify imports npm run build -- --listFiles | grep "error" ``` ### Build Optimization **Slow Builds**: 1. Enable incremental compilation 2. Use `skipLibCheck: true` 3. Reduce `include` patterns 4. Use project references for large codebases **Large Bundle Size**: 1. Enable `removeComments: true` 2. Use tree shaking 3. Split into multiple packages 4. Analyze bundle with tools ## 📚 Build Tools ### Additional Tools ```bash # TypeScript Language Service npm install -g typescript # Build analysis npm install -g source-map-explorer # Bundle analyzer npm install -g webpack-bundle-analyzer ``` ### IDE Extensions **Recommended VS Code Extensions**: - TypeScript Hero - TypeScript Error Translator - TypeScript Importer - Path Intellisense ## 📈 Performance Optimization ### Build Speed Optimization **Configuration Tuning**: ```json { "compilerOptions": { "skipLibCheck": true, // Skip node_modules type checking "incremental": true, // Enable incremental builds "composite": true, // Enable project references "declaration": false, // Disable for dev builds "sourceMap": false // Disable for production builds } } ``` ### Resource Optimization **Memory Management**: - Use `--max-old-space-size` for large projects - Monitor build memory usage - Optimize TypeScript configuration **CPU Optimization**: - Parallel type checking - Incremental builds - Build caching strategies ## 📚 Further Reading - **[Development Setup](DEVELOPMENT_SETUP.md)** - Local development environment - **[Release Process](RELEASE_PROCESS.md)** - Automated release pipeline - **[CI/CD Pipeline](CI_CD_PIPELINE.md)** - GitHub Actions workflows - **[Architecture Guide](ARCHITECTURE.md)** - System design and patterns --- **Optimizing your build?** This build system is designed for both development speed and production efficiency. Each configuration option is tuned for optimal performance.