Developer Setup Guide

Overview

This guide provides comprehensive setup instructions for the WorkerSQL development environment - a MySQL-compatible edge database platform built on Cloudflare Workers.

Prerequisites

Required Software

Node.js: v18.0.0 or higher (Download)
npm: v8.0.0 or higher (comes with Node.js)
Git: Latest version (Download)
Python: v3.8+ (for security scanning tools)
VS Code: Recommended IDE (Download)

Cloudflare Account Requirements

Cloudflare account with Workers enabled
Workers Paid plan (required for Durable Objects)
API Token with the following permissions:
- Cloudflare Workers:Edit
- Account:Read
- Zone:Read

Installation

1. Clone the Repository

git clone https://github.com/healthfees-org/workersql.git
cd workersql

2. Install Dependencies

# Install Node.js dependencies
npm install

# Install Python dependencies for security scanning
python -m pip install --user pre-commit bandit

3. Setup Pre-commit Hooks

# Install pre-commit hooks
npm run prepare

# Test pre-commit installation
pre-commit run --all-files

4. Configure Wrangler

# Install Wrangler CLI globally (if not already installed)
npm install -g wrangler

# Authenticate with Cloudflare
wrangler auth login

# Copy and configure wrangler.toml
cp wrangler.toml.template wrangler.toml

5. Environment Configuration

Development Environment

Create a .env.local file:

# Copy environment template
cp .env.example .env.local

# Edit with your values
ENVIRONMENT=development
LOG_LEVEL=debug
MAX_SHARD_SIZE_GB=1
CACHE_TTL_MS=300000
CACHE_SWR_MS=600000
SHARD_COUNT=4

Configure Secrets

# Set JWT secret for authentication
wrangler secret put JWT_SECRET

# Set encryption keys
wrangler secret put ENCRYPTION_KEY_PRIMARY
wrangler secret put ENCRYPTION_KEY_SECONDARY

Development Workflow

1. Build the Project

# TypeScript compilation
npm run build

# Watch mode for development
npm run build -- --watch

2. Run Tests

# Run all tests
npm test

# Run specific test suites
npm run test:unit
npm run test:integration
npm run test:coverage

# Run tests in watch mode
npm run test:watch

3. Local Development

# Start local development server
npm run dev

# Test local deployment
curl -X POST http://localhost:8787/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer test-token-12345" \
  -d '{"sql": "SELECT 1 as test"}'

4. Code Quality

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

# Check formatting
npm run format:check

# Run security scans
npm run security:check

# Complete workflow check
npm run workflow:check

IDE Setup

VS Code Extensions

Install these recommended extensions:

{
  "recommendations": [
    "ms-vscode.vscode-typescript-next",
    "esbenp.prettier-vscode",
    "ms-vscode.vscode-eslint",
    "bradlc.vscode-tailwindcss",
    "ms-python.python",
    "ms-python.bandit"
  ]
}

VS Code Settings

Add to your .vscode/settings.json:

{
  "typescript.preferences.strictFunctionTypes": true,
  "typescript.preferences.strictNullChecks": true,
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "eslint.workingDirectories": ["src", "tests"]
}

Testing Strategy

Unit Tests

Located in tests/unit/
Use Jest with ts-jest transformer
Mock Cloudflare Workers environment
Focus on individual service logic

Integration Tests

Located in tests/integration/
Use Miniflare for Cloudflare Workers simulation
Test service interactions
Validate cache and queue behaviors

End-to-End Tests

Located in tests/e2e/
Test complete workflows
Validate API contracts
Performance benchmarking

Browser Tests

Located in tests/browser/
Use Playwright for browser automation
Test client SDK functionality
Cross-browser compatibility

Deployment

Development Deployment

# Deploy to development environment
wrangler deploy --env development

# View deployment logs
wrangler tail

Staging Deployment

# Deploy to staging environment
wrangler deploy --env staging

# Run smoke tests against staging
npm run test:smoke -- --env=staging

Production Deployment

# Deploy to production (requires approval)
wrangler deploy --env production

# Monitor production deployment
wrangler tail --env production

Troubleshooting

Common Issues

Build Failures

# Clear TypeScript cache
npx tsc --build --clean

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

Test Failures

# Update test snapshots
npm test -- --updateSnapshot

# Run tests with verbose output
npm test -- --verbose

# Debug specific test
npm test -- --testNamePattern="test name"

Wrangler Issues

# Re-authenticate
wrangler auth logout
wrangler auth login

# Clear Wrangler cache
rm -rf ~/.wrangler/cache

Pre-commit Hook Failures

# Update pre-commit hooks
pre-commit autoupdate

# Skip hooks temporarily (emergency only)
git commit --no-verify

Performance Issues

Slow Tests

Use --testPathPattern to run specific tests
Implement test parallelization
Mock external dependencies

Build Performance

Use --incremental flag with TypeScript
Configure path mapping correctly
Exclude unnecessary files from compilation

Security Issues

Token Validation Failures

Verify JWT_SECRET is set correctly
Check token expiration times
Validate issuer and audience claims

CORS Issues

Update gateway CORS configuration
Check request headers and methods
Validate origin whitelist

Contributing

Code Style

Follow TypeScript strict mode guidelines
Use ESLint and Prettier configurations
Write comprehensive JSDoc comments
Follow security best practices

Pull Request Process

Create feature branch from main
Implement changes with tests
Run npm run workflow:check
Submit PR with description
Address review feedback
Merge after approval

Security Guidelines

Never commit secrets or credentials
Use Wrangler secrets for sensitive data
Follow OWASP security guidelines
Run security scans before commits

Support

Documentation

Community

GitHub Issues: Report bugs and feature requests
GitHub Discussions: Community support and questions
Security Issues: [email protected]

Internal Support

Development Team: [email protected]
DevOps Team: [email protected]
Security Team: [email protected]

Last updated: September 1, 2025 Version: 1.0.0