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

TypeScript Source → Compilation → Bundling → Distribution
                 ↓              ↓          ↓
               Type Check    Optimization  NPM Package
                                          Docker Image

🔧 Build Configuration

TypeScript Configuration (`tsconfig.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

{
  "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

# Standard development build
npm run build

# Watch mode for continuous development
npm run build:watch

# Type checking only (fast)
npm run typecheck

Production Build

# 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

# 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

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

// 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

# 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

# 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

{
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "files": ["dist/", "src/", "README.md", "LICENSE"],
  "engines": {
    "node": ">=18.0.0"
  }
}

Package Build Process

# 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

# 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):

{
  "version": "2.0.0",
  "tasks": [
    {
      "type": "typescript",
      "tsconfig": "tsconfig.json",
      "option": "watch",
      "group": {
        "kind": "build",
        "isDefault": true
      }
    }
  ]
}

Build Debugging

# 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

# 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

# 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

# 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:

# Clear TypeScript cache
rm .tsbuildinfo

# Check for type conflicts
npm run typecheck -- --strict

Memory Issues:

# Increase Node.js memory limit
export NODE_OPTIONS="--max-old-space-size=4096"
npm run build

Module Resolution Issues:

# Check module resolution
npm run typecheck -- --traceResolution > resolution.log

# Verify imports
npm run build -- --listFiles | grep "error"

Build Optimization

Slow Builds:

Enable incremental compilation
Use skipLibCheck: true
Reduce include patterns
Use project references for large codebases

Large Bundle Size:

Enable removeComments: true
Use tree shaking
Split into multiple packages
Analyze bundle with tools

📚 Build Tools

Additional Tools

# 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:

{
  "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 - Local development environment
Release Process - Automated release pipeline
CI/CD Pipeline - GitHub Actions workflows
Architecture Guide - 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.

Uh oh!

FilesExpand file tree

BUILD_SYSTEM.md

Latest commit

History