Runtime Adapters

CruzJS is provider-agnostic. While Cloudflare Workers/Pages is the default target, you can deploy to AWS, Google Cloud, Azure, DigitalOcean, or self-hosted Docker using runtime adapters.

How It Works

Each adapter implements the RuntimeAdapter interface, providing platform-specific implementations for database, cache, queue, AI, and storage bindings.

// server.cloudflare.ts — Cloudflare (default)
import { CloudflareAdapter } from '@cruzjs/adapter-cloudflare';

export default createCruzApp({
  schema,
  modules: [/* your modules */],
  adapter: new CloudflareAdapter(),
  pages: () => import('virtual:react-router/server-build'),
});

// server.ts — Docker / self-hosted
import { DockerAdapter } from '@cruzjs/adapter-docker';

export default createCruzApp({
  schema,
  modules: [/* your modules */],
  adapter: new DockerAdapter(),
  pages: () => import('virtual:react-router/server-build'),
});

Available Adapters

Package	Adapter	Runtime Type	Use Case
@cruzjs/adapter-cloudflare	CloudflareAdapter	Edge	Cloudflare Workers/Pages
@cruzjs/adapter-aws	AWSLambdaAdapter	Serverless	AWS Lambda + API Gateway
@cruzjs/adapter-aws	AWSFargateAdapter	Container	AWS ECS Fargate
@cruzjs/adapter-gcp	GCPCloudRunAdapter	Container	Google Cloud Run
@cruzjs/adapter-gcp	GCPCloudFunctionsAdapter	Serverless	Google Cloud Functions
@cruzjs/adapter-azure	AzureFunctionsAdapter	Serverless	Azure Functions
@cruzjs/adapter-azure	AzureContainerAppsAdapter	Container	Azure Container Apps
@cruzjs/adapter-digitalocean	DigitalOceanAppPlatformAdapter	Container	DO App Platform
@cruzjs/adapter-docker	DockerAdapter	Container	Docker, Dokploy, Coolify, K8s

Runtime Types

• Edge — Runs at the edge (Cloudflare Workers). Lowest latency, V8 isolate runtime.
• Serverless — Scale-to-zero functions (Lambda, Cloud Functions). waitUntil() must be flushed before response returns.
• Container — Long-running processes (Fargate, Cloud Run, Docker). waitUntil() is fire-and-forget.

RuntimeAdapter Interface

All adapters implement this interface:

interface RuntimeAdapter {
  readonly name: string;
  readonly type: 'edge' | 'serverless' | 'container';

  init(context: unknown): Promise<void>;
  getDatabase(): unknown;
  getCache(namespace?: string): CacheBinding;
  getQueue<T>(name: string): QueueBinding<T>;
  getLocalQueue<T>(name: string): LocalQueueLike<T> | null;
  getAI(): AIBinding | null;
  getBinding<T>(name: string): T | null;
  getStorageBucket(): unknown | null;
  waitUntil(promise: Promise<unknown>): void;
  get env(): Record<string, string | undefined>;
  get diagnostics(): Record<string, unknown>;
  clear(): void;
}

Binding Interfaces

CacheBinding

Redis-like cache API with TTL support, key namespacing, and atomic counters.

interface CacheBinding {
  get<T>(key: string): Promise<T | null>;
  set(key: string, value: string | number | object, ttlSeconds?: number): Promise<boolean>;
  delete(key: string): Promise<boolean>;
  exists(key: string): Promise<boolean>;
  keys(pattern: string): Promise<string[]>;
  clear(): Promise<number>;
  increment(key: string, by?: number): Promise<number>;
  decrement(key: string, by?: number): Promise<number>;
}

QueueBinding

Message dispatch for background job processing.

interface QueueBinding<T = unknown> {
  send(message: T): Promise<void>;
  sendBatch(messages: { body: T }[]): Promise<void>;
}

AIBinding

Provider-agnostic AI operations for chat, embeddings, and structured extraction.

interface AIBinding {
  chat(options: AIChatOptions): Promise<string | null>;
  embed(texts: string[], model?: string): Promise<number[][] | null>;
  describeImage(image: ArrayBuffer, prompt?: string): Promise<string | null>;
  analyzeSentiment(text: string): Promise<AISentimentResult | null>;
  extractStructured<T>(options: AIExtractOptions<T>): Promise<T | null>;
}

Optional Adapter Bindings

Beyond the core bindings, the RuntimeAdapter interface exposes optional methods for advanced features. These return null when the adapter does not support them, and the corresponding modules fall back to in-memory or no-op implementations.

interface RuntimeAdapter {
  // ... core methods above ...

  // Optional bindings
  getRateLimiter(): RateLimitAdapter | null;
  getScheduler(): SchedulerAdapter | null;
  getBroadcast(): BroadcastAdapter | null;
  getSSEBackend(): SSEBackend | null;
  getSearch(): SearchAdapter | null;
  getSessionAdapter(): SessionAdapter | null;
  getLogger(): LogAdapterBinding | null;
}

Method	Returns	Purpose
getRateLimiter()	RateLimitAdapter	Distributed rate limiting
getScheduler()	SchedulerAdapter	Distributed lock for scheduled tasks
getBroadcast()	BroadcastAdapter	Presence tracking for real-time channels
getSSEBackend()	SSEBackend	Server-Sent Events message delivery
getSearch()	SearchAdapter	Full-text search indexing and querying
getSessionAdapter()	SessionAdapter	Session storage and management
getLogger()	LogAdapterBinding	Structured logging

Binding Support Matrix

Binding	Cloudflare	AWS Lambda	AWS Fargate	GCP Cloud Run	GCP Functions	Azure Functions	Azure Containers	DigitalOcean	Docker
Database	D1	DynamoDB / RDS	RDS	Cloud SQL	Cloud SQL	Cosmos DB	Cosmos DB	Managed DB	PostgreSQL
Cache	KV	ElastiCache	ElastiCache	Memorystore	Memorystore	Redis Cache	Redis Cache	Redis	Redis
Queue	Queues	SQS	SQS	Pub/Sub	Pub/Sub	Service Bus	Service Bus	—	BullMQ
AI	Workers AI	Bedrock	Bedrock	Vertex AI	Vertex AI	OpenAI	OpenAI	—	Ollama
Storage	R2	S3	S3	GCS	GCS	Blob Storage	Blob Storage	Spaces	Local/S3
Rate Limiter	KV	ElastiCache	ElastiCache	Memorystore	Memorystore	Redis Cache	Redis Cache	Redis	Redis
Scheduler	KV	DynamoDB	Redis	Memorystore	Memorystore	Redis Cache	Redis Cache	Redis	Redis
Broadcast	KV	ElastiCache	ElastiCache	Memorystore	Memorystore	Redis Cache	Redis Cache	Redis	Redis
SSE Backend	KV	—	Redis	Redis	—	—	Redis	Redis	Redis
Search	FTS5 (D1)	OpenSearch	OpenSearch	—	—	—	—	—	OpenSearch
Sessions	KV	DynamoDB	Redis	Memorystore	Memorystore	Redis Cache	Redis Cache	Redis	Redis
Logger	Console/Logpush	CloudWatch	CloudWatch	Cloud Logging	Cloud Logging	App Insights	App Insights	—	stdout

Backward Compatibility

The adapter field is optional in createCruzApp(). Without it, the framework uses CloudflareContext directly (existing behavior). When provided, the adapter is initialized alongside CloudflareContext, so all existing services continue to work unchanged.