Content Workers Edge Adapter

Native Cloudflare Workers adapter for Content Workers that eliminates the Node.js compatibility layer, achieving 5x smaller bundles and 6x faster cold starts.

🚀 Performance Benefits

| Metric | Node.js Adapter | Edge Adapter | Improvement | |--------|----------------|--------------|-------------| | Bundle Size | 2.5MB | <500KB | 5x smaller | | Cold Start | 100-300ms | 10-50ms | 6x faster | | Memory Usage | 50-128MB | <30MB | 2-4x less |

📦 Installation

npm install @content-workers/edge-adapter

🔧 Usage

Basic Configuration

// cw.config.ts
import { edgeAdapter } from '@content-workers/edge-adapter';

export default {
  adapter: edgeAdapter({
    // Edge-specific configuration
    build: {
      treeShaking: true,
      sizeLimit: 500, // KB
      minify: true
    },
    runtime: {
      memoryLimit: 30, // MB
      timeout: 30, // seconds
      monitoring: true
    }
  })
};

Development Server

# Start edge development server
cw dev --adapter=edge

# Build for edge deployment
cw build --adapter=edge

🌐 Web API Replacements

The edge adapter replaces Node.js APIs with native Web APIs:

Crypto Operations

import { EdgeCryptoService } from '@content-workers/edge-adapter/runtime';

const crypto = new EdgeCryptoService();

// Generate secure tokens
const token = await crypto.generateSecureToken(32);

// Hash passwords
const hash = await crypto.hashPassword('password123');

// Create HMAC signatures
const signature = await crypto.createHMAC('SHA-256', 'secret', 'data');

Stream Processing

import { EdgeStreamService } from '@content-workers/edge-adapter/runtime';

const streams = new EdgeStreamService();

// Create readable stream
const readable = streams.createReadableStream(data);

// Transform streams
const transform = streams.createTransformStream(chunk => processChunk(chunk));

// Convert to buffer
const buffer = await streams.streamToBuffer(readable);

Storage Operations

import { EdgeStorageService } from '@content-workers/edge-adapter/runtime';

const storage = new EdgeStorageService(env);

// Store files in R2
await storage.storeFile('my-bucket', 'path/file.jpg', imageBuffer);

// Retrieve files
const file = await storage.retrieveFile('my-bucket', 'path/file.jpg');

// Store config in KV
await storage.storeConfig('config-kv', 'app-settings', { theme: 'dark' });

Image Processing

import { EdgeImageProcessor } from '@content-workers/edge-adapter/runtime';

const images = new EdgeImageProcessor(env);

// Resize images
const resized = await images.resize(imageBuffer, {
  width: 800,
  height: 600,
  format: 'webp',
  quality: 85
});

// Create thumbnails
const thumbnail = await images.createThumbnail(imageBuffer, 150);

// Generate responsive variants
const variants = await images.createResponsiveVariants(imageBuffer);

🔧 Environment Setup

Cloudflare Workers Configuration

# wrangler.toml
name = "content-workers-app"
main = "dist/index.js"
compatibility_date = "2024-01-01"

[env.production]
vars = { NODE_ENV = "production" }

[[env.production.kv_namespaces]]
binding = "CONFIG_KV"
id = "your-kv-namespace-id"

[[env.production.r2_buckets]]
binding = "MEDIA_BUCKET"
bucket_name = "your-r2-bucket"

[[env.production.d1_databases]]
binding = "DB"
database_name = "your-d1-database"
database_id = "your-d1-database-id"

Environment Variables

# Cloudflare Images (optional)
CLOUDFLARE_ACCOUNT_ID=your-account-id
CLOUDFLARE_IMAGES_API_TOKEN=your-images-token

# Database
DATABASE_URL=your-d1-or-libsql-url

# Security
SECURITY_KEY=your-security-key
JWT_SECRET=your-jwt-secret

🏗️ Architecture

Runtime Detection

The adapter automatically detects the runtime environment:

import { isEdgeRuntime, getRuntimeInfo } from '@content-workers/edge-adapter/runtime';

if (isEdgeRuntime()) {
  // Use edge-optimized implementations
  console.log('Running in Cloudflare Workers');
} else {
  // Fallback to Node.js implementations
  console.log('Running in Node.js');
}

Conditional Loading

Core packages automatically use edge implementations when available:

// Core automatically detects runtime and uses appropriate implementation
import { getCryptoService } from '@content-workers/core';

const crypto = getCryptoService(); // EdgeCryptoService in Workers, Node crypto in Node.js

🧪 Testing

Unit Tests

npm run test
npm run test:coverage

Performance Benchmarks

npm run benchmark

Edge Runtime Testing

# Test with Miniflare (local Workers environment)
npm run test:edge

📊 Monitoring

Performance Monitoring

import { EdgePerformance } from '@content-workers/edge-adapter/runtime';

// Measure function execution
const { result, duration } = await EdgePerformance.measure('api-call', async () => {
  return await apiCall();
});

console.log(`API call took ${duration}ms`);

Error Handling

import { EdgeErrorHandler } from '@content-workers/edge-adapter/runtime';

try {
  await riskyOperation();
} catch (error) {
  const errorResponse = EdgeErrorHandler.createErrorResponse(error, 500);
  return errorResponse;
}

Logging

import { EdgeLogger } from '@content-workers/edge-adapter/runtime';

const logger = new EdgeLogger('MyService');
logger.info('Operation completed', { userId: 123 });
logger.error('Operation failed', error);

🔄 Migration from Node.js Adapter

1. Update Configuration

// Before (Node.js)
import { nodeAdapter } from '@content-workers/node-adapter';

export default {
  adapter: nodeAdapter()
};

// After (Edge)
import { edgeAdapter } from '@content-workers/edge-adapter';

export default {
  adapter: edgeAdapter()
};

2. Update Database Adapter

// Before (SQLite - Node.js only)
import { sqliteAdapter } from '@content-workers/sqlite-adapter';

// After (D1 or LibSQL - Edge compatible)
import { d1Adapter } from '@content-workers/d1-adapter';
// or
import { libsqlAdapter } from '@content-workers/libsql-adapter';

3. Update Storage Configuration

// Before (File system)
export default {
  media: {
    adapter: 'file-system',
    config: { uploadDir: './uploads' }
  }
};

// After (R2)
export default {
  media: {
    adapter: 'r2',
    config: { bucket: 'MEDIA_BUCKET' }
  }
};

🚨 Limitations

Not Supported in Edge Runtime

• File system operations
• Node.js built-in modules
• Native modules (Sharp, better-sqlite3)
• Child processes
• Node.js streams (use Web Streams)

Cloudflare Workers Limits

• 128MB memory limit
• 30-second execution limit
• No persistent file system
• Limited CPU time

📚 API Reference

EdgeAdapter

Main adapter interface for Cloudflare Workers runtime.

EdgeCryptoService

Web Crypto API implementations for cryptographic operations.

EdgeStreamService

Web Streams API implementations for stream processing.

EdgeStorageService

KV and R2 storage implementations for file and config storage.

EdgeImageProcessor

Cloudflare Images and WASM-based image processing.

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📄 License

BSL-1.0 (Business Source License)

🔗 Links

• Content Workers Documentation
• Cloudflare Workers Documentation
• Web APIs Documentation