Vercel to Cloudflare Worker Migration

# Vercel to Cloudflare Worker Migration

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:
2. ```bash
3. python3 scripts/analyze_project.py <project-path>
4. ```
5. Review the migration report
6. Run the migration script:
7. ```bash
8. python3 scripts/migrate.py <project-path>
9. ```
10. Configure Hyperdrive: see references/hyperdrive-setup.md

Core Migration Steps

1. Install @opennextjs/cloudflare adapter

```bash 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()`:

```typescript // 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

```typescript // 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

```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.

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

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

1. 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