How OpenSEO Leverages Cloudflare Workers for Serverless Architecture

OpenSEO runs its entire backend as a Cloudflare Worker, executing at the edge with TanStack Start routing, R2 caching, and Cloudflare Access authentication for a fully serverless, zero-trust SEO platform.

OpenSEO is an open-source SEO platform built on a fully serverless architecture using Cloudflare Workers. The codebase in the every-app/open-seo repository eliminates traditional server management by running all backend logic at Cloudflare's edge locations. This architecture combines TanStack Start for server-side rendering, R2 object storage for caching, and Cloudflare Access for zero-trust security.

Worker Entrypoint and Request Routing

The application exposes a single Worker entrypoint defined in src/server.ts that extends Cloudflare.WorkerEntrypoint. This file compiles into the executable script deployed to Cloudflare's edge network.

The entrypoint initializes a TanStack Start request handler that routes incoming HTTP requests to the appropriate server functions. Unlike traditional Node.js servers, this handler operates within Cloudflare's V8 isolates, providing instant cold starts and global distribution.

// src/server.ts – Worker entrypoint (simplified)
import { createRequestHandler } from "@tanstack/start/server";
export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
    // TanStack Start provides a request handler that works in a Worker
    const handler = createRequestHandler({ /* routes */ });
    return handler(request, env, ctx);
  },
} as ExportedHandler<Env>;

The TypeScript definitions in worker-configuration.d.ts declare the environment bindings, ensuring type safety when accessing KV namespaces, R2 buckets, and secrets within the Worker runtime.

Deployment Configuration and Infrastructure as Code

OpenSEO uses Wrangler as its deployment toolchain, configured via wrangler.jsonc. This configuration file declaratively defines the Worker name, KV namespaces, R2 buckets, and secret bindings required for operation.

The repository includes a Deploy to Cloudflare button that provisions the entire stack via Wrangler. When triggered, it automatically creates the Worker, binds the OPEN_SEO_R2 bucket, configures KV namespaces, and injects secrets like DATAFORSEO_API_KEY without manual dashboard configuration.

Key bindings defined in wrangler.jsonc include:

• KV namespaces for session storage and configuration
• R2 buckets for caching expensive API responses
• Secret variables such as DATAFORSEO_API_KEY and POLICY_AUD

Edge Caching with R2 and KV

To minimize latency and reduce costs for external API calls, OpenSEO implements a caching layer using Cloudflare R2. API responses from DataForSEO are stored in the dataforseo-cache/ bucket with configurable TTLs.

A lifecycle rule (configured via wrangler r2 bucket lifecycle) automatically expires cached objects after a specified number of days, preventing unbounded storage growth. This pattern reduces redundant API calls while maintaining fresh data.

// Caching a DataForSEO response in R2
export async function fetchKeywordData(keyword: string, env: Env) {
  const cacheKey = `dataforseo-cache/${keyword}`;
  const cached = await env.OPEN_SEO_R2.get(cacheKey);
  if (cached) return JSON.parse(cached);

  const fresh = await fetchFromDataForSEO(keyword, env);
  await env.OPEN_SEO_R2.put(cacheKey, JSON.stringify(fresh), {
    expirationTtl: 60 * 60 * 24, // 1 day
  });
  return fresh;
}

Accessing bound secrets within the Worker uses the standard environment object pattern:

// Accessing a bound secret (DataForSEO API key)
const apiKey = env.DATAFORSEO_API_KEY;   // injected via wrangler secrets
const resp = await fetch(`https://api.dataforseo.com/v3/keyword_data?key=${apiKey}`, { … });

Zero-Trust Authentication and MCP Integration

OpenSEO enforces Zero-Trust security through Cloudflare Access, protecting the Worker URL from unauthorized requests. Secrets including POLICY_AUD (Policy Audience) and TEAM_DOMAIN are stored in Cloudflare's Variables & Secrets dashboard and injected into the Worker environment.

For MCP (Managed Cloud Platform) clients, the transport layer resolves Cloudflare Access JWTs via resolveCloudflareAccessContext in src/server/mcp/transport.ts. This allows CLI and desktop agents to authenticate using Managed OAuth rather than exposing raw API keys, enabling secure team collaboration.

// Verifying Cloudflare Access JWT (used by MCP)
import { verifyJwt } from "some-jwt-lib";
export async function resolveCloudflareAccessContext(headers: Headers) {
  const token = headers.get("CF-Access-Token");
  if (!token) throw new Error("Missing Cloudflare Access token");
  const payload = await verifyJwt(token, env.POLICY_AUD);
  return payload;
}

Build Optimization and Developer Experience

The build pipeline uses a custom Vite plugin (vite-plugin-lean-worker-bundle.ts) to produce optimized Worker bundles. This plugin strips unnecessary code and ensures compatibility with Cloudflare's JavaScript runtime, reducing bundle size and improving cold-start performance.

For local development, setting CLOUDFLARE_INCLUDE_PROCESS_ENV=true exposes Worker bindings as standard process environment variables. This allows the Vite dev server to mirror the Cloudflare runtime without requiring actual deployment during development.

Summary

• OpenSEO deploys as a single Cloudflare Worker defined in src/server.ts, using TanStack Start for request routing at the edge.
• Infrastructure configuration is managed declaratively through wrangler.jsonc, supporting one-click deployment with automatic secret and storage binding.
• R2 object storage caches expensive DataForSEO API responses in the dataforseo-cache/ bucket with automatic lifecycle expiration.
• Cloudflare Access provides zero-trust authentication, with JWT verification handled in src/server/mcp/transport.ts for secure MCP client connections.
• Build optimization via vite-plugin-lean-worker-bundle.ts ensures minimal bundle sizes compatible with the Cloudflare Workers runtime.

Frequently Asked Questions

What is the entry point for the OpenSEO Cloudflare Worker?

The entry point is src/server.ts, which exports a handler implementing Cloudflare.WorkerEntrypoint. This file creates a TanStack Start request handler that processes all incoming requests within the Cloudflare Workers runtime, routing them to the appropriate server functions based on the URL path.

How does OpenSEO cache external API responses?

OpenSEO caches DataForSEO API responses in a Cloudflare R2 bucket named dataforseo-cache/. The Worker checks this cache before making external API calls, storing fresh results with a configurable TTL (typically 24 hours). A lifecycle rule automatically deletes expired objects to manage storage costs.

What authentication method does OpenSEO use for MCP clients?

MCP clients authenticate via Cloudflare Access JWTs. The Worker validates these tokens using the POLICY_AUD secret against the CF-Access-Token header. This zero-trust approach, implemented in src/server/mcp/transport.ts, allows team members to use Managed OAuth instead of sharing static API keys.

How do I deploy OpenSEO to Cloudflare Workers?

Deploy by clicking the Deploy to Cloudflare button in the repository, which uses Wrangler to provision the Worker. Alternatively, run wrangler deploy locally after configuring wrangler.jsonc with your KV namespaces, R2 bucket (OPEN_SEO_R2), and secrets (DATAFORSEO_API_KEY, POLICY_AUD). The deployment automatically binds all required resources.

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