secondsky/claude-skills / plugins/cloudflare-nextjs/skills/cloudflare-nextjs
cloudflare-nextjs
VerifiedDeploy Next.js to Cloudflare Workers via the OpenNext adapter (@opennextjs/cloudflare). Use for SSR/ISR/SSG/App or Pages Router, getCloudflareContext, bindings (D1/R2/KV/AI/Hyperdrive), caching tiers, skew protection, multi-worker, custom worker, env vars, or worker size/runtime/keep_names/FinalizationRegistry/connection-scoping errors.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 20.7 KB |
| assets/workflow-diagram.md | markdown | 15.8 KB |
| references/advanced.md | markdown | 10.0 KB |
| references/bindings-and-services.md | markdown | 6.7 KB |
| references/caching.md | markdown | 6.4 KB |
| references/database-client-example.ts | script | 3.8 KB |
| references/dev-deploy-and-env.md | markdown | 3.7 KB |
| references/error-catalog-extended.md | markdown | 7.5 KB |
| references/feature-support.md | markdown | 13.2 KB |
| references/known-issues.md | markdown | 2.1 KB |
| references/open-next.config.ts | script | 7.3 KB |
| references/package.json | manifest | 871 B |
| references/troubleshooting.md | markdown | 4.3 KB |
| references/wrangler.jsonc | other | 6.1 KB |
| scripts/analyze-bundle.shexecutable | script | 3.9 KB |
| scripts/setup-existing-project.shexecutable | script | 3.1 KB |
| scripts/setup-new-project.shexecutable | script | 1.1 KB |
references/bindings-and-services.md
View on GitHub# Bindings & Service Integration
How to access Cloudflare bindings from Next.js routes, and how to wire common ORMs/SDKs.
## `getCloudflareContext()` — the only correct way
**Do not use `process.env` for bindings.** Import `getCloudflareContext` from `@opennextjs/cloudflare`.
```ts
import { getCloudflareContext } from "@opennextjs/cloudflare";
export async function GET() {
const { env, cf, ctx } = getCloudflareContext();
await env.MY_KV.put("foo", "bar");
return new Response(await env.MY_KV.get("foo"));
}
```
- `env` — bindings (D1, R2, KV, AI, Hyperdrive, DOs, service bindings, vars, secrets).
- `cf` — request properties (city, country, colo, TLS version, …).
- `ctx` — Workers lifecycle (`waitUntil`, `passThroughOnException`).
### Static routes (ISR/SSG) — async mode required
```ts
const { env } = await getCloudflareContext({ async: true });
```
**Caution:** secrets (`.dev.vars`) and local-dev binding values are used during static generation. Do not leak them into static HTML.
### TypeScript types
```bash
npx wrangler types --env-interface CloudflareEnv
# or, per the get-started template:
npx wrangler types --env-interface CloudflareEnv cloudflare-env.d.ts
```
Generates `worker-configuration.d.ts` (or `cloudflare-env.d.ts`). Re-run after any binding change.
### Remote bindings (local dev → real resources)
Stabilized in **Wrangler 4.36.0**. On older wrangler, enable via `initOpenNextCloudflareForDev({ experimental: { remoteBindings: true } })` and use the `experimental_remote` (not `remote`) key on binding options. Remote bindings are **also used during build**.
## Database integration
**Core rule:** create a new client **per request**. Global clients use connection pooling that is forbidden in Workers and causes `Error: Cannot perform I/O on behalf of a different request`.
Wrap with `cache()` from `react` to reuse the client within a single request (only affects server components).
### Drizzle + Cloudflare D1
```ts
import { getCloudflareContext } from "@opennextjs/cloudflare";
import { drizzle } from "drizzle-orm/d1";
import { cache } from "react";
import * as schema from "./schema/d1";
export const getDb = cache(() => {
const { env } = getCloudflareContext();
return drizzle(env.MY_D1, { schema });
});
// For static routes (ISR/SSG):
export const getDbAsync = cache(async () => {
const { env } = await getCloudflareContext({ async: true });
return drizzle(env.MY_D1, { schema });
});
```
### Drizzle + Cloudflare Hyperdrive (PostgreSQL)
```ts
import { getCloudflareContext } from "@opennextjs/cloudflare";
import { drizzle } from "drizzle-orm/node-postgres";
import { cache } from "react";
import * as schema from "./schema/pg";
import { Pool } from "pg";
export const getDb = cache(() => {
const { env } = getCloudflareContext();
const pool = new Pool({
connectionString: env.HYPERDRIVE.connectionString,
maxUses: 1, // do not reuse connections across requests
});
return drizzle({ client: pool, schema });
});
export const getDbAsync = cache(async () => {
const { env } = await getCloudflareContext({ async: true });
const pool = new Pool({ connectionString: env.HYPERDRIVE.connectionString, maxUses: 1 });
return drizzle({ client: pool, schema });
});
```
> ⚠️ Known issue: Hyperdrive + `pg` / `@prisma/adapter-pg` bundling failure — see #1322 / #1214.
### Drizzle + standard PostgreSQL (no Hyperdrive)
```ts
import { drizzle } from "drizzle-orm/node-postgres";
import { cache } from "react";
import { Pool } from "pg";
import * as schema from "./schema/pg";
export const getDb = cache(() => {
const pool = new Pool({
connectionString: process.env.PG_URL,
maxUses: 1, // critical
});
return drizzle({ client: pool, schema });
});
```
### Prisma + Cloudflare D1
`schema.prisma`:
```prisma
generator client {
provider = "prisma-client-js"
previewFeatures = ["driverAdapters"]
}
```
> ⚠️ Do **not** specify an output directory in `schema.prisma` — the generated client must be patched by OpenNext to work on Workers; specifying output prevents patching.
`next.config.ts`:
```ts
const nextConfig: NextConfig = {
serverExternalPackages: ["@prisma/client", ".prisma/client"],
};
```
`lib/db.ts`:
```ts
import { getCloudflareContext } from "@opennextjs/cloudflare";
import { cache } from "react";
import { PrismaClient } from "@prisma/client";
import { PrismaD1 } from "@prisma/adapter-d1";
export const getDb = cache(() => {
const { env } = getCloudflareContext();
const adapter = new PrismaD1(env.MY_D1);
return new PrismaClient({ adapter });
});
export const getDbAsync = async () => {
const { env } = await getCloudflareContext({ async: true });
const adapter = new PrismaD1(env.MY_D1);
return new PrismaClient({ adapter });
};
```
### Prisma + PostgreSQL (Hyperdrive)
```ts
import { getCloudflareContext } from "@opennextjs/cloudflare";
import { cache } from "react";
import { PrismaClient } from "@prisma/client";
import { PrismaPg } from "@prisma/adapter-pg";
export const getDb = cache(() => {
const { env } = getCloudflareContext();
const adapter = new PrismaPg({ connectionString: env.HYPERDRIVE.connectionString, maxUses: 1 });
return new PrismaClient({ adapter });
});
export const getDbAsync = async () => {
const { env } = await getCloudflareContext({ async: true });
const adapter = new PrismaPg({ connectionString: env.HYPERDRIVE.connectionString, maxUses: 1 });
return new PrismaClient({ adapter });
};
```
### Prisma + plain PostgreSQL
```ts
import { cache } from "react";
import { PrismaClient } from "@prisma/client";
import { PrismaPg } from "@prisma/adapter-pg";
export const getDb = cache(() => {
const adapter = new PrismaPg({ connectionString: process.env.PG_URL ?? "", maxUses: 1 });
return new PrismaClient({ adapter });
});
```
## Other bindings
### R2
```ts
const { env } = getCloudflareContext();
const obj = await env.MY_BUCKET.get("file.txt");
return new Response(obj?.body);
```
### KV
```ts
const { env } = getCloudflareContext();
await env.MY_KV.put("key", "value");
const v = await env.MY_KV.get("key");
```
### Workers AI
```ts
const { env } = getCloudflareContext();
const result = await env.AI.run("@cf/meta/llama-3-8b-instruct", { prompt: "Hello" });
```
## Stripe
The default Stripe HTTP client uses `node:https`, which is **not** implemented on Workers. Use the Fetch-based client:
```ts
import Stripe from "stripe";
const stripe = Stripe(process.env.STRIPE_API_KEY!, {
httpClient: Stripe.createFetchHttpClient(),
});
```
No `wrangler.jsonc` or `open-next.config.ts` changes required.
## Sources
- Bindings — https://opennext.js.org/cloudflare/bindings
- How-to: DB (Drizzle, Prisma, D1, Hyperdrive, PG) — https://opennext.js.org/cloudflare/howtos/db
- How-to: Stripe — https://opennext.js.org/cloudflare/howtos/stripeAPI
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |