How OpenCut API Uses Elysia with CloudflareAdapter for Serverless Deployment

OpenCut's API leverages the Elysia framework's CloudflareAdapter to compile TypeScript routes into a Cloudflare Workers-compatible bundle, enabling serverless deployment without runtime translation layers.

The OpenCut backend API demonstrates a modern serverless architecture by combining the Elysia TypeScript framework with Cloudflare's edge computing platform. By utilizing the CloudflareAdapter, the application transforms standard Elysia route definitions into a format executable by Cloudflare Workers. This integration lives primarily in apps/api/src/index.ts within the OpenCut-app/OpenCut repository and eliminates the need for separate Node.js servers while maintaining full type safety and validation.

Cloudflare Adapter Integration

The bridge between Elysia's abstract request handling and Cloudflare's serverless runtime centers on the adapter pattern implemented in the main entry file.

Adapter Registration in apps/api/src/index.ts

The core configuration occurs when instantiating the Elysia application. Instead of using the default Node-HTTP implementation, the code explicitly passes CloudflareAdapter to the constructor:

import { Elysia, t } from "elysia";
import { CloudflareAdapter } from "elysia/adapter/cloudflare-worker";

export default new Elysia({ adapter: CloudflareAdapter })
  .post(
    "/echo",
    ({ body }) => body,
    {
      body: t.Object({ message: t.String() }),
    }
  )
  .compile();

This registration tells Elysia to translate all subsequent route definitions into the Cloudflare Workers runtime API.

Route Definitions and Schema Validation

Standard Elysia methods like .get() and .post() define endpoints that execute identically across platforms. The t helper from Elysia provides runtime type validation without additional middleware. For example, adding a health check endpoint requires only:

export default new Elysia({ adapter: CloudflareAdapter })
  .get("/health", () => ({
    healthy: true,
    timestamp: new Date().toISOString(),
  }))
  .compile();

The schema validation ensures that requests to /echo must contain a message field of type string, returning automatic 400 responses for malformed payloads before the handler executes.

Ahead-of-Time Compilation Requirements

The .compile() method triggers AoT (Ahead-of-Time) compilation, which is mandatory for Cloudflare Workers deployment according to the OpenCut source code. This process bundles the entire application—including routes, validation logic, and the adapter itself—into a single script that Cloudflare executes directly. This compilation step eliminates runtime translation overhead, producing the final worker script without additional boilerplate.

Production Deployment Workflow

Deploying the compiled API to Cloudflare Workers follows a two-stage process. First, the build step bundles the TypeScript source using Vite or esbuild as configured in the project's build scripts. Then, the wrangler CLI uploads the resulting artifact:

# Build the worker bundle

npm run build

# Deploy to Cloudflare Workers

wrangler publish ./dist/worker.js

The wrangler.toml configuration file in the repository root specifies account IDs, script names, and environment variables required for the deployment.

Key Implementation Files

• apps/api/src/index.ts: Contains the main Elysia server definition with Cloudflare adapter registration and route declarations.
• package.json: Declares dependencies including elysia and the elysia/adapter/cloudflare-worker subpath export.
• wrangler.toml: Configures Cloudflare Workers runtime settings and deployment parameters.

Summary

• Adapter Pattern: OpenCut uses new Elysia({ adapter: CloudflareAdapter }) to replace the default Node.js HTTP server with Cloudflare Workers compatibility.
• Type Safety: Runtime validation via Elysia's t object ensures request integrity without external libraries.
• AoT Compilation: The .compile() method produces a single deployable script optimized for edge execution.
• Zero Translation Layer: The compiled output runs directly on Cloudflare Workers, matching the runtime API without middleware overhead.

Frequently Asked Questions

What is the CloudflareAdapter in Elysia?

The CloudflareAdapter is an official Elysia adapter exported from elysia/adapter/cloudflare-worker that translates the framework's abstract request/response handling into the Cloudflare Workers runtime API. It allows Elysia applications to run on Cloudflare's serverless platform without modification to route logic or validation schemas.

Why does OpenCut use Ahead-of-Time compilation?

OpenCut calls .compile() to trigger AoT bundling, which is required by Cloudflare Workers to receive a single executable script. This process inlines all routes, validation, and adapter logic into one file, eliminating runtime module resolution and improving cold-start performance on the edge network.

How does request validation work in this serverless setup?

Request validation uses Elysia's built-in t schema validator. When defining routes like /echo, the body: t.Object({ message: t.String() }) specification automatically validates incoming JSON against the schema, returning structured error responses before the handler executes. This occurs within the compiled worker script without requiring separate validation middleware.

Can I use standard Node.js libraries with this configuration?

No, Cloudflare Workers run on the Winter V8 runtime rather than Node.js. The CloudflareAdapter ensures Elysia avoids Node-specific APIs, and code in apps/api/src/index.ts must use Web Standard APIs (Request, Response, Fetch) compatible with Workers. The AoT compilation step fails if Node.js built-ins are detected in the dependency graph.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}