@alchemy.run/frontend-frameworks/nextjs
Next.js framework integration for Cloudflare Workers — an OpenNext-based build pipeline and two dev-server modes, fully wrangler-free.
buildruns the@opennextjs/cloudflarepipeline in a disposable child process (no wrangler code is ever imported), performs the final bundle pass wrangler would normally do at deploy time, and returns the framework-coreBuildOutput(server modules entry-first + the static-assets directory).devstarts a local server in one of two modes (dev.mode).
Dev modes
"preview" (default) — production parity, no HMR
Builds the OpenNext worker and serves it under
@alchemy.run/cloudflare-runtime/core (workerd) with the OpenNext worker
shape: ASSETS (run-worker-first), a WORKER_SELF_REFERENCE self service
binding, and the same-script SQLite-backed revalidation-queue Durable Object.
What you run is what you deploy. Any change requires a rebuild.
"hmr" — real next dev, Cloudflare bindings proxied
Runs the programmatic next({ dev: true }) custom-server API (Turbopack HMR)
on an http server this package owns, and opens a cloudflare-runtime
platform proxy (our wrangler-free getPlatformProxy equivalent) with the
worker's bindings. The proxy's { env, cf, ctx } is planted on
globalThis[Symbol.for("__cloudflare-context__")] — the exact contract
@opennextjs/cloudflare's getCloudflareContext() reads — and
vm.runInContext is patched so edge-runtime middleware/routes see it too.
App code works without initOpenNextCloudflareForDev() and without wrangler.
import * as Nextjs from "@alchemy.run/frontend-frameworks/nextjs";
const layer = Nextjs.make({
dev: { mode: "hmr" },
vite: {
compatibilityDate: "2026-08-31",
worker: { name: "my-app", bindings: [Text.local("TEST_TEXT", "value")] },
},
}); Fidelity: what "hmr" mode is NOT
"hmr" mode runs your app code in Node.js (and Next's edge-runtime VM
sandbox for middleware/edge routes), not in workerd:
- Cloudflare-specific runtime behavior differs. workerd APIs, runtime
limits,
nodejs_compatshimming,cloudflare:*modules, request lifecycles (waitUntilis a no-op), and thecfobject (a static mock) only behave faithfully in"preview"mode. - Bindings round-trip over a local proxy.
env.*stubs forward method chains to a workerd instance hosting the real local bindings. Method results must be JSON-compatible values, bytes, dates, streams, orDurableObjectIds; rich class returns (e.g.R2Object) andconnect()are not supported (seecloudflare-runtime/platform-proxy). Durable Object classes defined in your app cannot run in this mode (the proxy worker does not host your compiled code). - ISR/caching semantics differ.
next devnever uses the OpenNext incremental-cache/queue/tag-cache overrides — it uses Next's own dev cache. Prerender/ISR behavior,_next/imagevia theIMAGESbinding, and the revalidation queue only exist in"preview"(and production).
Rule of thumb: iterate with "hmr", verify with "preview".
Alchemy source provider
@alchemy.run/frontend-frameworks/nextjs/source implements alchemy's WorkerSourceModule
contract. The descriptor options (NextjsSourceOptions) are JSON-stable and
include dev.mode to select the dev-server mode:
source: {
provider: "@alchemy.run/frontend-frameworks/nextjs/source",
options: { dev: { mode: "hmr" } },
} Notes
- The OpenNext pipeline runs
next buildinternally via a child process (runner.mjs); awranglerstub package (wrangler-stub/) satisfies OpenNext's version probe without installing wrangler. nextitself is resolved from the project'snode_modules, never from a hoisted sibling.
Upstream references
- Next.js:
55d30fb91d8197597c5c400174f1d38a89333de8 - OpenNext for Cloudflare:
da4b7fc8c89441a6f96205635fa70e329d1f0df7