{"slug":"opennext-cloudflare-deploy-review","name":"OpenNext on Cloudflare Deploy Review","version":"1.0.1","updated_at":"2026-11-22T15:16:16.120Z","use_when":"Reviews the deploy setup of a Next.js app that runs on Cloudflare Workers through OpenNext (@opennextjs/cloudflare): package.json versions and scripts, open-next.config.ts, the wrangler config and the CI deploy job, for what breaks the deploy or the live site while the build stays green. Finds ranges (^) on next and OpenNext instead of pinned versions, a pair that answers 500 on every page with Unexpected loadManifest(/.next/server/preview-props.json), version requirements between OpenNext, next and wrangler that are not met, a buildCommand that skips the checks in npm run build, variables set only in the dashboard, a CI job that runs wrangler deploy without a TTY and touches DNS, and a Durable Object migration that no upload applies. Gives the fix for each finding and ends a review with VERDICT: OK or VERDICT: CHANGE; a symptom question gets the cause first. Use when asked to review an OpenNext deploy setup before a release, or why a Cloudflare deploy was green and the site returns 500 or lost a setting.","not_for":"Next.js on Vercel or any host other than Cloudflare Workers, and anything about how the app itself is written. Edge runtime in a route, a secret set on one environment only and ISR cache mistakes belong to our neighbouring skills. It does not know versions released after its measurements and says so; it is not a security audit of your code; it never runs a deploy or a migration for you.","languages":["any"],"tags":["opennext","cloudflare-workers","nextjs","wrangler","deploy","ci","review"],"category":"code","category_url":"https://aiskills402.com/categories/code","keywords":["wrangler deploy without a TTY","preview-props.json","buildCommand","pinned versions"],"faq":[{"q":"Green build, green deploy, and every page answers 500: how?","a":"A green deploy means the bundle was built and uploaded, nothing more. We measured one pair of Next.js and OpenNext releases that did exactly this: build and upload passed, every page returned 500, and an older Next.js release served fine. The skill treats the two package versions as the main suspect, asks for exact versions instead of ranges, and wants a new release tried on a throwaway Worker first. It also gives the dates of its own measurements so you can see when they need to be repeated."},{"q":"What does it tell me about deploying from CI?","a":"That a deploy command run without a terminal can rewrite the DNS record of a custom domain, so a pipeline should upload a version and then promote it with wrangler versions deploy. It also names the one exception: a change that brings along a Durable Object migration cannot go out by that route, because the version upload will not carry it, and it needs a full deploy from a real terminal after a person has checked what the migration deletes."},{"q":"Does it help Claude Sonnet?","a":"By five inputs, all on version and CI facts. Claude Sonnet saw fifteen inputs of ours twice, bare and with the file: package.json with npm ls, a CI job on two custom domains, build configs, wrangler vars, a Durable Object deletion and four broken-release questions. Bare it got ten. It knew the build-script bypass, dashboard-only flags and lossy tail. It waved through caret ranges on the pair that answers 500, a CI job that rewrites DNS and an OpenNext bump below its wrangler and next floors, and said to run next upgrade --agent=security. With the file: fifteen. Haiku went from six to fifteen."}],"examples":[{"lang":"en","model":"claude-sonnet-5-5","input_excerpt":"Before the deploy I ran `npm run build` and it stopped with `SecurityFatalError`; the message tells me to run\n`next upgrade --agent=security`. Versions in package.json: \"next\": \"16.4.3\", \"eslint-config-next\": \"16.4.3\",\n\"@opennextjs/cloudflare\": \"1.20.13\", \"wrangler\": \"4.150.0\". Should I run that command and then deploy?","output_excerpt":"No, don't run `next upgrade --agent=security`. Upgrade by hand and pin the exact versions.\n\n**Cause:** `next` 16.4.3 is below the 16.4.5 security line, and `next build` stopped on it with `SecurityFatalError`. That command picks the target version for you, which is why it shouldn't be run.…"}],"page_url":"https://aiskills402.com/skills/opennext-cloudflare-deploy-review","markdown_url":"https://aiskills402.com/skills/opennext-cloudflare-deploy-review.md","image_url":"https://cdn.aiskills402.com/og/skills/opennext-cloudflare-deploy-review/47816080.png","related_url":"https://api.aiskills402.com/v1/skills/opennext-cloudflare-deploy-review/related","purchases_count":null,"tested":{"date":"2026-11-22","strong":{"model":"claude-sonnet-5-5 (Claude Code alias \"sonnet\")","verdict":"Right on all 15 inputs on the 1.0.1 bytes, read by hand. It moved the caret ranges on next 16.4.0 with OpenNext 1.20.10 to the pair tried in November, pinned exactly; caught an OpenNext bump to 1.20.16 that left wrangler under 4.148 and next under 16.4.5; split a CI deploy on two custom domains into an upload and wrangler versions deploy; refused next upgrade --agent=security; read the 52 of 79 tail events as no proof of lost requests; called the DOQueueHandler build lines harmless; and answered OK on all five sound setups, including the one without a buildCommand. On the commit that deletes a Durable Object class it said the upload stops with an error naming the pending migration, so the job goes red and no version is made, and sent the commit to one full deploy from a terminal with a TTY. The version facts it used were measured on dates we give (11 October and 17 November 2026) and go stale, and it told the reader to check what is current."},"weak":{"model":"claude-haiku-5-5 (Claude Code alias \"haiku\")","verdict":"Right on all 15 inputs on the 1.0.1 bytes, read by hand. It moved the caret ranges to the tried pair with exact pins, named both version requirements of OpenNext for the bump to 1.20.16, split the CI job on custom domains into an upload and a promote step, kept the dashboard-only flag out of the full deploy by putting it in vars, and refused the security-upgrade prompt. On the commit that deletes a Durable Object class it said the upload refuses the pending migration, the job goes red and no version is made, and asked for one full deploy from a terminal. It answered OK on the default OpenNext build (no buildCommand, so npm run build runs) and on the correct upload-and-promote CI step, without asking for a smoke test. Its version numbers carry the measurement dates of the skill and go stale like them."},"note":"Fifteen inputs written by us: eleven deploy setups pasted before a release (package.json with npm ls, a GitHub Actions job with the wrangler routes, open-next.config.ts, wrangler vars, a commit that deletes a Durable Object class), five of them sound, and four questions about a symptom (500 with loadManifest after npm update, SecurityFatalError, fewer tail events than requests, DOQueueHandler lines during the build). Code scores every answer, with identical checks for both sides: the verdict line for a review, and for each fault the point in any words (an exact pin, a tried pair, DNS together with versions deploy, the versions OpenNext needs, a full deploy from a terminal). Re-checked on 2026-11-22 in the installed sources: wrangler 4.156.0 sets override_existing_dns_record for custom domains when there is no TTY, and its version upload stops with an error while a Durable Object migration is pending; OpenNext runs the package manager's build script when no buildCommand is set. Owner-measured and not re-checked: the 500 of next 16.4.0 with OpenNext 1.20.10 (11 October 2026), next 16.4.6 paired with OpenNext 1.20.17 and serving production since 17 November 2026, the requirements of OpenNext 1.20.13 and 1.20.16 on wrangler and next, SecurityFatalError on 16.4.3, tail losing events, and the DOQueueHandler lines coming from the local proxy. Version facts go stale. Two checks were widened after the run for both sides: the migration check takes 'Neither applies Durable Object migrations' in the sentence after the upload commands, and the build-warning check takes 'comes from the Next.js build step' as the source. After the first run, the wrangler source showed that a pending Durable Object migration makes the upload stop with an error (CI goes red, no version is made), where the skill text had said the push goes green; the wording was fixed on 22 November 2026, with two more 'not a finding' lines (no buildCommand means OpenNext runs npm run build; a CI job without a smoke test). The skill side was then re-run in full on all 15 inputs (the earlier run with the old wording: Sonnet 15 of 15, Haiku 13 of 15). The bare side is unchanged. One run per model and input. Version 1.0.1, 22 November 2026: the version requirements were corrected from the adapter's own peer requirements on npm: wrangler 4.148 is needed from OpenNext 1.20.10 (the file had said 1.20.13), and 1.20.12 needs next 16.4.1, which the file did not say. Three sentences were reworded so that no published post on our blog shares a run of five words with the file. One check was widened for both sides: going back to any OpenNext from 1.20.10 to 1.20.15 meets the next requirement of that input. The side with the skill was run again in full on those bytes: Sonnet 15 of 15, Haiku 15 of 15. The side without the skill, re-scored with the same checks: unchanged, 10 and 6 of 15.","baseline":{"date":"2026-11-22","rows":[{"label":"Inputs judged right (15 inputs)","better":"higher","strong":{"with":{"n":15,"of":15},"without":{"n":10,"of":15}},"weak":{"with":{"n":15,"of":15},"without":{"n":6,"of":15}}}],"note":"Same request on both sides, scored on the point in any words. Read by hand, Sonnet without the skill already knew the build-script bypass of a buildCommand, the loss of dashboard-only values (and keep_vars), lossy wrangler tail, the harmless DOQueueHandler lines, and that a version upload does not apply a Durable Object migration. It missed five measured facts: it approved caret ranges on next 16.4.0 with OpenNext 1.20.10, approved a CI deploy without a TTY on two custom domains and later moved a class deletion into that job, said yes to next upgrade --agent=security, and passed an OpenNext 1.20.16 bump with wrangler 4.140 and next 16.4.3. Haiku without the skill was right on six: the same misses, plus false alarms on four of the five sound setups. With the skill, run again after the wording fix, Haiku was right on all 15 and gave no false alarm on a sound setup."},"report_url":null},"price_usd":"0.05","price_micro":50000,"size_bytes":13857,"sha256":"69a8fdf40df82fa474e14c17949395c476d7e68b9f3e3c6acb62bb59b4fa5b47","outline":["Facts this review rests on","What to check, in this order","1. Exact versions of next and OpenNext","2. The pair and its requirements","3. buildCommand","4. Variables","5. How CI deploys","6. Files that never go into git","Symptom questions","Answer format","Not a finding","What not to do"],"license":{"summary":"Perpetual, non-exclusive; use and modify for yourself incl. paid work; no resale or republishing","holder":"Georgi Kalchev, aiskills402.com","url":"https://aiskills402.com/docs#license"},"buy_url":"https://api.aiskills402.com/v1/skills/opennext-cloudflare-deploy-review/file","redownload_url_template":"https://api.aiskills402.com/v1/purchases/{token}","mcp_tool":null,"payment":{"protocol":"x402","scheme":"exact","asset":"USDC","selling":true,"network":"base","network_caip2":"eip155:8453","pay_to":"0xbc0dcc70d8b5d85541d86ffc68d988fd59c22e68","facilitator":"cdp"},"seo_title":"OpenNext on Cloudflare Deploy Review","seo_description":"Reviews a Next.js app on Cloudflare Workers via OpenNext before deploy: exact versions, tried package pairs, buildCommand, CI, DNS. Pay $0.05 once, in USDC.","versions":[{"version":"1.0.1","date":"2026-11-22","changelog":"# Changelog\n\n## 1.0.1 — 2026-11-22\n\nFact fixed from the peer requirements that @opennextjs/cloudflare declares on npm (read for 1.20.9 to 1.20.18): wrangler 4.148 or later is needed from OpenNext 1.20.10, not from 1.20.13 as the file said, and the floor of next 16.4.1 for OpenNext 1.20.12 onward was missing. Three other sentences reworded with the same meaning, so that no published post on our blog shares a run of five words with the file. One check widened for both sides. The side with the skill was run again in full, one run per model and input: Sonnet 15 of 15, Haiku 15 of 15. Without the skill, re-scored: 10 and 6 of 15, unchanged.\n\n## 1.0.0 — 2026-11-22\n\n- First version.\n- Measured on 15 inputs of ours (11 deploy setups, 5 of them sound, and 4 symptom questions), one run per model and\n  input, scored by code with the same checks on both sides and every failure read by hand: Claude Sonnet 15 of 15 with\n  the skill and 10 of 15 without it; Claude Haiku 13 of 15 with it and 6 of 15 without it.\n- Two checks widened after the run, for both sides, because the answers said the same thing in other words: the\n  migration check now takes \"Neither applies Durable Object migrations\" written in the sentence after the two upload\n  commands, and the build-warning check takes \"comes from the Next.js build step\" as the source of the warning. No input\n  changed and nothing was re-run.\n- Formatting of the skill file only, after the run: the two CI lines moved from a fenced block to an indented one, and\n  three placeholders changed from angle brackets to braces, because the catalog refuses fences and tag-like text. The\n  words are the same; the test ran on the earlier bytes.\n- Price $0.05: Sonnet gained five inputs, on five distinct facts we measured.\n- Wording fix in the skill, 22 November 2026: a pending Durable Object migration makes the upload stop with an error (CI goes red, no version is made), not a green job without the migration, as the first text said; plus two lines on what is not a finding (no buildCommand means OpenNext runs npm run build; a CI job without a smoke test). Skill side re-run in full on the 15 inputs: Claude Sonnet 15 of 15 and Claude Haiku 15 of 15 (the earlier run with the old wording: 15 and 13). Without the skill, unchanged: 10 and 6 of 15. Price stays $0.05.\n"},{"version":"1.0.0","date":"2026-11-22","changelog":"# Changelog\n\n## 1.0.0 — 2026-11-22\n\n- First version.\n- Measured on 15 inputs of ours (11 deploy setups, 5 of them sound, and 4 symptom questions), one run per model and\n  input, scored by code with the same checks on both sides and every failure read by hand: Claude Sonnet 15 of 15 with\n  the skill and 10 of 15 without it; Claude Haiku 13 of 15 with it and 6 of 15 without it.\n- Two checks widened after the run, for both sides, because the answers said the same thing in other words: the\n  migration check now takes \"Neither applies Durable Object migrations\" written in the sentence after the two upload\n  commands, and the build-warning check takes \"comes from the Next.js build step\" as the source of the warning. No input\n  changed and nothing was re-run.\n- Formatting of the skill file only, after the run: the two CI lines moved from a fenced block to an indented one, and\n  three placeholders changed from angle brackets to braces, because the catalog refuses fences and tag-like text. The\n  words are the same; the test ran on the earlier bytes.\n- Price $0.05: Sonnet gained five inputs, on five distinct facts we measured.\n- Wording fix in the skill, 22 November 2026: a pending Durable Object migration makes the upload stop with an error (CI goes red, no version is made), not a green job without the migration, as the first text said; plus two lines on what is not a finding (no buildCommand means OpenNext runs npm run build; a CI job without a smoke test). Skill side re-run in full on the 15 inputs: Claude Sonnet 15 of 15 and Claude Haiku 15 of 15 (the earlier run with the old wording: 15 and 13). Without the skill, unchanged: 10 and 6 of 15. Price stays $0.05.\n"}]}