Vercel to Cloudflare Worker Migration

Migrate Next.js projects from Vercel to Cloudflare Workers with Supabase/Hyperdrive support. Use when user wants to move a Next.js app off Vercel to reduce c...

Security Scan

The skill's purpose and included analysis script match the migration goal, but the runtime instructions reference a missing migration script (scripts/migrate.py) and the SKILL.md gives broad advice that could cause users to run edits that require sensitive DB credentials — the package appears incomplete and therefore potentially unsafe to run as-is.

Purpose & Capability

Name, description, and the included analysis script (scripts/analyze_project.py) and reference docs consistently target migrating Next.js/Supabase projects from Vercel to Cloudflare Workers with Hyperdrive. The guidance to install @opennextjs/cloudflare and edit next.config/wrangler.toml is appropriate for the stated task.

Instruction Scope

SKILL.md tells the user to run a migration script 'scripts/migrate.py' which is not present in the bundle — this is an incoherence that could lead users to fetch or run unknown external code. The provided analyze_project.py reads the project tree and source files (which is expected) but could expose local secrets if the user runs it in a repo containing credentials; the skill does not explicitly warn about sensitive files. Overall the runtime instructions are specific but incomplete.

Install Mechanism

No install spec is provided (instruction-only plus local helper script). No remote downloads or installers are requested by the package itself, which reduces supply-chain risk. The only external package the instructions ask to install is @opennextjs/cloudflare via npm — expected for this migration.

Credentials

The skill declares no required environment variables or credentials (consistent with being an instruction-only tool). The migration guidance explains where database connection strings and Hyperdrive bindings belong, but it does not request the skill be given secrets. Users will need to supply DB/Hyperdrive credentials for real migrations — those are appropriately described as local configuration rather than required envs for the skill itself.

Persistence & Privilege

The skill does not request persistent presence (always: false) and has no install actions. It does not modify other skills or global configuration. Autonomous invocation is allowed (platform default) but does not combine with other high-risk indicators here.

What to consider before installing

This package mostly looks like a legitimate migration helper, but it's incomplete: SKILL.md tells you to run scripts/migrate.py yet that file is not included. Before running anything, do not fetch or execute external code to compensate for the missing file. Review scripts/analyze_project.py locally (it only reads files and prints a report) and run it in a safe environment (not on production servers or on a repo with unredacted secrets). If you plan to perform the migration: (1) ask the publisher for the missing migrate.py or a full install script and review it before running, (2) keep DB credentials and Hyperdrive IDs local and never paste them into third-party channels, (3) install @opennextjs/cloudflare only from npm and verify package integrity, and (4) back up your project and test the migration in a staging environment. If you want higher assurance, request the full source for migrate.py and have it reviewed before execution.

Migrate a Next.js + Supabase project from Vercel to Cloudflare Workers with Hyperdrive connection pooling.

Quick Start

1. Run the analysis script to scan the project:

   python3 scripts/analyze_project.py <project-path>
   

2. Review the migration report
3. Run the migration script:

   python3 scripts/migrate.py <project-path>
   

4. Configure Hyperdrive: see references/hyperdrive-setup.md

Core Migration Steps

1. Install @opennextjs/cloudflare adapter

npm install @opennextjs/cloudflare

Update next.config.js or next.config.ts if needed.

2. Rewrite environment variable access

All process.env.XXX for Cloudflare bindings (Hyperdrive, KV, D1, etc.) must use getCloudflareContext():

// BEFORE (Vercel/Node.js)
const url = process.env.DATABASE_URL;

// AFTER (Cloudflare Worker)
import { getCloudflareContext } from '@opennextjs/cloudflare';

function getConnectionInfo() {
  const env = getCloudflareContext().env;
  const hyperdrive = env.HYPERDRIVE as { connectionString?: string } | undefined;
  if (hyperdrive?.connectionString) {
    return { connectionString: hyperdrive.connectionString, source: 'hyperdrive' };
  }
  // Fallback for local dev
  const local = env.CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE;
  if (local) {
    return { connectionString: local, source: 'hyperdrive-local' };
  }
  throw new Error('HYPERDRIVE is not configured');
}

3. Refactor global DB singleton to per-request pattern

// BEFORE: Global singleton
import { drizzle } from 'drizzle-orm/postgres-js';
import postgres from 'postgres';
const client = postgres(process.env.DATABASE_URL!);
export const db = drizzle(client);

// AFTER: Per-request with React cache
import { cache } from 'react';

export const getDb = cache(() => {
  const { connectionString, source } = getConnectionInfo();
  return createDatabase({
    connectionString,
    enableSSL: source === 'hyperdrive' ? false : 'require',
  });
});

Then replace all import { db } with import { getDb } and add const db = getDb() at the start of each function.

4. Configure wrangler.toml

name = "my-app"
main = ".open-next/worker.js"
compatibility_date = "2024-09-23"
compatibility_flags = ["nodejs_compat"]

[[hyperdrive]]
binding = "HYPERDRIVE"
id = "<your-hyperdrive-id>"

Critical Pitfalls

1. Hyperdrive must connect to Supabase Direct Connection (port 5432), NOT the Pooler (port 6543). Hyperdrive IS a connection pooler — connecting pooler-to-pooler causes errors.

2. SSL must be disabled for Hyperdrive connections — Worker ↔ Hyperdrive is internal network. Only enable SSL for direct database connections (local dev, build stage).

3. Cannot initialize DB at module top level — getCloudflareContext() only works during request handling, not at module load time.

4. Supabase Free Tier direct connection is IPv6 only — local dev may fail if your network doesn't support IPv6. Use the Pooler URL (port 6543) for local development.

Detailed References

• Hyperdrive setup & Supabase config: Read references/hyperdrive-setup.md
• Environment variable patterns: Read references/env-patterns.md