@cloudmock/core

Zero-dependency, full-featured Cloudflare services simulator with embedded dashboard for local development and testing.

CloudMock is a complete local development environment that simulates ALL Cloudflare Workers services.CloudMock is fully standalone, works offline, and includes an embedded real-time dashboard.

Features

• Zero Runtime Dependencies - Everything built from scratch
• All Cloudflare Services - KV, R2, D1, Durable Objects, Queues, Cache, AI, Vectorize, and more
• Embedded Dashboard - Real-time dashboard works completely offline
• 100% API Compatible - Drop-in replacement for Cloudflare Workers
• Simulation Layer - Latency, errors, limits, network conditions
• TypeScript Native - Full type safety with strict mode
• Testing First - 100% test coverage with test utilities

Quick Start

# Install
npm install -D @cloudmock/core

# Or use directly
npx cloudmock

Usage

Basic Example

import { createCloud, kv, r2, d1 } from '@cloudmock/core';

// Create cloud instance
const cloud = createCloud({
  plugins: [
    kv('MY_KV'),
    r2('MY_BUCKET'),
    d1('MY_DB')
  ]
});

// Access bindings
const env = cloud.env;

// Use KV
await env.MY_KV.put('key', 'value');
const value = await env.MY_KV.get('key');

// Start server
await cloud.listen(8787);
console.log('Running at http://localhost:8787');
console.log('Dashboard at http://localhost:8787/__dashboard');

With wrangler.toml

CloudMock automatically detects and parses your wrangler.toml:

# Auto-detect configuration
cloudmock serve

CLI Commands

# Start development server
cloudmock serve

# Seed data
cloudmock seed ./fixtures.json

# Export data
cloudmock export ./backup.json

# Run migrations
cloudmock migrate

# Generate types
cloudmock generate:types

# Check configuration
cloudmock doctor

Supported Services

Storage (Tier 1)

• Workers KV - Full API with TTL, metadata, pagination
• R2 - Object storage with multipart upload
• D1 - SQLite database with custom SQL parser
• Durable Objects - Full API with WebSocket and alarms
• Queues - Producer/consumer with DLQ
• Cache - Full Cache API compatibility

AI & Data (Tier 2)

• Workers AI - Mock AI with configurable responses
• Vectorize - Vector database with similarity search

Runtime (Tier 3)

• Runtime APIs - Request/Response with CF extensions
• Context - ExecutionContext with waitUntil
• Scheduled - Cron triggers and scheduler
• Fetch Mock - Pattern-based request mocking
• Rate Limiting - Token bucket algorithm

Advanced (Tier 4)

• Hyperdrive - Connection pooling mock
• Analytics - Analytics Engine dataset
• Service Bindings - Multi-worker support
• Email - Email message mock
• Browser - Browser rendering mock
• Images - Image transformation
• Workflows - Durable execution

Configuration

Programmatic

import { createCloud, kv, d1, durableObjects } from '@cloudmock/core';

const cloud = createCloud({
  // Storage
  persist: true,
  persistPath: './.cloudmock',

  // Plugins
  plugins: [
    kv('CACHE', 'SESSIONS'),
    d1('DB', { schema: './schema.sql' }),
    durableObjects({ COUNTER: CounterDO })
  ],

  // Simulation
  simulation: {
    latency: { min: 5, max: 50 },
    errorRate: 0.01,
    enforceLimits: true,
    geo: { country: 'TR', colo: 'IST' }
  },

  // Dashboard
  dashboard: {
    enabled: true,
    path: '/__dashboard',
    theme: 'dark'
  }
});

wrangler.toml

name = "my-worker"
main = "src/index.ts"
compatibility_date = "2024-01-01"

[vars]
API_KEY = "secret"

[[kv_namespaces]]
binding = "MY_KV"
id = "xxx"

[[r2_buckets]]
binding = "MY_BUCKET"
bucket_name = "my-bucket"

[[d1_databases]]
binding = "MY_DB"
database_name = "my-db"

[[durable_objects.bindings]]
name = "COUNTER"
class_name = "Counter"

[triggers]
crons = ["*/5 * * * *"]

Testing

import { describe, it, expect } from 'vitest';
import { createTestCloud, kv } from '@cloudmock/core/testing';

describe('My Worker', () => {
  let cloud;

  beforeEach(async () => {
    cloud = await createTestCloud({
      plugins: [kv('CACHE')]
    });
  });

  afterEach(async () => {
    await cloud.reset();
    await cloud.close();
  });

  it('should cache data', async () => {
    await cloud.env.CACHE.put('key', 'value');
    expect(await cloud.env.CACHE.get('key')).toBe('value');
  });
});

Dashboard

The embedded dashboard provides real-time visibility into your CloudMock instance:

• Overview - Live request stream, metrics, latency
• KV Browser - Browse and edit KV data
• R2 Browser - Upload/download objects
• D1 Studio - SQL editor with results
• DO Inspector - View instances and storage
• Queue Inspector - Manage queues
• AI Playground - Test AI models
• Logs - Real-time log stream
• Metrics - Performance graphs
• Settings - Configure simulation

Access at: http://localhost:8787/__dashboard

Simulation

Latency Simulation

const cloud = createCloud({
  simulation: {
    latency: {
      enabled: true,
      global: { min: 5, max: 50 },
      perService: {
        kv: { min: 1, max: 10 },
        r2: { min: 10, max: 100 }
      }
    }
  }
});

Error Injection

const cloud = createCloud({
  simulation: {
    errors: {
      enabled: true,
      rate: 0.01, // 1% of requests fail
      types: ['timeout', 'connection_reset', 'internal_error']
    }
  }
});

Limits Enforcement

const cloud = createCloud({
  simulation: {
    limits: {
      enforce: true,
      kv: {
        keyMaxSize: 512,
        valueMaxSize: 25 * 1024 * 1024
      }
    }
  }
});

Documentation

• Full Documentation: https://cloudmock.oxog.dev
• API Reference: https://cloudmock.oxog.dev/docs/api
• Examples: https://cloudmock.oxog.dev/examples

Comparison

Feature	CloudMock	Miniflare	Localflare
Zero Runtime Dependencies	✅	❌	❌
Offline Dashboard	✅	❌	❌
All CF Services	✅	Partial	Partial
No Wrangler Required	✅	❌	❌
Embedded Dashboard	✅	❌	❌
LLM-Native Design	✅	❌	❌

Project Status

Version: 0.1.0 (Beta)

Last Updated: 2026-01-10

This project is in active development. See docs/TASKS.md for implementation progress.

License

MIT © Ersin Koç

Links

• GitHub: https://github.com/ersinkoc/cloudmock
• NPM: https://www.npmjs.com/package/@cloudmock/core
• Website: https://cloudmock.oxog.dev