next-ai-draw-io/docs/en/cloudflare-deploy.md

Deploy on Cloudflare Workers

This project can be deployed as a Cloudflare Worker using the OpenNext adapter, giving you:

• Global edge deployment
• Very low latency
• Free workers.dev hosting
• Full Next.js ISR support via R2 (optional)

Important Windows Note: OpenNext and Wrangler are not fully reliable on native Windows. Recommended options:

• Use GitHub Codespaces (works perfectly)
• OR use WSL (Linux)

Pure Windows builds may fail due to WASM file path issues.

---

Prerequisites

1. A Cloudflare account (free tier works for basic deployment)
2. Node.js 18+
3. Wrangler CLI installed (dev dependency is fine):

npm install -D wrangler

4. Cloudflare login:

npx wrangler login

Note: A payment method is only required if you want to enable R2 for ISR caching. Basic Workers deployment is free.

---

Step 1 — Install dependencies

npm install

---

Step 2 — Configure environment variables

Cloudflare uses a different file for local testing.

1) Create .dev.vars (for Cloudflare local + deploy)

cp env.example .dev.vars

Fill in your API keys and configuration.

2) Make sure .env.local also exists (for regular Next.js dev)

cp env.example .env.local

Fill in the same values there.

---

Step 3 — Choose your deployment type

Option A: Deploy WITHOUT R2 (Default, Free)

This is how the repository is configured: open-next.config.ts is defineCloudflareConfig({}) and wrangler.jsonc has no r2_buckets. Nothing to change here. Skip to Step 4.

---

Option B: Deploy WITH R2 (Optional, ISR caching)

R2 gives OpenNext a place to store Incremental Static Regeneration (ISR) pages. This app currently has no ISR pages, so you only need this step if you add some. Requires a payment method on your Cloudflare account.

1. Create an R2 bucket in the Cloudflare Dashboard:

• Go to Storage & Databases → R2
• Click Create bucket
• Name it: next-inc-cache

2. Configure open-next.config.ts:

import { defineCloudflareConfig } from "@opennextjs/cloudflare/config"
import r2IncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/r2-incremental-cache"

export default defineCloudflareConfig({
  incrementalCache: r2IncrementalCache,
})

3. Add r2_buckets to wrangler.jsonc:

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "main": ".open-next/worker.js",
  "name": "next-ai-draw-io-worker",
  "compatibility_date": "2025-12-08",
  "compatibility_flags": ["nodejs_compat", "global_fetch_strictly_public"],
  "assets": {
    "directory": ".open-next/assets",
    "binding": "ASSETS"
  },
  "r2_buckets": [
    {
      "binding": "NEXT_INC_CACHE_R2_BUCKET",
      "bucket_name": "next-inc-cache"
    }
  ],
  "services": [
    {
      "binding": "WORKER_SELF_REFERENCE",
      "service": "next-ai-draw-io-worker"
    }
  ]
}

Important: The bucket_name must exactly match the name you created in the Cloudflare dashboard.

Note: Time-based revalidation (revalidate on a page or fetch) also needs a queue in open-next.config.ts. See the OpenNext Cloudflare caching docs.

---

Step 4 — Register a workers.dev subdomain (first-time only)

Before your first deployment, you need a workers.dev subdomain.

Option 1: Via Cloudflare Dashboard (Recommended)

Visit: https://dash.cloudflare.com → Workers & Pages → Overview → Set up a subdomain

Option 2: During deploy

When you run npm run deploy, Wrangler may prompt:

Would you like to register a workers.dev subdomain? (Y/n)

Type Y and choose a subdomain name.

Note: In CI/CD or non-interactive environments, the prompt won't appear. Register via the dashboard first.

---

Step 5 — Deploy to Cloudflare

npm run deploy

What the script does:

• Builds the Next.js app
• Converts it to a Cloudflare Worker via OpenNext
• Uploads static assets
• Publishes the Worker

Your app will be available at:

https://<worker-name>.<your-subdomain>.workers.dev

---

Common issues & fixes

You need to register a workers.dev subdomain

Cause: No workers.dev subdomain registered for your account.

Fix: Go to https://dash.cloudflare.com → Workers & Pages → Set up a subdomain.

---

Please enable R2 through the Cloudflare Dashboard

Cause: R2 is configured in wrangler.jsonc but not enabled on your account.

Fix: Either enable R2 (requires payment method) or use Option A (deploy without R2).

---

No R2 binding "NEXT_INC_CACHE_R2_BUCKET" found

Cause: r2_buckets is missing from wrangler.jsonc.

Fix: Add the r2_buckets section or switch to Option A (without R2).

---

Can't set compatibility date in the future

Cause: compatibility_date in wrangler config is set to a future date.

Fix: Change compatibility_date to today or an earlier date.

---

Windows error: resvg.wasm?module (ENOENT)

Cause: Windows filenames cannot include ?, but a wasm asset uses ?module in its filename.

Fix: Build/deploy on Linux (WSL, Codespaces, or CI).

---

Optional: Preview locally

Preview the Worker locally before deploying:

npm run preview

---

Summary

Feature	Without R2	With R2
Cost	Free	Requires payment method
ISR Caching	No	Yes
Static Pages	Yes	Yes
API Routes	Yes	Yes
Setup Complexity	Simple	Moderate

The repository defaults to without R2. Choose with R2 only if you add pages that need ISR caching.