Cloudflare Workers & OpenNext Deployment

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• package.json
• open-next.config.ts
• lib/db/schema.ts
• app/api/admin/switches/route.ts
• test/browser-run.test.ts

Vantage deploys as a Cloudflare Worker using the OpenNext adapter for Next.js. This architecture allows the platform to run server-side logic, API routes, and scheduled collector tasks within Cloudflare's edge environment while maintaining compatibility with Next.js App Router features.

The deployment relies on @opennextjs/cloudflare to transform the Next.js build output into a format compatible with the Workers runtime. The system enables nodejs_compat to support Node.js modules like node:crypto and Buffer directly within the Worker environment.

Sources: README.md:1-15, README.md:92-98, package.json:44-57

Build and Deployment Workflow

The build process uses opennextjs-cloudflare to bundle the application. Developers trigger the build and deployment through defined pnpm scripts.

Deployment Pipeline

1. Build: pnpm cf:build runs opennextjs-cloudflare build.
2. Preview: pnpm cf:preview builds the project and launches a local Worker environment for testing.
3. Deploy: pnpm deploy executes the build and then uploads the bundle to Cloudflare.

The following diagram illustrates the deployment flow:

The diagram shows the transformation from source code to a production-ready Cloudflare Worker bundle.

Sources: package.json:17-21, README.md:94-100

Key Deployment Scripts

Script	Command	Description
cf:build	opennextjs-cloudflare build	Generates the Worker bundle in .open-next.
cf:preview	opennextjs-cloudflare build && opennextjs-cloudflare preview	Builds and runs the project in a local Worker runtime.
deploy	opennextjs-cloudflare build && opennextjs-cloudflare deploy	Automates the build and deployment to Cloudflare.
cf:typegen	wrangler types --env-interface CloudflareEnv	Generates TypeScript bindings for Cloudflare resources.

Sources: package.json:17-21

Environment Configuration

Deployment requires specific environment secrets and configuration flags. Vantage uses wrangler.jsonc for resource definition and open-next.config.ts for adapter-specific settings.

Adapter Configuration

The open-next.config.ts file defines the Cloudflare configuration. It omits the incremental-cache override because every Vantage surface is dynamic. Pages read workspace data from sessions on every request, necessitating a force-dynamic behavior across the application.

Sources: open-next.config.ts:1-11

Required Secrets

You must configure the following secrets via wrangler secret put before a successful production run:

• CRON_SECRET: A random string for authorizing scheduled tasks.
• NEON_AUTH_COOKIE_SECRET: Used for session encryption.
• DATABASE_URL: The Neon Postgres connection string.

Sources: README.md:105-110

Scheduled Tasks and Cron Infrastructure

Cloudflare Workers trigger the Vantage collector pipeline every 3 hours. Because the OpenNext adapter primarily emits a fetch handler, Vantage uses a custom entrypoint (worker-entry.mjs) to handle scheduled events.

The sequence diagram details how external cron triggers reach internal API routes using service bindings and authorization headers.

Sources: README.md:131-137, open-next.config.ts:4-6

Security and Runtime Constraints

Cross-Origin Defense

Privileged routes, such as the source switch admin API, implement defense-in-depth against cross-site requests. The system checks Sec-Fetch-Site and Origin headers to ensure requests originate from the same origin before allowing state changes.

Sources: app/api/admin/switches/route.ts:11-25

Runtime Limits

• Bundle Size: Cloudflare Free tier limits scripts to 3 MB; the Paid tier allows up to 10 MB. CI processes measure .open-next/worker.js and fail if these limits are exceeded.
• Platform Guard: The browser runner implements an SSRF (Server-Side Request Forgery) guard to block requests to localhosts, internal IPs, and specific denylisted platforms like LinkedIn or Facebook.

Sources: README.md:139-140, test/browser-run.test.ts:51-78

Database Migrations

Database migrations are a manual process and are not chained into the pnpm deploy command. You must apply migrations to the target database before deploying code changes that rely on a new schema.

DATABASE_URL="postgresql://…" pnpm db:migrate

Sources: README.md:115-120, package.json:15

Vantage's Cloudflare deployment strategy prioritizes dynamic responsiveness and edge execution, leveraging OpenNext to bridge standard Next.js development with the distributed Workers runtime.